# Ochrana pred duplicitou (externalId)

> Prečo každý doklad musí mať vlastný externalId: zabráni dvojitej evidencii tržby, keď sa stratí odpoveď. Ako ho tvoriť, čo eKasa vráti a ktoré úložiská ho strážia.

Zdroj: https://ekasa.ninedigit.sk/docs/receipt-registration/external-id

`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.

```mermaid
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.

**HTTP API:**

```jsonc
{
  "request": {
    "data": { /* … údaje dokladu */ },
    "externalId": "objednavka-2026-000123"
  }
}
```

**.NET knižnica:**

```csharp
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](https://ekasa.ninedigit.sk/docs/location-registration).

## Čo eKasa vráti

```mermaid
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`](https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-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](https://ekasa.ninedigit.sk/docs/receipt-lookup) a [vytlačíte jeho kópiu](https://ekasa.ninedigit.sk/docs/receipt-lookup#tla%C4%8D-k%C3%B3pie-dokladu), bez
toho, aby ste si museli pamätať číslo dokladu.

## Kam ďalej

- [Výsledok registrácie](https://ekasa.ninedigit.sk/docs/receipt-registration/result): isSuccessful, číslo dokladu a identifikátor.
- [Vyhľadanie dokladu](https://ekasa.ninedigit.sk/docs/receipt-lookup): Doklad podľa externalId alebo čísla.
- [Rozsah integrácie](https://ekasa.ninedigit.sk/docs/integration-scope): Čo musí váš softvér vedieť.
