Ochrana pred duplicitou (externalId)

Integrujem cez

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

  1. Vytvorte identifikátor Pre každý predaj jeden, jedinečný v rámci pokladnice: číslo objednávky, ID transakcie alebo UUID. Najviac 40 znakov.
  2. 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.
  3. Pri opakovaní pošlite to isté Ak odpoveď nedostanete, pošlite doklad znova s rovnakým externalId aj 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.

Kam ďalej

Esc

↑↓ výberEnter otvoriťEsc zavrieť

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.