---
url: /reference/CLIENT_INTEGRATION.md
---
# Client Integration Guide

What a front-end or integration team needs to call the API: the verified route
counts, the shared conventions, the error codes, the permission each route
needs, the business-day and regional-profile rules, and what is not built. OpenAPI
wins for the shape of a route, the code for behavior.

## 1. Verified route counts

Counted from `docs/generated/openapi.json` at baseline revision 200
(migrations through `0175`), one operation per method and path, grouped by the
first OpenAPI tag. Recount command:

```bash
node -e 'const s=JSON.parse(require("fs").readFileSync("docs/generated/openapi.json"));const c={};let t=0;for(const o of Object.values(s.paths))for(const k of ["get","post","put","patch","delete"])if(o[k]){t++;const g=o[k].tags[0];c[g]=(c[g]||0)+1}console.log(t,Object.keys(s.paths).length,c)'
```

316 operations on 258 paths (292 and 238 at revision 190: 24 new operations; 259 and 212 at revision 178).

| Group (OpenAPI tag)     | Operations |
| ----------------------- | ---------: |
| Catalog                 |        138 |
| Platform administration |         23 |
| Pricing                 |         14 |
| Inventory               |         11 |
| Operations              |         10 |
| Outlets                 |         10 |
| Memberships             |          9 |
| Sign-in and sessions    |          8 |
| Assets                  |          7 |
| Business units          |          6 |
| Invitations             |          6 |
| Legal entities          |          6 |
| Approvals               |          5 |
| Organizations           |          5 |
| Roles                   |          5 |
| Sign-in methods         |          5 |
| Brands                  |          4 |
| Outlet groups           |          4 |
| Password                |          4 |
| Schedules               |          4 |
| Second factors          |          4 |
| Sites                   |          4 |
| Sales channels          |          3 |
| Settings                |          3 |
| Step-up                 |          3 |
| Health                  |          2 |
| Onboarding              |          2 |
| Recovery codes          |          2 |
| Sales                   |          2 |
| Sign-up                 |          2 |
| Audit                   |          1 |
| Plans                   |          1 |
| Reference               |          1 |
| Reference data          |          1 |
| Subscription            |          1 |
| **Total**               |    **316** |

Only the two health probes are unversioned; the rest is under `/api/v1`. Eleven
operations need no session (sign-up, sign-in, renewal, second factor, password
recovery, provider nonces, plan catalog, probes); the other 305 need a bearer
session.

## 2. Conventions

The contract is [`FOUNDATION_HTTP_AND_OBSERVABILITY.md`](../contracts/FOUNDATION_HTTP_AND_OBSERVABILITY.md);
this is the short form.

| Topic               | Rule                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authentication      | `Authorization: Bearer <accessToken>` from `POST /sign-ins`; a missing or expired session is `401 identity.session_required`                                                                                                                                                                                                                                                                                                                                                                         |
| Tenant              | Routes of an organization need `X-Organization-Id`; an organization the caller does not belong to is `403 tenant.context_rejected`                                                                                                                                                                                                                                                                                                                                                                   |
| Envelope            | Success is `{ "data": ..., "meta"? }`; lists carry `meta.pageInfo`                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Pagination          | Keyset cursors only: `limit` (1 to 100, default 50), `after`, `before`; cursors are opaque and signed; a bad one is `400 collection.cursor_invalid`, `_tampered`, `_expired` or `_incompatible` (a cursor replayed with other filters). 24 operations take `limit`                                                                                                                                                                                                                                   |
| Idempotency         | `Idempotency-Key` (a UUID) is required on 39 operations: 13 creates of Catalog, `POST /organizations`, `POST /organization/onboarding`, `POST /memberships/{id}/ownership-grants`, `POST /assets/uploads`, `POST /outlets/{outletId}/sales` and the platform staff commands. Same key and same request replays the first answer with `Idempotent-Replayed: true`; same key with another request is `409 idempotency.key_reused`; a concurrent first use is `409 idempotency.in_progress` (retryable) |
| ETag and `If-Match` | Reads that change slowly return an `ETag` and accept `If-None-Match` (`304`, no body). Writes accept `If-Match` (104 operations declare it); a stale tag is `412 foundation.precondition_failed`, and whole-collection `PUT` routes require it (`428 precondition.required`)                                                                                                                                                                                                                         |
| Lifecycle           | A resource changes state with `POST .../transitions` and a closed `transition` value, never a bare status                                                                                                                                                                                                                                                                                                                                                                                            |
| Money               | Decimal strings, never numbers. Sales answers six-decimal strings                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Errors              | `application/problem+json` (RFC 9457) with `type`, `title`, `status`, `detail`, `instance`, `code`, `traceId`. React to `code`, not to `detail`                                                                                                                                                                                                                                                                                                                                                      |

