{
  "device_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",   // UUID-ul unui dispozitiv configurat
  "operation": {
    "type": "nume_operatiune",                            // tipul operațiunii, în snake_case
    // ... câmpuri specifice operațiunii
  }
}

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

Descriere: Tipărește un bon fiscal cu produse, text liber, plăți și, opțional, datele cumpărătorului. Este cea mai complexă și cea mai importantă operațiune din sistem.

Parametri:

Obiectul ReceiptLine

O linie de bon este un obiect etichetat - type selectează varianta:

// Linie de produs (vânzare)
{
  "type": "item",
  "description": "Nume Produs",      // "name" este acceptat ca alias
  "quantity_thousandths": 1000,      // 1000 = 1.000 bucăți (3 zecimale implicite)
  "unit_price_cents": 1500,          // 1500 = 15.00; valorile negative sunt acceptate pentru corecții
  "vat": "19%",                      // vezi „Valori TVA" mai jos
  "discount": {                      // OPȚIONAL: discount/majorare la nivel de produs
    "kind": "percent",
    "basis_points": 1000,            // 1000 = 10.00%
    "is_surcharge": false
  },
  "um": "buc",                       // OPȚIONAL: unitate de măsură; gol/lipsă devine "buc"
  "department": 3                    // OPȚIONAL: cod departament (1-99)
}

// Linie de text liber
{
  "type": "text",
  "text": "Text de tipărit"
}

// Linie de subtotal
{
  "type": "subtotal",
  "discount": {                      // OPȚIONAL: discount/majorare aplicată subtotalului curent
    "kind": "percent",
    "basis_points": 1000,
    "is_surcharge": false
  }
}

Valori TVA (câmpul vat)

Câmpul vat este un șir de caractere care acceptă următoarele forme:

Obiectul PaymentLine

{
  "method": "cash",                  // vezi tabelul metodelor de plată
  "amount_cents": 1500
}

Metode de plată (method):

Obiectul BuyerInfo

{
  "vat_number": "RO12345678"         // codul fiscal al clientului (CUI/CIF)
}

Obiectul Discount

Folosit pentru discounturi/majorări la nivel de produs, de subtotal și de bon. kind selectează varianta:

// Procentual
{
  "kind": "percent",
  "basis_points": 1000,              // 1000 = 10.00%
  "is_surcharge": false              // false = discount, true = majorare
}

// Sumă absolută
{
  "kind": "absolute",
  "amount_cents": 500,               // 500 = 5.00 (întotdeauna pozitiv)
  "is_surcharge": false
}

Obiectul ReceiptFlags

Validare și Preprocesare

Înainte ca ceva să fie trimis către dispozitiv, driverul validează și normalizează cererea. O validare eșuată returnează eroarea 400 cu un mesaj descriptiv și nu se tipărește nimic.

• Diacriticele sunt eliminate din denumirile produselor, unitățile de măsură și liniile de text liber.
• Produsele cu preț zero (unit_price_cents = 0) sunt convertite în note de text liber (ex: 2 buc PUNGA 0 lei), deoarece casele de marcat resping liniile de vânzare cu valoare zero.
• Bonul trebuie să conțină cel puțin o linie de produs (cu excepția bonului anulat).
• Totalul bonului trebuie să fie strict pozitiv după toate discounturile (cu excepția bonului anulat).
• Suma plăților trebuie să fie exact egală cu totalul bonului. Excepție: când există o plată cashback, suma trebuie să fie mai mare sau egală cu totalul. Totalul unei linii se calculează ca quantity_thousandths × unit_price_cents / 1000, rotunjit „half away from zero".
• Este permisă o singură linie de subtotal cu discount per bon, iar un discount de subtotal nu poate fi combinat cu receipt_discount.
• TVA-ul fiecărui produs este validat față de cotele active pe dispozitiv (vezi Valori TVA mai sus).
• Când close_action este "void", toate validările de vânzare de mai sus sunt sărite: bonul este deschis și apoi anulat, iar plățile nu sunt înregistrate.

Răspuns:

{
  "status": 0,
  "msg": "Receipt printed",
  "slip_number": 123,                // numărul bonului fiscal
  "z_report_number": 45,             // numărul raportului Z de care aparține bonul
  "fiscal_receipt_count": 1050,      // contorul de bonuri fiscale al dispozitivului
  "bon_id": "1234...32cifre"         // bon-ID-ul din codul QR (doar Datecs, când e activat); null altfel
}

