Duplicate protection (externalId)

Integrating via

externalId is your own receipt identifier, such as an order number. Formally it is optional; in practice it is one of the most important parts of the whole integration: it prevents the worst thing that can happen, recording the same sale twice.

Send an externalId with every receipt. Without it, eKasa has no way to recognise that you are sending the same sale again and records it a second time. The customer gets two receipts and the business is credited with double sales in the eKasa system.

When duplicates happen

The receipt is recorded, but the response never reaches your software: a timeout expires, the network drops or the application crashes. Your software does not know whether the receipt was recorded and sends it again.

sequenceDiagram
    autonumber
    participant S as Your software
    participant K as eKasa
    S->>K: receipt (externalId order-42)
    Note over K: receipt recorded and printed
    K--xS: the response is lost
    S->>K: the same receipt again (externalId order-42)
    K-->>S: the original result, nothing recorded or printed

Without an externalId, step 4 would record and print a second receipt.

How to do it

  1. Create an identifier One per sale, unique within the cash register: an order number, transaction ID or UUID. At most 40 characters.
  2. Store it before sending Save the identifier with the sale before calling eKasa, so you still know it after an application crash.
  3. Send the same on retry If you get no response, send the receipt again with the same externalId and the same data.
{
  "request": {
    "data": { /* … receipt data */ },
    "externalId": "order-2026-000123"
  }
}
var request = new RegisterCashRegisterReceiptRequest("order-2026-000123", receipt);

RegisterReceiptResult result = await client.RegisterReceiptAsync(
    request, RegisterReceiptPrintContext.CreatePos(), cancellationToken);

externalId works the same way for location registration.

What eKasa returns

flowchart TD
    A{Was this externalId<br/>used before?} -->|no| B[The receipt is<br/>recorded as usual]
    A -->|yes| C{Same receipt<br/>data?}
    C -->|no| D[Error -403<br/>StorageDuplicateKey]
    C -->|yes| E{Is the original registration<br/>still in progress?}
    E -->|yes| V{eKasa version?}
    V -->|9.1.0 and newer| F[eKasa waits and<br/>returns its result]
    V -->|older than 9.1.0| H[Error -100 GeneralError,<br/>the original registration continues]
    E -->|no| G[The original result,<br/>nothing is recorded or printed]

The error -403 StorageDuplicateKey means you used the same externalId for a different receipt.

“The same receipt” means the same receipt data (items, payments, texts). The way of issuing it in print is not compared.

From version 9.1.0, eKasa also handles the case where your software closes the connection after a timeout and retries the request right away: the retry waits until the original registration finishes. A registration whose request has already been written to the storage completes even after the connection is closed: the receipt is sent to the eKasa system and printed.

Which storages enforce uniqueness

The storage checks externalId uniqueness when writing, through its index table.

Storage Checks externalId
CHDU Lite yes
CHDU-SK yes
SwissBit yes
In-Memory no

The In-Memory test storage does not check duplicates: it registers a receipt with the same externalId again. Try repeated sending with a real storage before going live. In your software, however, always send an externalId, even when developing on In-Memory.

Other uses

With the externalId you can also look up a receipt and print its copy without having to remember the receipt number.

Where next

Esc

↑↓ selectEnter openEsc close

Chýba vám niečo v dokumentácii?

Napíšte nám, s čím potrebujete pomôcť. Ozveme sa do pár hodín.

Údaje použijeme len na odpoveď. Viac v ochrane osobných údajov.