Coduri Eroare

Această pagină este referința completă a codurilor de eroare returnate de driverul FisCool, pe toate interfețele (HTTP, WebSocket, erorile de execuție INP).

Formatul Răspunsului de Eroare

Toate API-urile returnează erorile într-un format JSON consecvent:

{
  "status": 500,                             // cod de eroare specific aplicației (întreg pozitiv)
  "error": "Lipsă hârtie în imprimantă.",    // mesaj lizibil (în română)
  "receipt": "..."                           // OPȚIONAL: prezent doar la unele erori POS
}

• Câmpul status din corp este codul de eroare al aplicației, documentat mai jos; statusul HTTP al răspunsului urmează convențiile REST (vezi maparea pe pagina API HTTP).
• Câmpul opțional receipt apare la erorile de tranzacție POS care au produs o chitanță tipăribilă (ex: o vânzare refuzată).

Erori de Aplicație

Erori generate de driver - înainte de sau în jurul comunicării cu dispozitivul.

Erori Dispozitive Fiscale (500–599)

Erori raportate de dispozitivele fiscale - probleme hardware, de stare sau operaționale. Mesajele sunt afișate exact cum sunt returnate în câmpul error.

Erori Hardware și de Stare (500–519)

Erori de Memorie Fiscală și Jurnal Electronic (520–529)

Erori Operaționale (530–549)

Erori de Comandă și Sintaxă (550–559, 599)

Erori Terminale POS (600–611)

Erori specifice operațiunilor pe terminalele POS. Acestea pot purta câmpul opțional receipt cu chitanța terminalului.

Erori de Imprimantă (2001–2005)

Erori din subsistemul de tipărire nefiscală (/printers/print_html și acțiunea de tipărire WebSocket).

Bune Practici de Tratare a Erorilor

• Intervale de coduri: categorisiți după interval:
  • 400, 404, 408: erori de cerere/configurare - corectați cererea
  • 1000–1015: erori de aplicație - verificați starea driverului/sistemului
  • 500–599: erori de dispozitiv fiscal - verificați dispozitivul
  • 600–611: erori POS - tratați starea tranzacției
  • 2001–2005: erori de imprimantă - verificați configurarea imprimantei
• Logica de reîncercare:
  • Erori tranzitorii (505, 408, 1004, 1005, 605, 606): pot fi reîncercate cu backoff - dar pentru vânzările POS folosiți întotdeauna un Idempotency-Key, ca reîncercarea să nu poată debita dublu.
  • Erori de stare (530, 531, 532, 544, 545): rezolvați mai întâi starea dispozitivului, apoi reîncercați.
  • Erori de configurare (400, 404, 540, 1009): nu reîncercați fără a corecta cererea/configurarea.
• Mesaje pentru utilizatori: mesajele din error sunt deja text prietenos în română, potrivit pentru afișare directă.
• Logging: logați întotdeauna atât codul, cât și mesajul complet.

Scenarii Frecvente de Eroare

530 (ReceiptOpen)   → anulați/finalizați bonul rămas deschis pe dispozitiv
544 (ZNeeded)       → tipăriți mai întâi raportul Z
400 (Config)        → plățile nu corespund totalului, cotă TVA inactivă, fără linii de produs
1004 (Connection)   → dispozitivul nu este conectat

404 (DeviceNotFound)      → device_id greșit / dispozitiv șters
1004 (Connection)         → conexiunea de rețea/serială a eșuat
505 (DeviceBusy)          → dispozitivul răspunde dar este ocupat - reîncercați
509/508 (GeneralError)    → dispozitivul e accesibil dar a raportat o eroare

600–603 → problemă card/plată - este necesară acțiunea clientului
604     → anulată - nicio acțiune suplimentară
605–606 → problemă de comunicare - verificați terminalul, reîncercați (idempotență!)
609     → închiderea de zi a eșuat - verificați starea terminalului
Notă: corpul erorii poate include "receipt" cu chitanța de refuz.

Testarea Integrării

Testați tratarea erorilor pentru aceste scenarii critice:

• Dispozitiv deconectat în timpul operațiunii
• Condiții de lipsă hârtie
• Bon rămas deschis pe dispozitiv
• Eșecuri de comunicare și refuzuri ale terminalului POS
• Raport Z necesar
• Eșecuri de validare a licenței