Trimitere automată card către POS: Dacă este activată în configurarea dispozitivului fiscal (auto_send_card_to_pos + linked_pos_device_id), suma plăților card și cashback este trimisă mai întâi ca vânzare către terminalul POS asociat. Dacă tranzacția POS eșuează, bonul fiscal nu este tipărit și se returnează eroarea POS.

Verificarea conexiunii: operațiunea eșuează imediat cu eroarea 1004 dacă dispozitivul fiscal nu este în starea Connected.

Descriere: Tipărește un bon nefiscal (text liber) pe dispozitivul fiscal. Util pentru documente proforma, bonuri de comandă sau orice informație care nu trebuie fiscalizată.

Parametri:

Obiectul NonFiscalLine

// Linie de text simplă
{
  "type": "text",
  "text": "Text de tipărit"
}

// Linie de text cu formatare (respectată pe dispozitivele Datecs; celelalte tipăresc text simplu)
{
  "type": "text",
  "text": "Text formatat",
  "formatting": {
    "bold": true,
    "italic": false,
    "double_height": true,
    "underline": false,
    "alignment": "center",           // "left" (implicit), "center", "right"
    "condensed": false
  }
}

Răspuns: aceeași formă ca la print_receipt; câmpurile numerice se referă la contoare nefiscale și pot fi 0, în funcție de dispozitiv:

{
  "status": 0,
  "msg": "Receipt printed",
  "slip_number": 0,
  "z_report_number": 0,
  "fiscal_receipt_count": 0
  "bon_id": null
}

Descriere: Tipărește un raport X (totaluri zilnice, fără închiderea zilei fiscale).

Parametri: niciunul (în afară de type).

Răspuns:

{
  "status": 0,
  "msg": "Report printed",
  "report_number": 45,               // contorul raportului
  "grand_total_sell": 123456,        // totalul general al zilei, în bani
  "payment_totals": [                // totaluri per metodă de plată (poate fi gol dacă dispozitivul
    { "method": "cash", "amount": 100000 },   //   nu le-a putut raporta; sume în bani)
    { "method": "card", "amount": 23456 }
  ],
  "vat_totals": [                    // totaluri per grupă de TVA; doar grupele cu amount > 0
    { "letter": "A", "value": 1900, "amount": 100000 }  // value = cota în sutimi de procent (basis points)
  ],
  "full_text": null                  // textul complet al raportului; populat doar la rapoartele Z pe Datecs
}

Note:

• payment_totals[].method folosește aceleași coduri ca plățile bonului (cash, card, …).
• Granularitatea payment_totals depinde de dispozitiv: unele dispozitive au mai puține registre fizice de plată și grupează mai multe metode împreună.
• Un array payment_totals/vat_totals gol înseamnă că dispozitivul nu a putut furniza detalierea - nu înseamnă vânzări zero.

Descriere: Tipărește un raport Z (închiderea fiscală de zi). Resetează contoarele zilnice.

Parametri: niciunul.

Răspuns: identic ca formă cu print_x (vezi mai sus). full_text conține textul complet al raportului tipărit pe dispozitivele Datecs, null în rest.

Descriere: Tipărește raportul pe departamente (vânzările zilnice grupate pe departamente), fără a închide ziua fiscală și fără a reseta vreun contor.

Parametri: niciunul.

Răspuns: raportul se tipărește doar pe hârtie - nu se returnează totaluri:

{
  "status": 0,
  "msg": "Operation completed successfully"
}

Note:

• Suportat pe dispozitivele Datecs, Daisy, Tremol și Custom. Dispozitivele al căror protocol nu are un raport pe departamente returnează eroarea 1015 (operațiune nesuportată).
• În interfața cu fișiere INP, același raport se declanșează cu Z,1,______,_,__;3; (legacy/FPrint) sau D^ (simplu/modern).

Descriere: Înregistrează o introducere de numerar (serviciu intrare) în casa de marcat.

Parametri:

Răspuns:

{
  "status": 0,
  "msg": "Cash operation successful",
  "total_cash_drawer": 1250.75       // totalul de numerar din sertar DUPĂ operațiune,
}                                     //   în lei, ca număr zecimal - NU în bani

Descriere: Înregistrează o retragere de numerar (serviciu ieșire) din casa de marcat.

Parametri:

Răspuns: aceeași formă ca la deposit_cash (total_cash_drawer în lei, zecimal).

