Cash Server API: reference

The protocol is compatible with ATOL Online: the same paths, the same field names, the same error codes. If you already have a module built for ATOL Online, changing the base URL and the access credentials is usually enough.

A product overview and the requirements for the cash register — Cash Server.

1. Authentication: getToken#

curl -X POST https://54fz.cenaly.ru/possystem/v5/getToken \
  -H 'Content-Type: application/json' \
  -d '{"login":"u9f3c1a7d40b2","pass":"••••••••"}'

{ "error": null, "token": "e826899dc378…063086", "timestamp": "04.08.2026 13:37:40" }

• The login and group_code are issued upon creating a POS server in the admin panel's "POS API" section and look like u<12 hex> and kkt-<12 hex> — custom descriptive values cannot be chosen.
• The token is valid for 24 hours; there is no need to request it for every receipt — cache it.
• The token is passed via the Token: <token> header or the ?token=<token> parameter.
• GET /possystem/v5/getToken?login=…&pass=… is also supported — mirroring ATOL.
• Invalid credentials → HTTP 401, error code 12.

One login serves one POS group. We store the password only as an argon2id hash — it cannot be recovered, only reissued: "POS API" section → "Change password". Previously issued tokens will continue to work until their 24 hours expire.

2. Registering a document#

POST /possystem/{v5|v4}/{group_code}/{operation}

Request body#

{
  "timestamp": "04.08.2026 14:40:00",
  "external_id": "order-10421",
  "service": { "callback_url": "https://shop.example/api/fiscal-callback" },
  "receipt": {
    "client": { "email": "buyer@example.com" },
    "company": {
      "email": "shop@example.com",
      "sno": "usn_income",
      "inn": "7736570901",
      "payment_address": "https://shop.example"
    },
    "items": [
      {
        "name": "Coffee beans, 1 kg",
        "price": 1250.00,
        "quantity": 2,
        "sum": 2500.00,
        "measure": 0,
        "payment_method": "full_payment",
        "payment_object": 1,
        "vat": { "type": "vat20" }
      }
    ],
    "payments": [ { "type": 1, "sum": 2500.00 } ],
    "total": 2500.00
  }
}

The contents of receipt and all value reference tables — Receipt fields.

Response#

{ "uuid": "47b30214-b145-4c3f-abe3-89076225ac4f",
  "timestamp": "04.08.2026 13:39:15", "status": "wait", "error": null }

uuid is the identifier of the document in our queue; the result is requested by it. The wait status means "accepted, waiting for a cash register" — that is the normal response to a successful registration.

Important. A wait response does not yet mean the receipt has been registered. A payment may be treated as fiscalized only on done in the report or in the callback.

3. Result: report#

GET /possystem/{v5|v4}/{group_code}/report/{uuid}

curl "https://54fz.cenaly.ru/possystem/v5/kkt-1f4c9a20b73e/report/47b30214-…" \
  -H "Token: $TOKEN"

{
  "uuid": "47b30214-b145-4c3f-abe3-89076225ac4f",
  "timestamp": "04.08.2026 13:39:28",
  "callback_url": "https://shop.example/api/fiscal-callback",
  "status": "done",
  "group_code": "kkt-1f4c9a20b73e",
  "daemon_code": "cenaly-54fz",
  "device_code": "kkt-1",
  "external_id": "order-10421",
  "error": null,
  "warnings": null,
  "payload": {
    "fiscal_receipt_number": 101,
    "shift_number": 9,
    "receipt_datetime": "04.08.2026 13:39:15",
    "total": 2500.0,
    "fn_number": "9999078902005478",
    "ecr_registration_number": "0000000001056264",
    "fiscal_document_number": 6789,
    "fiscal_document_attribute": 2745081395,
    "fns_site": "www.nalog.gov.ru",
    "ofd_receipt_url": ""
  }
}

Statuses#

Payload fields#

The four parameters FD + FPD + FN + RN KKT are what you need to save in the order: they allow locating the receipt in the OFD personal dashboard and in the FTS "Receipt Check" mobile app. The ofd_receipt_url field is reserved by the protocol, but POS drivers do not return the link, so it arrives empty.

