Coduri Eroare

Această secțiune oferă o referință comprehensivă a tuturor codurilor de eroare care pot fi returnate de driverul FisCool. Înțelegerea acestor coduri este crucială pentru construirea integrărilor robuste și implementarea gestionării corecte a erorilor.

Format Răspuns Eroare

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

{
  "status": 500,                    // Cod eroare specific aplicației
  "error": "Lipsă hârtie în imprimantă."  // Mesaj eroare prietenos utilizatorului (de obicei română)
}

Notă: Codurile de stare HTTP din antete urmează convențiile REST, în timp ce câmpul status din corpul JSON oferă clasificarea erorilor specifice aplicației.

Erori Aplicație (1000-1999)

Aceste erori apar la nivelul aplicației, înainte de comunicarea cu dispozitivul sau în timpul procesării interne.

Erori Dispozitive Fiscale (500-599)

Aceste erori sunt raportate de dispozitivele fiscale și reprezintă probleme hardware, de stare sau operaționale.

Erori Hardware și Stare (500-519)

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

Erori Operaționale (530-549)

Erori Comandă și Sintaxă (550-559)

Erori Terminal POS (600-619)

Aceste erori sunt specifice operațiunilor terminalelor POS și procesării cardurilor.

Erori Imprimantă (2000-2999)

Aceste erori apar când se folosește subsistemul de tipărire pentru operațiuni de tipărire non-fiscală.

Bune Practici Gestionare Erori

Pentru Dezvoltatorii de Aplicații

• Intervale Coduri Stare: Folosiți intervalele codurilor de eroare pentru a categoriza tipurile de erori:
  • 400, 404: Erori client/configurație - corectați cererea
  • 1000-1999: Erori aplicație - verificați starea sistemului
  • 500-599: Erori dispozitiv - verificați starea dispozitivului
  • 600-619: Erori POS - gestionați starea tranzacției
  • 2000+: Erori imprimantă - verificați setarea imprimantei
• Logică Reîncercare: Implementați logica de reîncercare corespunzătoare:
  • Erori temporare (505, 1004, 1005): Sigur să reîncercați cu întârziere
  • Erori stare (530, 531, 532): Corectați starea înainte de reîncercare
  • Erori configurație (400, 404, 1008): Nu reîncercați fără a corecta problema
• Mesaje Utilizator: Folosiți mesajele de eroare în română pentru afișarea către utilizatorul final
• Jurnalizare: Jurnalizați întotdeauna atât codul de eroare cât și contextul complet al erorii

Scenarii Comune de Erori

// Verificați starea dispozitivului înainte de a începe
GET /devices/{device_id}

// Erori comune de secvență:
530 (ReceiptOpen) → Anulați bonul existent mai întâi
531 (ReceiptNotOpen) → Inițializați bonul înainte de a adăuga articole
537 (InvalidAmount) → Validați că sumele sunt > 0
544 (ZNeeded) → Tipăriți raportul Z înainte de a continua

// Progresie eroare conexiune:
404 (DeviceNotFound) → Dispozitiv neConfigurat
1004 (Connection) → Conexiune rețea/serială eșuată
505 (DeviceBusy) → Dispozitivul răspunde dar este ocupat
508 (GeneralDeviceError) → Comunicația cu dispozitivul stabilită dar a apărut eroare

// Gestionarea erorilor POS:
600-603 → Problemă card/plată - necesară acțiunea clientului
604 → Tranzacție anulată - nu este necesară acțiune suplimentară
605-606 → Problemă comunicație - reîncercarea este posibilă
609 → Închiderea eșuată - verificați starea terminalului

Testarea Integrării

Testați gestionarea erorilor pentru aceste scenarii critice:

• Deconectarea dispozitivului în timpul operațiunii
• Condiții lipsă hârtie
• Secvențe invalide de bonuri
• Eșecuri comunicație terminal POS
• Cerințe raport Z
• Eșecuri validare licență