Descriere: Declanșează semnalul acustic (buzzer-ul) al dispozitivului fiscal. Pe dispozitivele fără buzzer controlabil se tipărește în schimb o notă nefiscală scurtă, astfel încât acțiunea să fie totuși observabilă.

Parametri: niciunul.

Răspuns:

{
  "status": 0,
  "msg": "Operation completed successfully"
}

Descriere: Deschide sertarul de bani conectat la dispozitivul fiscal.

Parametri:

Răspuns:

{
  "status": 0,
  "msg": "Operation completed successfully"
}

Descriere: Exportă fișierele de date fiscale pentru raportarea ANAF într-un folder local.

Parametri:

Obiectul AnafExportRange

// Interval de date (șiruri, AAAA-LL-ZZ)
{ "start": "2023-12-01", "end": "2023-12-31" }

// Interval de numere Z (numere întregi)
{ "start": 1, "end": 10 }

Răspuns:

{
  "status": 0,
  "msg": "Operation completed successfully"
}

Descriere: Citește starea de sincronizare ANAF de la dispozitivul fiscal.

Parametri: niciunul.

Răspuns: câmpul data este un șir JSON codificat care conține una dintre:

{
  "status": 0,
  "msg": "Report data retrieved successfully",
  "data": "\"Success\""
}

// data se decodifică într-una dintre:
"Success"                                                    // ultima sincronizare OK
{ "Failed": { "error_code": -3, "error_message": "..." } }   // ultima sincronizare a eșuat
"Unknown"                                                    // nesuportat / necunoscut

Descriere: Încarcă o imagine de logo în dispozitivul fiscal, pentru a fi tipărită pe bonuri. Driverul convertește imaginea în formatul nativ al dispozitivului; folosiți get_logo_dimensions pentru a afla dimensiunea optimă.

Parametri:

Răspuns:

{
  "status": 0,
  "msg": "Operation completed successfully"
}

Descriere: Returnează dimensiunile logo-ului (în pixeli) suportate de dispozitiv.

Parametri: niciunul.

Răspuns: data este un șir JSON codificat:

{
  "status": 0,
  "msg": "Report data retrieved successfully",
  "data": "{\"width\":576,\"height\":128}"
}

Descriere: Tipărește un raport de memorie fiscală pentru un interval de date sau de numere Z, pe imprimanta dispozitivului.

Parametri:

Obiectul FiscalRange

// Interval de date (șiruri, AAAA-LL-ZZ)
{ "start": "2023-12-01", "end": "2023-12-31" }

// Interval de numere Z (numere întregi)
{ "start": 1, "end": 10 }

Răspuns:

{
  "status": 0,
  "msg": "Operation completed successfully"
}

Descriere: Generează un raport din jurnalul electronic (JE), fie tipărit pe dispozitiv, fie returnat ca text.

Parametri:

Obiectul JeReportRange (etichetat cu type)

// Interval de date
{ "type": "date", "start": "2023-12-01", "end": "2023-12-31" }

// Interval de numere Z
{ "type": "z_number", "start": 1, "end": 10 }

// Interval de numere de document
{ "type": "doc_number", "start": 100, "end": 200 }

Tipuri de Documente (doc_type)

• "all" - toate tipurile de documente
• "fiscal_receipts" - doar bonuri fiscale
• "z_reports" - doar rapoarte Z
• "invoices" - doar facturi
• "non_fiscal_receipts" - doar bonuri nefiscale
• "numerar" - doar operațiuni de numerar (introducere/retragere)

Moduri de Ieșire (output_mode)

• "print_on_device" - raportul se tipărește pe dispozitivul fiscal; data din răspuns este gol.
• "read_line_by_line" - nu se tipărește nimic; textul raportului este returnat în data.

Răspuns:

{
  "status": 0,
  "msg": "Report data retrieved successfully",
  "data": "linia1\nlinia2\n..."      // textul raportului când output_mode = "read_line_by_line"
}

Descriere: Citește grupele de TVA programate curent pe dispozitiv.

Parametri: niciunul.

Răspuns: data este un șir JSON codificat care mapează literele grupelor la cote în sutimi de procent (basis points; 1900 = 19.00%):

{
  "status": 0,
  "msg": "Report data retrieved successfully",
  "data": "{\"A\":1900,\"B\":900,\"C\":500,\"E\":0}"
}