Certain POS units may not return some attributes (such as the shift number). In this case, the field returns zero or empty — we deliberately never substitute calculated values into fiscal attributes.

Storage and limits#

• The result is available for at least 32 days; the document is archived after 60 days.
• Polling is rate-limited: 1 request per second per POS in the group. Exceeding it returns HTTP 429.
• Unknown uuid → error 30; document still in queue → HTTP 200 with status: wait.

4. Callback#

If the request contained service.callback_url, then after the document moves to done or fail we send it a POST with the same body the report returns.

• The request timeout is 10 seconds, success is any 2xx response.
• Retries: immediately, after 30 seconds, after 120 seconds (3 attempts in total).
• An invalid or overly long URL does not break the receipt: it is discarded and warnings.callback_url appears in the report.

The handler on your side must be idempotent — key it on uuid or external_id. The callback does not replace polling: if no notification arrived within 300 seconds, request the report yourself.

5. Idempotency#

external_id is unique within a group. Registering the same external_id again returns HTTP 400 and error 33 — together with the original uuid:

{ "uuid": "47b30214-…", "status": "wait",
  "error": { "code": 33, "text": "a document with this external_id has already been accepted in this group", "type": "system" } }

That is the regular answer to a retry, not an emergency: take the uuid from the response and request the report for it.

Idempotency is end-to-end — it reaches the cash register itself. The bridge receives an operation key built from the group and external_id, and the bridge keeps an operation journal on disk: a repeat of the same operation returns the first result and survives a reboot of the cash register PC. If the previous attempt broke off with an unknown outcome (the connection dropped exactly at the closing of the receipt), the repeat is rejected with a demand to verify the last document on the cash register — a second tax document is never generated blindly.

The practical rule: one external_id per payment, and repeat the request with the same value as many times as you like. Create a new external_id only for a new settlement.

6. Limits#

7. Error Codes#

The error object format is consistent across all endpoints:

{ "error": { "error_id": "f546e8d0-…", "code": 33, "text": "…", "type": "system" },
  "status": "fail", "timestamp": "04.08.2026 13:39:15" }

type — one of system, driver, agent, timeout, unknown.

Codes 2001–2003 — no available POS / no matching POS / TIN mismatch:

• no POS became available within 300 seconds (every POS in the group is offline or busy with other receipts) → status: fail, type: "timeout", code 2001. If a POS did take the receipt but did not answer within 300 s, you get code 1 with the same type: "timeout" — the code tells "no POS at all" from "the POS went silent";
• receipt TIN does not match group TIN → document is rejected immediately upon registration: HTTP 400, code 2003, text indicates both TINs; it does not enter the queue;
• POS cannot process this receipt type (marking, electronic receipt, extended buyer requisites) → status: fail, code 2002, type: "driver", with the POS's verbatim rejection in error.text.

Driver errors do not arrive in the registration response, but in the document result — they occur once it has already been accepted into the queue. For a detailed breakdown and resolution steps for each case, see Errors and Diagnostics.

8. Differences between v5 and v4#

They cannot be mixed: measurement_unit in v5 and measure in v4 are rejected by validation with a clear message. v5 is recommended for new integrations — marked goods require FFD 1.2.

9. Quick Start: Full Cycle with curl#

BASE=https://54fz.cenaly.ru/possystem/v5
GROUP=kkt-1f4c9a20b73e

TOKEN=$(curl -s -X POST $BASE/getToken -H 'Content-Type: application/json' \
  -d '{"login":"u9f3c1a7d40b2","pass":"••••"}' | jq -r .token)

UUID=$(curl -s -X POST $BASE/$GROUP/sell -H "Token: $TOKEN" \
  -H 'Content-Type: application/json' -d @receipt.json | jq -r .uuid)

curl -s "$BASE/$GROUP/report/$UUID" -H "Token: $TOKEN" | jq .payload

Next: receipt details · store scenarios · errors.