Erori și coduri

Ce înseamnă fiecare cod.

Ramifică după codul de stare și după `code`, unde există, niciodată după text: textele se pot schimba, iar unele vin de la casă, în limba ei.

API local

Forma erorii: { "statusCode": …, "message": "…" }, plus code unde un singur cod de stare acoperă două refuzuri. Niciodată HTML. Excepție: /api/Receipt răspunde mereu 200 (vezi „Treci de pe FiscalNet sau Fisco”).

Status	Cheie în surse	Descriere
200	—	Succes.
400	—	Cererea încalcă o regulă (interval, lungime, obiect lipsă), sau casa a refuzat comanda („Receipt printing error: …”). Un bon deschis e anulat întâi.
400	`INVALID_SEPARATING_LINE_TYPE`	Tipul liniei de separare nu e 1–4, sau e 4 pe o casă Datecs.
401	`LICENSE_REQUIRED`	Casa conectată nu are licență.
403	`COMMERCE_LICENSE_REQUIRED`	Rutele Shopify fără licența Commerce.
404	—	Resursa nu există.
424	—	Transport: nicio casă conectată, sau legătura cu casa a căzut.
500	—	Casa n-a răspuns la timp: aplicația o marchează „nu răspunde”, iar următorul succes șterge marcajul. Sau o eroare neașteptată în aplicație.

Coloana „Cheie în surse” numește refuzul în documentația noastră. Câmpul code apare în corp doar pe rutele unde un cod de stare acoperă două refuzuri.

json

{
  "statusCode": 500,
  "message": "Internal server error occurred - if you see this, please contact the developer"
}

API Cloud

Mesajele de eroare sunt text simplu: text/plain fără antet Accept, sau un șir JSON cu Accept: application/json. O cerere care nu se poate citi deloc răspunde application/problem+json, cu o hartă errors.

Status	Descriere
202	Comanda e în coadă.
400	Validarea a eșuat; corpul e mesajul.
401	Fără cheie, sau cheie necunoscută, revocată ori expirată. Corp gol.
403	Cheie de alt tip sau a altei organizații. Corp gol.
404	Nu există în organizația ta; corpul e mesajul.
409	Conflict cu date existente, de exemplu un nume de client deja folosit.
500	Eșec neașteptat. Corpul poate fi gol.

Rezultatul unei comenzi

O comandă răspunde 202 imediat; rezultatul casei îl citești apoi cu „Starea unei comenzi”: codul în statusCode, textul în message. Un rezultat reușit e StatusCode 200 cu răspunsul în Data; o eroare a casei e un obiect cu statusCode și message.

`statusCode`	Descriere
200	Succes.
400	Casa a refuzat, sau corpul încalcă o regulă a aplicației FiscalLink. Majoritatea regulilor se verifică înainte de deschiderea bonului; un bon care eșuează după deschidere e anulat, iar mesajul se termină cu `\| Receipt cancelled successfully`.
404	`unknown_command`: aplicația FiscalLink de pe casă e prea veche pentru această comandă.
409	La citirea cotelor TVA: verificarea cotelor e oprită pe casă.
424	Transport: imprimanta nu e conectată sau n-a răspuns la timp.
499	`client_cancelled`: comanda a fost anulată în timp ce rula.
500	Eroare neașteptată în aplicație; mesajul numește excepția. Un bon fiscal deja deschis e anulat.

Erorile pe care aplicația le dă înainte să ajungă la casă au corpuri fixe:

json

{ "error": "unknown_command", "commandType": "cashRegister.printFiscalReceipt" }

json

{ "error": "invalid_payload", "detail": "<detail>" }

json

{ "error": "internal_error" }

json

{ "error": "client_cancelled" }

Înainte să retrimiți

`400`: cererea a fost refuzată înainte să plece ceva spre casă, sau bonul a fost anulat. Corectează cererea și trimite-o din nou.
`424` și timeout (`500`) la un bon fiscal: nu dovedesc că nu s-a tipărit nimic; un document poate exista. Nu retrimite automat. Un bon se trimite din nou doar când știi sigur că nu s-a tipărit, pentru că un bon fiscal dublat nu se mai poate repara.
API-ul Cloud: fiecare trimitere e o comandă nouă și un bon nou. Când răspunsul unei trimiteri se pierde, interoghează lista comenzilor („Istoricul casei” sau „Toate comenzile”) înainte să trimiți din nou.

Erori frecvente

#	Eroare	Ce faci
1	`401` pe API-ul local	Casa nu are licență. Clientul o activează din FiscalLink Cloud (pașii: /app/docs).
2	`424`	Casa nu e conectată sau legătura a căzut. Clientul verifică conexiunea în aplicația FiscalLink (pașii: /app/docs).
3	`500` la timeout	Când legătura merge, un timeout înseamnă aproape mereu că, de fapt, casa e în alt mod de lucru. Verifică pe casă, apoi citește „Înainte să retrimiți”.
4	`400` vânzare liberă pe Daisy	Pornește „Vânzare liberă pe Daisy” (în aplicație sau, ca integrator, în Setări → Date companie) sau vinde articole PLU.
5	`400` grupă TVA	Folosește o grupă pe care casa o are și care poartă 21%, 11% sau 0%: Tremol 1–6, Datecs 1–7; un Datecs neplătitor de TVA doar 5 și 6.
6	Casa refuză bonurile după 24 de ore	Casa blochează vânzările la 24 de ore de la prima vânzare fără raport Z (Datecs -111024, Tremol 1100, Daisy 82 „DEPASIT 24h”); pe Datecs, aplicația avertizează după 20 de ore. Trimite raportul Z.
7	`409` la citirea cotelor TVA	Verificarea cotelor TVA e oprită în aplicația de pe casă. Clientul o pornește din setările aplicației (/app/docs).
8	`404` la trimiterea unei comenzi Cloud	Casa nu poate primi comenzi: verifică cu „Citește o casă” că e `Active`, că `awaitingClientConsent` e `false` și că abonamentul e activ.
9	`403` pe API-ul Cloud	Cheia e de alt tip (comenzi, administrare, sandbox) sau `tenantId` nu e organizația cheii.
10	`unknown_command`	Aplicația FiscalLink de pe casă e prea veche. Clientul o actualizează (/download).
11	Fără hârtie	Pe API-ul Cloud, bonul se reîncearcă singur la 60 de secunde; interoghează ID-ul inițial. După ce clientul pune hârtie, bonul pleacă.
12	`Amount must be between 0.01 and 9999999.99. \| Receipt cancelled successfully`	Plată automată la un total de 0 sau mai mic, pe Datecs. Verifică liniile bonului.