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.

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.

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 has the same format everywhere:

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

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

Codes 2001–2003 mean no free register / no suitable register / INN mismatch:

• no register became available within 300 seconds (all registers in the group are offline or busy with other receipts) → status: fail, type: "timeout", code 2001. If a register PICKED UP the receipt but did not respond within 300 seconds, you receive code 1 with the same type: "timeout" — the code distinguishes “no register was available” from “the register is not responding”;
• the receipt INN does not match the group INN → the document is rejected immediately on registration: HTTP 400, code 2003, with both INNs named in the message; it never enters the queue;
• the register cannot issue this kind of receipt (product marking, electronic receipt, extended buyer details) → status: fail, code 2002, type: "driver", and error.text contains the register's rejection verbatim.

Driver errors appear in the document result, not in the registration response — they occur after the document has been accepted into the queue. For details and what to do in 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.