### Shared error codes

| Status    | Code                                                                                  | Retryable          |
| --------- | ------------------------------------------------------------------------------------- | ------------------ |
| 400       | `foundation.validation_failed` (field errors in `meta.errors`), `collection.cursor_*` | no                 |
| 401       | `identity.session_required`, `auth.unauthenticated`                                   | no                 |
| 403       | `auth.unauthorized`, `tenant.context_rejected`                                        | no                 |
| 404       | `resource.not_found`                                                                  | no                 |
| 409       | `conflict.business`, `idempotency.key_reused`, `idempotency.in_progress`              | only `in_progress` |
| 412 / 428 | `foundation.precondition_failed`, `precondition.required`                             | no                 |
| 413 / 415 | `payload.too_large`, `media_type.unsupported`                                         | no                 |
| 422       | `content.unprocessable`                                                               | no                 |
| 429       | `rate_limit.exceeded` (with `Retry-After`)                                            | yes                |
| 500 / 503 | `foundation.internal_error`, `service.unavailable`                                    | 503 yes            |

Module codes are in the problem responses of each operation in OpenAPI. The
newest ones:

| Area            | Codes                                                                                                                                                                                                                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sales           | `sales.action_forbidden` (403), `sales.order_not_found` (404), `sales.insufficient_stock` (409), `sales.currency_mismatch` (409), `sales.lines_not_sellable` (422), `sales.order_refused` (422, reason in `detail`)                                                                               |
| Pricing         | `pricing.action_forbidden` (403), `pricing.price_schedule_conflict` (409), `pricing.price_list_refused` (422)                                                                                                                                                                                     |
| Plan limits     | `organization.plan_limit_reached` (409): creating or reactivating a site, business unit or outlet beyond the plan; also onboarding                                                                                                                                                                |
| Onboarding      | `organization.first_run_conflict` (409), `organization.structure_refused` (422)                                                                                                                                                                                                                   |
| Structure       | `organization.action_forbidden` (403), `organization.structure_not_found` (404), `organization.structure_code_taken`, `organization.structure_in_use`, `organization.assignment_conflict` (409), `organization.structure_refused` (422)                                                           |
| Settings        | `settings.action_forbidden` (403), `settings.scope_not_found`, `settings.setting_not_found` (404), `settings.locked_by_parent` (409), `settings.value_invalid` (422)                                                                                                                              |
| Approvals       | `identity.approval_denied` (403, every wrong PIN case alike), `identity.approval_not_required` (409), `identity.approval_rule_refused` (422)                                                                                                                                                      |
| Ownership grant | `identity.elevation_required` (403), `identity.membership_not_found` (404), `identity.ownership_grant_refused` (422)                                                                                                                                                                              |
| Roles and team  | `identity.action_forbidden`, `identity.role_read_only`, `identity.role_assignment_privilege_exceeded`, `identity.invitation_privilege_exceeded` (403), `identity.role_not_found` (404), `identity.role_in_use`, `identity.role_already_assigned` (409), `identity.role_permissions_unknown` (422) |
| Locations       | `inventory.action_forbidden` (403), `inventory.location_not_found` (404), `inventory.location_code_taken`, `inventory.location_in_use` (409), `inventory.location_refused` (422)                                                                                                                  |
| Audit           | `audit.action_forbidden` (403)                                                                                                                                                                                                                                                                    |

## 3. Permission each route needs

A permission is checked at a scope: organization-wide, or at the outlet or
business unit named by the route. A caller without it gets `403` with the
module's `action_forbidden` code; routes that name an outlet answer the same
`403` for an unknown or foreign outlet. Roles and permissions:
[`ACCESS_USE_CASES.md`](ACCESS_USE_CASES.md). The permission is taken from the
operation description in OpenAPI.

Catalog (138 operations): `catalog.items.view` (33 operations),
`catalog.items.manage` (76), `catalog.assortment.manage` (4),
`catalog.catalogs.manage` (5), `catalog.sellables.view` (5),
`catalog.change_sets.read` (2, and 2 more that also need
`catalog.sellables.view`), `catalog.change_sets.write` (5),
`catalog.change_sets.publish` (1). Five operations (duplications, nutrition
reads) do not state it and follow the item permissions.

Everything else, by permission:

