An open API for POS systems

General rules

Session and customer consent

• The customer consents to every receipt: the QR or six digits from the customer's screen open a session that posts one receipt and lasts 2 hours, 12 hours with a POS key. The next receipt needs a new QR.
• The QR and the code are single-use: posIdentify redeems them, just like a staff scan. Repeating the same request with the same key (the response got lost) returns the same session — until a receipt is posted on it or it expires; the Unemi till or another key gets code_used.
• With a POS key, the same code or phone number returns the same open session for 12 hours, even after the code itself has expired (it lives about a minute): the POS asks for the customer's card several times per order. A fresh code of another customer with the same digits wins — it is redeemed and opens a new session.
• A cancelled receipt (posUndo) doesn't use up the consent: the same session, while it lives, can post it again.
• A phone number finds only this business's customers (they already have a card, a bonus account or a subscription), and the session is accrual-only: accrualOnly: true, stamps and bonuses without spending.
• A phone number proves nothing: spending bonuses, buying or using a subscription and redeeming a reward need the QR or code from the customer's phone — otherwise consent_required. The API does not create new customers by phone number.

Retries and idempotency

• The response got lost — repeat the same request: the operation is not posted twice.
• posIdentify with the same QR or code from the same key returns the same session until a receipt is posted on it or it expires.
• posApply with the same receiptId and the same data returns the saved response with replayed: true — no second operation and no second push to the customer. The same receiptId with different data or another session gets receipt_conflict. The cashier and items (cashier, items) are for reference only: they aren't compared.
• receiptId is unique within a location: if a location has several tills, their receipt numbers must not overlap — for example, prefix them with the till. After a cancellation (posUndo) the same receiptId can be posted again.
• Repeating posUndo returns the same response with replayed: true.
• rate_limited and too_many_attempts — wait details.seconds seconds; internal — try again later.

Error response

An error is an HTTP status and a body:

{
  "error": {
    "code": "cooldown",
    "message": "Слишком рано: следующий штамп можно через 12 мин",
    "details": { "minutes": 12 },
    "requestId": "Qk2v9XyZaB7cD1eF3gH5"
  }
}

The POS branches on error.code — the codes are stable (tables below). message is in Russian, as in the Unemi till; details holds the numbers for the code (minutes, limit, balance).

Error codes

Access and request

Identification (posIdentify)

Receipt (posApply)

Cancellation (posUndo)

Security and data

• The key is unemi_<key id, 20 characters>_<secret, 48 hex>, 192 random bits of secret. Unemi stores only the sha256 of the secret and its last four characters to recognise it in the list; a wrong, malformed or non-existent key gets the same unauthorized.
• Other businesses are out of reach: a key is bound to its business, sessions and receipts are looked up only there, and a location key sees only its location. Someone else's session, program, reward or receipt answers “not found”.
• Personal data: the POS gets the customer's name (as Unemi Staff shows it), balances, rewards and level. Responses carry no phone number, email or internal Unemi id; the customer id is a separate alias for each business.
• Guessing codes and numbers: failed identifications (code_not_found, customer_not_found) add up per key over 15 minutes; after 5 — a 1-minute pause, after 10 — 5 minutes, after 15 — 30 minutes (too_many_attempts). The pause doesn't stop posting or cancelling receipts.
• The request log in the dashboard has no customer data and is kept for 30 days.
• There is no sandbox: integrations are tested on a test business on the Pro plan.

POS key

• A POS key is an API key for one location marked with a POS system: r_keeper, iiko, Syrve or a chain's own POS. The owner creates it in the dashboard by choosing an r_keeper till key. There are no POS keys for the whole business: a POS stands at a particular location.
• The key carries the location's rules — a default program and action (a stamp for a stamp card, bonuses for a bonus card), an amount threshold (0 … 10 000 000 ₸) and POS item codes (up to 100, each up to 40 characters without spaces) — and the language of texts on the POS screen, one of Unemi's six languages. The rules and the language change without a new key; another POS system needs a new key.
• What differs in the methods: a session lasts 12 hours, and the same code or phone number within an order returns the same session; posIdentify returns defaultProgram; a receipt without a program goes to the default program, and if nothing was accrued, the reason is in skipped.
• Digital QR: while the business has an active r_keeper POS key, the QR on the customer's card holds the same six digits as under it — the r_keeper scanner reads them as a card number. Pass them to posIdentify in qr (identifiedBy: "qr"). The general QR from the app menu (not tied to a card) stays as it is: the customer reads out the six digits under it.

{
  "name": "r_keeper · Abay",
  "venueId": "v8Kp2LmQx1",
  "pos": {
    "system": "r_keeper",
    "language": "ru",
    "rules": {
      "programId": "q2Nw7xRt",
      "action": "bonus",
      "minAmount": 0,
      "productCodes": []
    }
  }
}

r_keeper bridge for dealers Coming soon

The HttpFarCard module (ExtDllHTTP.dll) of the r_keeper POS server sends POST requests with XML itself — a card request (getcardinfoex) and the transactions of a closed receipt (transactionsex) — and the posRkeeper bridge runs them through the same core as the methods above: it identifies the customer, posts the receipt and cancels it on a rollback or refund.

Transactions are refused only when a bonus payment can't be accepted (for example, not enough bonuses, the customer was found by phone number or there is no bonus program): a receipt without a bonus payment always closes, and if the accrual didn't go through, the owner sees the reason in the request log.

Payment rollbacks, refunds and refund rollbacks never stop the POS: a refund cancels the receipt within 48 hours, and what Unemi didn't reverse, the owner sees in the refund log. Gifts and coupons aren't redeemed through r_keeper — they are handed out in the Unemi till. Texts on the POS screen are in the key's language.