# Paloma365 Platform API

> REST API (OAuth 2.1 with PKCE) for third-party apps that read and write data of a Paloma365 business with the owner's consent: profile, locations, taxes, catalog, menus, stop list, orders, customers, staff, sales. This host serves the CIS (Paloma365, KZT and other local currencies, VAT usually included in prices) market; API base URL: https://sandbox-api.paloma365.com/platform/v1

- Start here: https://sandbox-api.paloma365.com/platform/ — the step-by-step page for people (the same steps as below, with links).
- Two ways to get a token for the same endpoints: an OAuth app (you register it yourself in the dashboard — https://sandbox.paloma365.com → Settings → Developers, keys at once, no review; works for any business whose owner consents) or a personal integration key `ppik_…` that a business owner creates in the dashboard for their own account (Connected apps → Create integration; no registration, no OAuth, no expiry). Both are sent as `Authorization: Bearer …`.
- Ids are strings, money is a decimal string with two decimals plus a `currency` field, times are ISO 8601 with an offset.
- Lists page with `limit`/`cursor`; incremental sync with `since=<sync_token>` returns changes including deletions.
- Every order-changing POST needs an `Idempotency-Key` header. The server prices orders; a cart it cannot price is refused with 422 `quote_unsupported`.
- Webhooks are not available in v1: poll `GET /v1/orders?since=` for status changes.
- Payment systems (banks, acquirers, gateways) can take payments for QR menu online orders on their own: register as a payment provider (`payments:process`), receive signed payment sessions at your URL and resolve them — guide section 9.6; sandbox and going live — section 9.7.
- PalomaPOS (USA) businesses are served by https://alfaposapi.palomapos.com/platform — a separate app registration.
- Contact (questions; a review that lists a payment provider for every business of the market): info@paloma365.com. Before offering order creation to a business, check `capabilities.order_writes` in `GET /v1/account`.
- This is the TEST host (sandbox): test accounts and data only, same code and contract as production, no SLA. Production hosts: https://alfaposapi.palomapos.com/platform (USA) and https://alfaposapi.paloma365.com/platform (CIS); production keys are created separately in the market dashboard (https://dashboard.paloma365.com, https://dashboard.palomapos.com).
- Self-service: register a free test business at https://sandbox.paloma365.com/register, sign in as its owner and create your app in Settings → Developers («Настройки → Разработчикам» in the Russian interface, https://sandbox.paloma365.com/settings/developer-apps) — client_id, client_secret (and ppss_… for payment providers) at once, no review.
- Payment providers: `POST /v1/sandbox/payment-sessions` sends you a test payment session right now and checks your endpoint (signature, contract, retry); `GET /v1/sandbox/payment-readiness` says what is left before production — guide section 9.7.

## Docs

- [Integration guide](https://sandbox-api.paloma365.com/platform/v1/guide.md): OAuth, conventions, pagination and sync, idempotency, rate limits, orders, errors, and a checklist for AI coding agents
- [OpenAPI 3.1 description](https://sandbox-api.paloma365.com/platform/v1/openapi.json): every operation, schema, error and example
- [API reference](https://sandbox-api.paloma365.com/platform/v1/docs): the same description rendered as a web page

## Optional

- [OAuth authorization endpoint](https://sandbox-api.paloma365.com/platform/oauth/authorize): opened in the owner's browser (Authorization Code + PKCE S256)
- [OAuth token endpoint](https://sandbox-api.paloma365.com/platform/oauth/token): `authorization_code` and `refresh_token` grants, client_secret_basic or client_secret_post
- [OAuth revocation endpoint](https://sandbox-api.paloma365.com/platform/oauth/revoke): RFC 7009; revoking a refresh token disconnects the app