Descriere: Programează grupele de TVA ale dispozitivului. Atenție: pe dispozitive reale aceasta este o operațiune cu relevanță fiscală - majoritatea dispozitivelor cer mai întâi un raport Z și limitează numărul total de schimbări de TVA pe durata de viață a dispozitivului (ex: Datecs permite până la 51).

Parametri:

{
  "device_id": "...",
  "operation": {
    "type": "set_vat_rates",
    "rates": { "A": 1900, "B": 900, "C": 500, "D": null, "E": 0 }
  }
}

Răspuns:

{
  "status": 0,
  "msg": "VAT rates programming successful",
  "remaining_changes": 42            // schimbări de TVA rămase permise, sau null dacă dispozitivul nu raportează
}

După programare, driverul recitește cotele de pe dispozitiv și își actualizează automat starea din cache.

Descriere: Programează o schimbare de cote TVA care se execută automat la un moment viitor (ex: o schimbare legislativă de TVA la miezul nopții). Programările sunt persistate și supraviețuiesc repornirilor driverului; la eșec, execuția se reîncearcă la fiecare minut.

Parametri:

Răspuns:

{
  "status": 0,
  "msg": "Operation completed successfully"
}

Programările în așteptare sunt vizibile în obiectul dispozitivului (câmpul scheduled_vat_rate_changes, fiecare intrare cu id-ul ei) returnat de GET /devices/fiscal.

Descriere: Anulează o schimbare de cote TVA programată, aflată în așteptare.

Parametri:

Răspuns: {"status": 0, "msg": "Operation completed successfully"}. Returnează eroarea 400 dacă programarea nu există.

Descriere: Citește setările dispozitivului gestionate de driver.

Parametri: niciunul.

Răspuns: data este un șir JSON codificat:

{
  "status": 0,
  "msg": "Report data retrieved successfully",
  "data": "{\"block_on_auto_z_report\":false,\"include_qr_on_receipt\":true}"
}

Descriere: Scrie setările descrise la get_settings.

Parametri:

{
  "device_id": "...",
  "operation": {
    "type": "set_settings",
    "settings": {
      "block_on_auto_z_report": false,
      "include_qr_on_receipt": true
    }
  }
}

Răspuns: {"status": 0, "msg": "Operation completed successfully"}

Descriere: Rulează un auto-test de memorie fiscală pe dispozitiv.

Parametri:

Răspuns: data este un șir JSON codificat:

{
  "status": 0,
  "msg": "Report data retrieved successfully",
  "data": "{\"free_records\":14}"     // înregistrări de test rămase (0-16), sau null dacă necunoscut
}

Descriere: Citește indicatorii detaliați de stare hardware ai dispozitivului (hârtie, capac, bon deschis, memorie fiscală, …). Setul exact de câmpuri este specific dispozitivului.

Parametri: niciunul.

Răspuns: data este un șir JSON codificat:

{
  "status": 0,
  "msg": "Report data retrieved successfully",
  "data": "{\"fields\":[{\"name\":\"NoPaper\",\"description\":\"Lipsă hârtie\",\"value\":0}, ...],\"raw_data\":\"...\"}"
}

• fields[] - câte o intrare per indicator de stare: name, description lizibilă și value (0/1).
• raw_data - octeții de stare bruți raportați de dispozitiv, pentru depanare.

Descriere: Pornește o tranzacție de plată cu cardul pe terminalul POS.

Parametri:

Răspuns:

{
  "status": 0,
  "msg": "Sale successful",
  "transaction_id": "000012345678",   // RRN - păstrați-l, este necesar pentru void
  "authorization_code": "123ABC",     // păstrați-l, este necesar pentru void
  "receipt": "..."                    // textul chitanței POS, când este disponibil
}

Cazul de eroare: o tranzacție refuzată/eșuată returnează un răspuns de eroare (coduri 600–611) care poate include și un câmp receipt cu chitanța de refuz.

Descriere: Anulează (stornează) o tranzacție de vânzare anterioară.

Parametri:

Răspuns:

{
  "status": 0,
  "msg": "Void successful",
  "receipt": "..."                    // textul chitanței de anulare, când este disponibil
}

Descriere: Efectuează închiderea de zi (settlement / batch close) pe terminalul POS.

Parametri: niciunul.

Răspuns:

{
  "status": 0,
  "msg": "Settlement successful",
  "receipt": "..."                    // textul raportului de închidere, când este disponibil
}