Appearance
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; 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. 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.
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 (
currencyinGET,PUT,PATCH /price-list). businessDateof an order is(now in the site time zone - cutoff)::date. The cutoff is the settingoperations.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 /organizationsets default currency and locale;POST,PATCH /sitesset country, time zone and the optional currency and locale override (nullinherits again);PUT /settings/{code}/assignmentsets the cutoff.- No route reads
Accept-Language. Catalog reads take alocalequery parameter; offered languages:GET /catalog/offered-locales(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.