| Permission                                         | Routes                                                                                                                                                                                                                                                                                                                   |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `organization.account.manage`                      | organization profile and structure reads, brands, business units, legal entities, sites, outlets, invitations, memberships, roles, role assignments, permissions, approval settings                                                                                                                                      |
| `organization.structure.view` / `.manage`          | structure reads and writes at a scope (sites and outlets `PATCH`, deactivation, `POST /outlets`), outlet groups, schedules, sales channels, legal entity read and tax identifiers, onboarding and setup; `organization.account.manage` also counts                                                                       |
| `identity.team.manage`                             | accepted by the code on invitations, member list, member control and role assignments (OpenAPI still names only `organization.account.manage`; scoped use not verified)                                                                                                                                                  |
| `settings.assignments.view` / `.manage`            | `GET /settings`; `PUT`, `DELETE /settings/{code}/assignment`                                                                                                                                                                                                                                                             |
| `inventory.locations.view` / `.manage`             | `GET`, `POST`, `PATCH /locations`, deactivation, reactivation, `PUT /outlets/{id}/issue-location-rules`                                                                                                                                                                                                                  |
| `audit.events.view`                                | `GET /audit-events`                                                                                                                                                                                                                                                                                                      |
| `pricing.prices.view` / `.manage`                  | `GET /price-list`, items and history reads, `GET /pricing/books`, `GET /pricing/rules`, `POST /pricing/resolve` / `PUT`, `PATCH /price-list`, `POST`, `PATCH /pricing/books`, `PUT /pricing/books/{id}/assignments`, `PUT /pricing/books/{id}/option-prices`, `POST`, `PATCH /pricing/rules`                             |
| `operations.quotas.view` / `.manage` / `.override` | `GET /operations/pools`, `GET /operations/pools/{id}/status` / `POST /operations/pools`, `PUT .../members`, `POST`, `PATCH .../rules` / the approval that lets a sale go past a blocking quota pool                                                                                                                      |
| `operations.availability.view` / `.block`          | `GET /outlets/{id}/availability`, `POST .../availability/check` / `POST`, `DELETE /catalog/outlets/{id}/blocks`                                                                                                                                                                                                          |
| `inventory.supply_routes.view` / `.manage`         | `GET /inventory/supply-routes`, `GET .../{variantId}`, `GET /outlets/{id}/variants/{variantId}/supply` / `PUT /inventory/supply-routes/{variantId}`, `POST .../routes/{routeId}/end`                                                                                                                                     |
| `sales.orders.take` / `.read`                      | `POST` / `GET /outlets/{id}/sales`                                                                                                                                                                                                                                                                                       |
| `assets.media.view` / `.manage`                    | `GET /assets`, `GET /assets/{id}` / uploads, `PATCH`, archival, restoration                                                                                                                                                                                                                                              |
| a session only                                     | `GET /reference/metadata`, `GET /service-modes`, `GET /plans`, `GET /subscription`, `GET /organizations`, `POST /organizations`, `POST /approvals`, `GET /approvals/can-approve`, `PUT /memberships/{own id}/pin`, invitation preview and acceptance, sign-in methods, second factors, recovery codes, password, step-up |
| elevation                                          | `POST /memberships/{id}/ownership-grants` needs an organization-wide administrator and a live step-up                                                                                                                                                                                                                    |

The 23 `platform-admin` operations are for Ninaku staff and need a staff actor
and a live step-up; they are not part of a tenant client.

### The 33 routes added since revision 178

| Area       | Routes                                                                                                                                                                                                                                                                                                                        |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Reference  | `GET /reference/metadata`, `GET /service-modes`                                                                                                                                                                                                                                                                               |
| Settings   | `GET /settings`, `PUT`, `DELETE /settings/{code}/assignment`                                                                                                                                                                                                                                                                  |
| Audit      | `GET /audit-events`                                                                                                                                                                                                                                                                                                           |
| Locations  | `GET`, `POST /locations`, `PATCH /locations/{id}`, `.../deactivation`, `.../reactivation`, `PUT /outlets/{id}/issue-location-rules`                                                                                                                                                                                           |
| Onboarding | `POST /organization/onboarding`, `GET /organization/setup`                                                                                                                                                                                                                                                                    |
| Structure  | `GET`, `POST /sales-channels`, `PATCH /sales-channels/{id}`, `GET`, `POST /outlet-groups`, `PATCH /outlet-groups/{id}`, `PUT /outlet-groups/{id}/members`, `GET`, `POST /schedules`, `PUT /schedules/{id}/windows`, `GET /schedules/{id}/occurrences`, `GET /legal-entities/{id}`, `PUT /legal-entities/{id}/tax-identifiers` |
| Access     | `POST /memberships/{id}/ownership-grants`, `POST /approvals`, `GET /approvals/can-approve`                                                                                                                                                                                                                                    |
| Pricing    | `PATCH /price-list`, `GET /price-list/items/{itemId}`, `GET /price-list/variants/{variantId}/history`                                                                                                                                                                                                                         |

