Operațiuni Dispozitive

Această secțiune prezintă operațiunile dispozitivelor suportate care pot fi executate prin API HTTP, API WebSocket sau fișiere INP. Toate operațiunile sunt puternic tipizate și urmează o structură unificată.

Important: Toate operațiunile dispozitivelor necesită un device_id valid (UUID) care corespunde unui dispozitiv fiscal sau terminal POS configurat în sistem.

Operațiuni Dispozitive Fiscale

Următoarele operațiuni sunt disponibile pentru dispozitivele de tipărire fiscală. Toate sumele sunt specificate în bani (cea mai mică unitate monetară).

print_receipt

Descriere: Tipărește un bon fiscal cu articole, plăți și informații opționale ale cumpărătorului. Aceasta este operațiunea cea mai complexă și importantă din sistem.

Parametri:

Parametru	Tip	Obligatoriu	Descriere
`lines`	Array<ReceiptLine>	Da	Array de linii bon (articole, text și subtotal)
`payments`	Array<PaymentLine>	Da*	Metode și sume de plată (*auto-calculat dacă omis)
`buyer`	BuyerInfo	Nu	Informații cumpărător pentru facturi
`receipt_discount`	Discount	Nu	Reducere sau adaos la nivel de bon
`flags`	ReceiptFlags	Nu	Flag-uri comportament bon (implicit: bon fiscal)
`close_action`	CloseAction	Nu	`"close"` sau `"void"` (implicit: "close")

Obiect ReceiptLine

Liniile bonului pot fi articole, text liber sau operațiuni de subtotal:

// Linie articol
{
  "type": "item",
  "description": "Nume Produs",
  "quantity_thousandths": 1000,    // 1000 = 1.000 bucăți
  "unit_price_cents": 1500,        // 1500 = 15.00 unități monetare
  "vat": "19%",                    // Poate fi procent (ex., "19%") sau literă ("A", "B", etc.)
  "discount": {                    // Reducere opțională la nivel de articol
    "kind": "percent",
    "basis_points": 1000,          // 1000 = 10.00%
    "is_surcharge": false
  },
  "um": "buc"                      // Unitatea de măsură (opțional)
}

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

// Linie subtotal
{
  "type": "subtotal",
  "discount": {                    // Reducere opțională la nivel de subtotal
    "kind": "percent",
    "basis_points": 1000,          // 1000 = 10.00%
    "is_surcharge": false
  }
}

Note:

Este permis un singur subtotal cu reducere pe bon.
Nu puteți utiliza o reducere la subtotal dacă există și o reducere globală (receipt_discount).

Obiect PaymentLine

{
  "method": "cash",                // "cash", "card", "credit", "tichete_masa", etc.
  "amount_cents": 1500             // Suma plății în bani
}

Obiect BuyerInfo

{
  "vat_number": "RO12345678"       // Număr TVA (CUI/CIF)
}

Obiect Discount

// Reducere procentuală
{
  "kind": "percent",
  "basis_points": 1000,            // 1000 = 10.00%
  "is_surcharge": false            // false = reducere, true = adaos
}

// Reducere sumă absolută
{
  "kind": "absolute", 
  "amount_cents": 500,             // 500 = 5.00 unități monetare
  "is_surcharge": false
}

Răspuns:

{
  "status": 0,
  "msg": "Bon tipărit",
  "slip_number": 123               // Numărul bonului fiscal
}

Auto Card-către-POS: Dacă este activat în configurația dispozitivului, plățile cu cardul din bon vor declanșa automat o tranzacție de vânzare POS înainte de tipărirea bonului fiscal.

print_non_fiscal_receipt

Descriere: Tipărește un bon non-fiscal (text liber) pe dispozitivul fiscal. Util pentru note de plată, bonuri de comandă sau alte informații care nu necesită fiscalizare.

Parametri:

Parametru	Tip	Obligatoriu	Descriere
`lines`	Array<NonFiscalLine>	Da	Array de linii de text pentru bonul non-fiscal

Obiect NonFiscalLine

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

// Linie text cu formatare (Doar DATECS - ignorat pe alte dispozitive)
{
  "type": "text",
  "text": "Text formatat",
  "formatting": {
    "bold": true,
    "italic": false,
    "double_height": true,
    "underline": false,
    "alignment": "center", // "left", "center", "right"
    "condensed": false
  }
}

Răspuns:

{
  "status": 0,
  "msg": "Bon tipărit"
}

print_x

Descriere: Tipărește un raport X (rezumat zilnic non-fiscal).

Parametri: Niciun parametru

Răspuns:

{
  "status": 0,
  "msg": "Raport tipărit",
  "report_number": 45
}

print_z

Descriere: Tipărește un raport Z (închidere fiscală zilnică).

Parametri: Niciun parametru

Răspuns:

{
  "status": 0,
  "msg": "Raport tipărit", 
  "report_number": 46
}

deposit_cash

Descriere: Înregistrează un depozit de numerar în dispozitivul fiscal.

Parametri:

Parametru	Tip	Obligatoriu	Descriere
`amount`	integer	Da	Suma depozitului în bani (trebuie să fie > 0)

Răspuns:

{
  "status": 0,
  "msg": "Operațiune numerar reușită",
  "total_cash_drawer": 15000       // Total numerar în sertar după operațiune (bani)
}

withdraw_cash

Descriere: Înregistrează o retragere de numerar din dispozitivul fiscal.

