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
- Create an identifier One per sale, unique within the cash register: an order number, transaction ID or UUID. At most 40 characters.
- Store it before sending Save the identifier with the sale before calling eKasa, so you still know it after an application crash.
- Send the same on retry
If you get no response, send the receipt again with the same
externalIdand 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.