### The 24 routes added by the unlock slice (revisions 191 to 200)

| Area                 | Routes                                                                                                                                                              |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Price books          | `GET`, `POST /pricing/books`, `PATCH /pricing/books/{id}`, `PUT /pricing/books/{id}/assignments`, `PUT /pricing/books/{id}/option-prices`                           |
| Price rules and cart | `GET`, `POST /pricing/rules`, `PATCH /pricing/rules/{id}`, `POST /pricing/resolve`                                                                                  |
| Quotas               | `GET`, `POST /operations/pools`, `PUT /operations/pools/{id}/members`, `POST`, `PATCH /operations/pools/{id}/rules`, `GET /operations/pools/{id}/status`            |
| Availability         | `GET /outlets/{id}/availability`, `POST /outlets/{id}/availability/check`, `POST /catalog/outlets/{id}/blocks`, `DELETE /catalog/outlets/{id}/blocks/{blockId}`     |
| Supply routes        | `GET /inventory/supply-routes`, `GET`, `PUT /inventory/supply-routes/{variantId}`, `POST .../routes/{routeId}/end`, `GET /outlets/{id}/variants/{variantId}/supply` |

Every `etag` and `membersEtag` in a body is already quoted: send it as it is in
`If-Match` (`PUT /operations/pools/{id}/members` takes the `membersEtag` of the
pool list or of its last answer, which is also the `ETag` of that answer).

`POST /pricing/resolve` is also open to a member holding `sales.orders.take` at
the outlet of the cart (a cashier quotes the cart it will sell); a grant at
another outlet or `pricing.prices.view` scoped below the organization is `403`.

`POST /outlets/{id}/sales` changed: the body carries no price; each line takes
`options` and `bundleChoices`, the order takes `channelId`, `serviceMode`,
`menuId` and `overrides`; the answer carries the priced lines, `serviceMode`,
`warnings` and, per line, the `options` and `bundleChoices` chosen (also in
`GET /outlets/{id}/sales/{orderId}`). A variant without a price in the books that apply is
refused (`422 sales.price_unresolvable`); an explicit price of `0` sells. A
combo line without a required choice is `422` (`sales.order_refused` or
`sales.lines_not_sellable`). `PATCH /price-list` takes an optional `bookId`.

Flows and diagrams: [`SYSTEM_FLOWS.md`](SYSTEM_FLOWS.md).

## 4. Business day and regional profile

Each outlet has a regional profile (`organization.outlet_regional_profile`):
country and time zone from its site; currency and locale from the site
override, otherwise from the organization.

* A sale is made in the currency of the outlet. The request has no currency.
* The price list is per currency (`currency` in `GET`, `PUT`, `PATCH /price-list`).
* `businessDate` of an order is `(now in the site time zone - cutoff)::date`.
  The cutoff is the setting `operations.business_day.cutoff_minutes` (0 to
  1439, default 0), resolved outlet, outlet group, business unit, organization.
  With a 02:00 cutoff, 01:30 belongs to the previous business day.
* `PATCH /organization` sets default currency and locale; `POST`, `PATCH /sites`
  set country, time zone and the optional currency and locale override
  (`null` inherits again); `PUT /settings/{code}/assignment` sets the cutoff.
* No route reads `Accept-Language`. Catalog reads take a `locale` query
  parameter; offered languages: `GET /catalog/offered-locales`
  ([`CURRENCY_AND_LANGUAGE.md`](CURRENCY_AND_LANGUAGE.md)).

## 5. Built in SQL only, no REST route

| Area                                          | In the database                                                                                                                                     |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Goods receiving with lots, expiry and serials | `inventory.receive_stock` (`inventory.stock.receive`)                                                                                               |
| Stock truth                                   | Reservations, ledger guards, negative-stock mode (the mode is a setting, readable and writable over REST); supply routes are administered over REST |
| Consuming an approval                         | `identity.require_approval`; no business route calls it yet (settings, PIN and granting are REST)                                                   |

## 6. Not built

* Payments and cash movements, the till and cash shifts, credit and receivables.
* Promotions and discounts.
* Receiving and purchase orders over REST (built on unmerged branches).
* Order cancellation, returns, order lists and search.

E-invoicing and country tax calculation are an external service. This API only
holds configuration (legal entity tax identifiers) and a sale carries no tax.
`docs/generated/openapi.json` is the list of what exists.

## 7. Roadmap

The ordered release plan (R1 to R6) is kept outside this repository. R1, the
foundation, is merged. The phase order is in [`ROADMAP.md`](ROADMAP.md).