Parametri:

Parametru	Tip	Obligatoriu	Descriere
`amount`	integer	Da	Suma retragerii în bani (trebuie să fie > 0)

Răspuns:

{
  "status": 0,
  "msg": "Operațiune numerar reușită",
  "total_cash_drawer": 10000       // Total numerar în sertar după operațiune (bani)
}

chime

Descriere: Declanșează semnalul acustic (bip) pe dispozitivul fiscal.

Parametri: Niciun parametru

Răspuns:

{
  "status": 0,
  "msg": "Operațiune finalizată cu succes"
}

open_drawer

Descriere: Deschide sertarul de numerar conectat la dispozitivul fiscal.

Parametri:

Parametru	Tip	Obligatoriu	Descriere
pulse_duration_ms	număr	Nu	Durata impulsului de deschidere a sertarului în milisecunde. Implicit: 100. Notă: Ignorat de dispozitivele Tremol.

Răspuns:

{
  "status": 0,
  "msg": "Operațiune finalizată cu succes"
}

anaf_export

Descriere: Exportă datele fiscale pentru raportarea ANAF (autoritatea fiscală română).

Parametri:

Parametru	Tip	Obligatoriu	Descriere
`range`	AnafExportRange	Da	Interval de date sau număr Z pentru export
`destination_path`	string	Da	Calea completă unde să salveze fișierul de export

Obiect AnafExportRange

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

// Interval număr Z  
{
  "start": 1,
  "end": 10
}

Răspuns:

{
  "status": 0,
  "msg": "Operațiune finalizată cu succes"
}

anaf_status

Descriere: Preia starea sincronizării ANAF din dispozitivul fiscal.

Parametri: Niciun parametru

Răspuns:

{
  "status": 0,
  "msg": "Datele raportului preluate cu succes",
  "data": "{\"Success\":{}}"        // String JSON cu detalii stare ANAF
}

load_logo

Descriere: Încarcă o imagine logo în dispozitivul fiscal pentru tipărirea pe bonuri.

Parametri:

Parametru	Tip	Obligatoriu	Descriere
`image_data`	string	Da	Date imagine codificate Base64 (PNG, JPG, etc.)

Răspuns:

{
  "status": 0,
  "msg": "Operațiune finalizată cu succes"
}

fiscal_memory_report

Descriere: Generează un raport de memorie fiscală pentru un interval specificat de date sau număr Z.

Parametri:

Parametru	Tip	Obligatoriu	Descriere
`range`	FiscalRange	Da	Interval de date sau număr Z
`report_type`	string	Da	`"short"` sau `"detailed"`

Obiect FiscalRange

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

// Interval număr Z
{
  "start": 1,
  "end": 10
}

Răspuns:

{
  "status": 0,
  "msg": "Operațiune finalizată cu succes"
}

je_report

Descriere: Generează un raport jurnal electronic (JE) cu opțiuni de filtrare.

Parametri:

Parametru	Tip	Obligatoriu	Descriere
`range`	JeReportRange	Da	Specificația intervalului pentru raport
`doc_type`	string	Da	Filtru tip document
`output_mode`	string	Da	Destinația ieșirii

Obiect JeReportRange

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

// Interval număr Z
{
  "type": "z_number", 
  "start": 1,
  "end": 10
}

// Interval număr document
{
  "type": "doc_number",
  "start": 100,
  "end": 200
}

Tipuri Documente

"all" - Toate tipurile de documente
"fiscal_receipts" - Doar bonuri fiscale
"z_reports" - Doar rapoarte Z
"invoices" - Doar facturi
"non_fiscal_receipts" - Doar bonuri non-fiscale
"numerar" - Doar operațiuni numerar

Moduri Ieșire

"print_on_device" - Tipărește raportul pe imprimanta dispozitivului fiscal
"read_line_by_line" - Returnează datele raportului pentru afișare/procesare

Răspuns:

{
  "status": 0,
  "msg": "Datele raportului preluate cu succes",
  "data": "Conținut raport..."       // Conține datele raportului dacă output_mode este "read_line_by_line"
}

Operațiuni Terminal POS

Următoarele operațiuni sunt disponibile pentru terminalele de plată POS:

sale

Descriere: Inițiază o tranzacție de plată pe terminalul POS.

Parametri:

Parametru	Tip	Obligatoriu	Descriere
`amount`	integer	Da	Suma tranzacției în bani (trebuie să fie > 0)

Răspuns:

{
  "status": 0,
  "msg": "Vânzare reușită: [detalii_tranzacție]"
}

settlement

Descriere: Efectuează o închidere de zi pe terminalul POS.

Parametri: Niciun parametru

Răspuns:

{
  "status": 0,
  "msg": "Închidere reușită: [detalii_închidere]"
}

Format Răspuns Comun

Toate operațiunile dispozitivelor returnează un format standardizat de răspuns:

{
  "status": 0,                     // 0 = succes, non-zero = eroare
  "msg": "Descriere operațiune",  // Mesaj lizibil pentru om
  // ... câmpuri suplimentare specifice operațiunii
}

Pentru răspunsurile de eroare, formatul este:

{
  "status": [cod_eroare],          // Număr negativ pentru erori
  "error": "Descriere eroare"    // Mesaj detaliat de eroare
}

Exemple de Utilizare

Consultați paginile API HTTP și API WebSocket pentru exemple complete despre cum să invocați aceste operațiuni.