Skip to content

PoS integration

The Posto PoS is a desktop app for the till. It works offline: it keeps the catalog in a local database and sends its writes later. It uses the same API as every other client. This page shows what the app sends, so you can read its data in the API and understand its errors.

The PoS signs in as the OAuth app posto-pos. Read Authentication for OAuth apps in general.

Setting Value
Client type Native, public. It has no secret.
Grant Authorization code with PKCE (S256), and refresh tokens
Redirect http://127.0.0.1/callback, on any port
Scopes openid, profile, offline_access, retail:read, retail:write, masters:read, sales:read
Consent No consent page: it is a Posto app
  1. The app reads the discovery document at /.well-known/openid-configuration on the issuer. It takes the authorization endpoint and the token endpoint from it.
  2. The app starts a listener on http://127.0.0.1:<free port>/callback.
  3. The app opens the system browser at the authorization endpoint. It sends response_type=code, the PKCE challenge, a state and prompt=select_account.
  4. In the browser, the cashier signs in. With a session in the browser, the browser first shows the account: the cashier continues, or signs in with another account.
  5. A user with more than one tenant selects the tenant.
  6. The browser returns to the listener with the code.
  7. The app sends the code and the PKCE verifier to the token endpoint. The answer has the access token, the refresh token and the tenant (id, slug and name).
  8. The app calls /api/v1/<tenant slug>/... with the access token.

The cashier must be assigned to the register. An owner can work on every register. An admin can too, with an access role that grants “Work on any till”. GET /api/v1/<tenant>/retail/pos/mine returns the register of the caller, or 404 when the caller has no register.

  • The app refreshes with grant_type=refresh_token. Each refresh gives a new refresh token.
  • A second refresh with the same token within 60 seconds ends no sign-in. So the app can retry a refresh after a lost answer.
  • When an admin revokes the device, a refresh gets invalid_grant with "device_revoked": true. Then the app deletes the data of the cashiers and goes back to the device setup.

Each write of the till goes into the outbox first: a queue in the local database of the app. The app sends the queue in order when it is online.

A sale is three kinds of writes. The printer prints the receipt first, then the app sends:

  1. POST /retail/pos/transactions: the bill, with its own id, the register and the register time at.
  2. POST /retail/pos/transactions/:id/items: one write for each line, each with its own id.
  3. POST /retail/pos/transactions/:id/fiscalize: the payments and the numbers of the printer.

The day actions of the register also go through the outbox:

Action Route
Start of day POST /retail/pos/:posId/start-of-day
Cash in, cash out POST /retail/pos/:posId/cash-float/add, POST /retail/pos/:posId/cash-float/remove
End of day POST /retail/pos/:posId/end-of-day
Storno POST /retail/pos/transactions/:id/refund, then the fiscalize of the storno bill

A write of the till has at, the time on the register clock in ISO 8601 with an offset, for example 2026-11-13T09:41:00+01:00. The date part of at is the date of the bill or the end of day. A time more than 5 minutes after the server time gets 422.

The app makes the id of each new record. A second send of the same write does not make a second record. The server answers a second fiscalize of the same bill with the bill as it is.

The app sends the writes of one record in order. A write that waits holds back the later writes of the same record. Other records go on.

Answer of the server What the app does
No network Stops the pass and tries again later. The wait grows from 1 second to 1 minute.
401 Refreshes the token and sends again. Without a valid token, the write waits.
500 Tries the write again later
409 from a lock Tries again, up to 3 times
409 on a create Reads the record. If it exists, the create is done.
404 on a delete The delete is done
403 tenant_suspended Keeps the writes and sends them after the tenant is active again
Another error, for example 403, 422 or 429 Marks the write as stuck

The server refused a stuck write. It waits in the outbox, and it holds back the later writes of its record. The till never drops it alone:

  • The cashier sees the stuck writes in the outbox view of the app.
  • After someone fixes the cause in the ERP, the cashier sends the write again.
  • The app reports its outbox to the server after each change, and every 15 minutes, with PUT /retail/pos/:posId/outbox-state. The report has counts, the kind and the error text of the stuck writes, and no bill content or amounts.
  • A Posto platform administrator can tell the till to discard a stuck write. The till discards it with the later writes of its record. It never discards a start of day, a cash move or an end of day.

The printer fiscalizes the receipt. The server only records the numbers.

  1. At each start, and before each start of day, the app reads the printer. It sends the fiscal memory serial and the model to POST /retail/pos/:posId/device.
  2. The app prints the receipt on the printer.
  3. The app sends POST /retail/pos/transactions/:id/fiscalize with the payments, fiscalReceiptNumber, allReceiptNumber, the time at and the fmSerial of the printer.
  4. At the end of day, the app sends the number of the Z report (zReportNumber) and the fmSerial.

The device route answers:

Case Answer
The same printer as the register has 200
A new printer on a register without one 201. The server creates the device and binds it.
Another printer 409 with details of the move. A user with the write right on Tills (masters.pos) confirms it with "confirmMove": true.