Idempotency-Key

Un timeout sau o conexiune căzută te lasă fără răspuns: comanda poate fi în coadă sau nu. Trimite un antet Idempotency-Key cu fiecare comandă pe care o creezi și reîncearcă cu aceeași cheie. API-ul pune comanda în coadă o singură dată și răspunde la fiecare repetare cu primul commandId, așa că o reîncercare nu tipărește niciodată un al doilea bon.

• Creează un GUID nou pentru fiecare vânzare sau comandă și salvează-l împreună cu vânzarea înainte de primul apel, ca aplicația ta să reîncerce cu aceeași cheie chiar și după o repornire.
• Reîncearcă aceeași cerere cu aceeași cheie până primești un răspuns. Orice scriere a unui GUID este acceptată; API-ul îl păstrează cu litere mici și îl ține minte 30 de zile, după care cheia este o cerere nouă.
• O vânzare nouă primește o cheie nouă, chiar dacă are aceleași produse. O cheie care revine cu o altă cerere este refuzată cu 409 și nu se pune nimic în coadă.
• Fără antet nu se schimbă nimic: fiecare cerere este o comandă nouă. Antetul este acceptat de rutele care creează comenzi și de perechile lor /sandbox.

Ce răspunde API-ul

• 202: Prima cerere cu o cheie: intră în coadă ca de obicei.
• 202: Aceeași cerere din nou, cu aceeași cheie: din nou primul răspuns, inclusiv commandId, cu antetul Idempotent-Replayed: true. Nu se pune nimic nou în coadă.
• 409: Cheia a fost deja folosită pentru o altă cerere: altă casă, altă comandă sau alt corp.
• 400: Antetul nu este un singur GUID sau este trimis de două ori.
• 500: Comanda nu a putut fi salvată. Nu s-a pus nimic în coadă; reîncearcă cu aceeași cheie.

„Starea unei comenzi” și listele de comenzi arată cheia în requestId.

Pe casă

Cheia ajunge, împreună cu bonul fiscal, și la aplicația FiscalLink de pe casă. Dacă un bon cu aceeași cheie este deja pe hârtie — după o reîncercare din cauza lipsei de hârtie sau o retrimitere din panou — aplicația răspunde cu acel bon în loc să-l tipărească din nou, iar rezultatul conține replayedFromCommandId.

Dacă o încercare este întreruptă înainte ca casa să confirme bonul (răspunsul la închidere s-a pierdut sau aplicația s-a oprit în timpul bonului), aplicația nu poate ști dacă s-a tipărit. Acea încercare eșuează cu propria eroare și code: receipt_close_unconfirmed; o încercare ulterioară a aceleiași vânzări eșuează cu 424 și code: receipt_outcome_unknown, în loc să riște un al doilea bon. Verifică ultimul bon de pe casă; dacă vânzarea nu este pe el, trimite-o ca o comandă nouă, cu o cheie nouă.

O aplicație FiscalLink mai veche decât această funcție ignoră cheia pe casă; verificarea proprie a API-ului se aplică în continuare. Rutele /sandbox acceptă același antet și răspund la fel, dar simulatorul nu modelează partea casei.