Skip to content

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
Catalog138
Platform administration23
Pricing14
Inventory11
Operations10
Outlets10
Memberships9
Sign-in and sessions8
Assets7
Business units6
Invitations6
Legal entities6
Approvals5
Organizations5
Roles5
Sign-in methods5
Brands4
Outlet groups4
Password4
Schedules4
Second factors4
Sites4
Sales channels3
Settings3
Step-up3
Health2
Onboarding2
Recovery codes2
Sales2
Sign-up2
Audit1
Plans1
Reference1
Reference data1
Subscription1
Total316

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.

TopicRule
AuthenticationAuthorization: Bearer <accessToken> from POST /sign-ins; a missing or expired session is 401 identity.session_required
TenantRoutes of an organization need X-Organization-Id; an organization the caller does not belong to is 403 tenant.context_rejected
EnvelopeSuccess is { "data": ..., "meta"? }; lists carry meta.pageInfo
PaginationKeyset 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
IdempotencyIdempotency-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-MatchReads 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)
LifecycleA resource changes state with POST .../transitions and a closed transition value, never a bare status
MoneyDecimal strings, never numbers. Sales answers six-decimal strings
Errorsapplication/problem+json (RFC 9457) with type, title, status, detail, instance, code, traceId. React to code, not to detail

Shared error codes ​

StatusCodeRetryable
400foundation.validation_failed (field errors in meta.errors), collection.cursor_*no
401identity.session_required, auth.unauthenticatedno
403auth.unauthorized, tenant.context_rejectedno
404resource.not_foundno
409conflict.business, idempotency.key_reused, idempotency.in_progressonly in_progress
412 / 428foundation.precondition_failed, precondition.requiredno
413 / 415payload.too_large, media_type.unsupportedno
422content.unprocessableno
429rate_limit.exceeded (with Retry-After)yes
500 / 503foundation.internal_error, service.unavailable503 yes

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

AreaCodes
Salessales.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)
Pricingpricing.action_forbidden (403), pricing.price_schedule_conflict (409), pricing.price_list_refused (422)
Plan limitsorganization.plan_limit_reached (409): creating or reactivating a site, business unit or outlet beyond the plan; also onboarding
Onboardingorganization.first_run_conflict (409), organization.structure_refused (422)
Structureorganization.action_forbidden (403), organization.structure_not_found (404), organization.structure_code_taken, organization.structure_in_use, organization.assignment_conflict (409), organization.structure_refused (422)
Settingssettings.action_forbidden (403), settings.scope_not_found, settings.setting_not_found (404), settings.locked_by_parent (409), settings.value_invalid (422)
Approvalsidentity.approval_denied (403, every wrong PIN case alike), identity.approval_not_required (409), identity.approval_rule_refused (422)
Ownership grantidentity.elevation_required (403), identity.membership_not_found (404), identity.ownership_grant_refused (422)
Roles and teamidentity.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)
Locationsinventory.action_forbidden (403), inventory.location_not_found (404), inventory.location_code_taken, inventory.location_in_use (409), inventory.location_refused (422)
Auditaudit.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:

PermissionRoutes
organization.account.manageorganization profile and structure reads, brands, business units, legal entities, sites, outlets, invitations, memberships, roles, role assignments, permissions, approval settings
organization.structure.view / .managestructure 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.manageaccepted 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 / .manageGET /settings; PUT, DELETE /settings/{code}/assignment
inventory.locations.view / .manageGET, POST, PATCH /locations, deactivation, reactivation, PUT /outlets/{id}/issue-location-rules
audit.events.viewGET /audit-events
pricing.prices.view / .manageGET /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 / .overrideGET /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 / .blockGET /outlets/{id}/availability, POST .../availability/check / POST, DELETE /catalog/outlets/{id}/blocks
inventory.supply_routes.view / .manageGET /inventory/supply-routes, GET .../{variantId}, GET /outlets/{id}/variants/{variantId}/supply / PUT /inventory/supply-routes/{variantId}, POST .../routes/{routeId}/end
sales.orders.take / .readPOST / GET /outlets/{id}/sales
assets.media.view / .manageGET /assets, GET /assets/{id} / uploads, PATCH, archival, restoration
a session onlyGET /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
elevationPOST /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 ​

AreaRoutes
ReferenceGET /reference/metadata, GET /service-modes
SettingsGET /settings, PUT, DELETE /settings/{code}/assignment
AuditGET /audit-events
LocationsGET, POST /locations, PATCH /locations/{id}, .../deactivation, .../reactivation, PUT /outlets/{id}/issue-location-rules
OnboardingPOST /organization/onboarding, GET /organization/setup
StructureGET, 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
AccessPOST /memberships/{id}/ownership-grants, POST /approvals, GET /approvals/can-approve
PricingPATCH /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) ​

AreaRoutes
Price booksGET, POST /pricing/books, PATCH /pricing/books/{id}, PUT /pricing/books/{id}/assignments, PUT /pricing/books/{id}/option-prices
Price rules and cartGET, POST /pricing/rules, PATCH /pricing/rules/{id}, POST /pricing/resolve
QuotasGET, POST /operations/pools, PUT /operations/pools/{id}/members, POST, PATCH /operations/pools/{id}/rules, GET /operations/pools/{id}/status
AvailabilityGET /outlets/{id}/availability, POST /outlets/{id}/availability/check, POST /catalog/outlets/{id}/blocks, DELETE /catalog/outlets/{id}/blocks/{blockId}
Supply routesGET /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 (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).

5. Built in SQL only, no REST route ​

AreaIn the database
Goods receiving with lots, expiry and serialsinventory.receive_stock (inventory.stock.receive)
Stock truthReservations, ledger guards, negative-stock mode (the mode is a setting, readable and writable over REST); supply routes are administered over REST
Consuming an approvalidentity.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.

Application Foundation in progress. Tracked in issue #13.