externalId je váš vlastný identifikátor dokladu, napríklad číslo objednávky. Formálne je nepovinný, v praxi je to
jedna z najdôležitejších vecí celej integrácie: bráni tomu najhoršiemu, čo sa môže stať, totiž dvojitej
evidencii tej istej tržby.
Uvádzajte externalId pri každom doklade. Bez neho nemá eKasa ako rozpoznať, že ten istý predaj posielate
druhýkrát, a zaeviduje ho znova. Zákazník dostane dva doklady a podnikateľovi sa v systéme eKasa započíta dvojnásobná
tržba.
Kedy duplicita vzniká
Doklad sa zaeviduje, ale odpoveď sa k vášmu softvéru nedostane: vyprší časový limit, preruší sa sieť alebo spadne aplikácia. Váš softvér nevie, či sa doklad zaevidoval, a pošle ho znova.
sequenceDiagram
autonumber
participant S as Váš softvér
participant K as eKasa
S->>K: doklad (externalId objednavka-42)
Note over K: doklad zaevidovaný a vytlačený
K--xS: odpoveď sa stratí
S->>K: ten istý doklad znova (externalId objednavka-42)
K-->>S: pôvodný výsledok, nič sa neeviduje ani netlačí
Bez externalId by krok 4 zaevidoval a vytlačil druhý doklad.
Ako na to
- Vytvorte identifikátor Pre každý predaj jeden, jedinečný v rámci pokladnice: číslo objednávky, ID transakcie alebo UUID. Najviac 40 znakov.
- Uložte ho pred odoslaním Identifikátor uložte k predaju ešte pred volaním eKasy, aby ste ho po páde aplikácie poznali.
- Pri opakovaní pošlite to isté
Ak odpoveď nedostanete, pošlite doklad znova s rovnakým
externalIdaj rovnakými údajmi.
{
"request": {
"data": { /* … údaje dokladu */ },
"externalId": "objednavka-2026-000123"
}
}
var request = new RegisterCashRegisterReceiptRequest("objednavka-2026-000123", receipt);
RegisterReceiptResult result = await client.RegisterReceiptAsync(
request, RegisterReceiptPrintContext.CreatePos(), cancellationToken);
Rovnako funguje externalId aj pri registrácii polohy.
Čo eKasa vráti
flowchart TD
A{Použil sa tento<br/>externalId už skôr?} -->|nie| B[Doklad sa zaeviduje<br/>bežným spôsobom]
A -->|áno| C{Rovnaké údaje<br/>dokladu?}
C -->|nie| D[Chyba -403<br/>StorageDuplicateKey]
C -->|áno| E{Pôvodná registrácia<br/>ešte prebieha?}
E -->|áno| V{Verzia eKasy?}
V -->|9.1.0 a novšia| F[eKasa počká a vráti<br/>jej výsledok]
V -->|staršia ako 9.1.0| H[Chyba -100 GeneralError,<br/>pôvodná registrácia pokračuje]
E -->|nie| G[Pôvodný výsledok,<br/>nič sa neeviduje ani netlačí]
Chyba -403 StorageDuplicateKey znamená, že ten istý
externalId ste použili pri inom doklade.
„Rovnaký doklad“ znamená rovnaké údaje dokladu (položky, platby, texty). Spôsob vyhotovenia v print sa
neporovnáva.
Od verzie 9.1.0 eKasa navyše zvláda situáciu, keď váš softvér po vypršaní limitu zatvorí spojenie a požiadavku hneď zopakuje: opakovaná požiadavka počká, kým sa pôvodná registrácia dokončí. Registrácia, ktorej požiadavka sa už zapísala do úložiska, sa dokončí aj po zatvorení spojenia: doklad sa odošle do systému eKasa a vytlačí.
Ktoré úložiská unikátnosť strážia
Unikátnosť externalId kontroluje úložisko pri zápise, cez svoju tabuľku indexov.
| Úložisko | Kontroluje externalId |
|---|---|
| CHDU Lite | áno |
| CHDU-SK | áno |
| SwissBit | áno |
| In-Memory | nie |
Testovacie úložisko In-Memory duplicitu nekontroluje: doklad s rovnakým externalId zaregistruje znova. Opakované
odoslanie si preto pred nasadením vyskúšajte so skutočným úložiskom. Vo vašom softvéri však externalId posielajte
vždy, aj pri vývoji na In-Memory.
Ďalšie využitie
Podľa externalId doklad aj vyhľadáte a vytlačíte jeho kópiu, bez
toho, aby ste si museli pamätať číslo dokladu.