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 OAuth client posto-pos
Section titled “The OAuth client posto-pos”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 |
The sign-in flow
Section titled “The sign-in flow”- The app reads the discovery document at
/.well-known/openid-configurationon the issuer. It takes the authorization endpoint and the token endpoint from it. - The app starts a listener on
http://127.0.0.1:<free port>/callback. - The app opens the system browser at the authorization endpoint. It sends
response_type=code, the PKCE challenge, astateandprompt=select_account. - 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.
- A user with more than one tenant selects the tenant.
- The browser returns to the listener with the code.
- 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,slugandname). - 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.
Refresh tokens
Section titled “Refresh tokens”- 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_grantwith"device_revoked": true. Then the app deletes the data of the cashiers and goes back to the device setup.
The outbox
Section titled “The outbox”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.
What the till sends
Section titled “What the till sends”A sale is three kinds of writes. The printer prints the receipt first, then the app sends:
POST /retail/pos/transactions: the bill, with its ownid, the register and the register timeat.POST /retail/pos/transactions/:id/items: one write for each line, each with its ownid.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 |
Register time
Section titled “Register time”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.
Retries
Section titled “Retries”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 |
Stuck writes
Section titled “Stuck writes”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.
Fiscal printers
Section titled “Fiscal printers”The printer fiscalizes the receipt. The server only records the numbers.
- 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. - The app prints the receipt on the printer.
- The app sends
POST /retail/pos/transactions/:id/fiscalizewith the payments,fiscalReceiptNumber,allReceiptNumber, the timeatand thefmSerialof the printer. - At the end of day, the app sends the number of the Z report (
zReportNumber) and thefmSerial.
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. |