Referință

Tipuri de comandă

Referință pentru fiecare comandă fiscală pe care e-bon o trimite către AMEF — corpul cererii, forma rezultatului și ce face fiecare comandă pe dispozitiv.

Tipuri de comandă

Fiecare acțiune fiscală pe care POS-ul tău o face prin e-bon — emiterea unui bon, deschiderea sertarului de bani, închiderea zilei cu raport Z — este trimisă ca o comandă tipizată către un dispozitiv AMEF înregistrat.

Această pagină este referința per tip. Pentru fiecare comandă enumeră identificatorul de protocol pe care îl trimiți în corpul cererii, payload-ul JSON (când este necesar) și ce întoarce dispozitivul. Folosește-o împreună cu pagina API Comenzi, care documentează plicul HTTP, polling-ul și idempotența.

Trimite o comandă

Toate tipurile de comandă folosesc același punct de intrare HTTP:

POST /api/v1/devices/:deviceId/commands
Content-Type: application/json
Authorization: Bearer <cheie-api>

{
  "type": "print_receipt",
  "payload": { /* corp specific tipului, vezi mai jos */ }
}

Un singur domeniu de cheie API (commands) autorizează toate tipurile de comandă enumerate aici. Vezi Chei API pentru cum se generează și se rotesc cheile.

Catalogul comenzilor

Cele 27 de tipuri de comandă, grupate după scop:

Identificator	Categorie	Payload	Scop
`print_receipt`	Bonuri	obligatoriu	Emitere bon fiscal de vânzare.
`void_receipt`	Bonuri	obligatoriu	Anularea unui bon emis anterior, după ID.
`print_reversal_receipt`	Bonuri	obligatoriu	Emitere storno (bon fiscal de stornare).
`void_open_receipt`	Bonuri	fără	Anularea unui bon deschis pe dispozitiv.
`print_duplicate`	Bonuri	fără	Reimprimarea ultimului bon ca duplicat nefiscal.
`non_fiscal_receipt`	Bonuri	obligatoriu	Tipărire liberă, nefiscală.
`x_report`	Rapoarte	fără	Citire totaluri ale zilei fără închiderea ei.
`z_report`	Rapoarte	fără	Închidere zi fiscală și înscriere totaluri în memoria fiscală.
`cash_in`	Numerar	obligatoriu	Înregistrare depunere de numerar.
`cash_out`	Numerar	obligatoriu	Înregistrare ridicare de numerar.
`get_cash_amount`	Numerar	fără	Citire sold curent de numerar.
`open_drawer`	Numerar	fără	Deschiderea sertarului de bani.
`set_datetime`	Configurare	opțional	Setarea ceasului dispozitivului.
`set_logo`	Configurare	obligatoriu	Încărcarea unui bitmap de siglă.
`delete_logo`	Configurare	fără	Ștergerea siglei configurate.
`set_vat_rates`	Configurare	obligatoriu	Configurarea tabelei de cote TVA.
`set_header_footer`	Configurare	obligatoriu	Înlocuirea rândurilor de antet și subsol.
`set_operator`	Configurare	obligatoriu	Adăugarea sau înlocuirea unui operator.
`get_status`	Diagnostic	fără	Citire stare hârtie, capac și erori.
`get_info`	Diagnostic	fără	Citire serie, firmware și stare memorie fiscală.
`get_last_receipt_info`	Diagnostic	fără	Citire metadate ale ultimului bon emis.
`get_vat_rates`	Diagnostic	fără	Citire tabel de cote TVA configurate.
`get_vat_capabilities`	Diagnostic	fără	Citire cote TVA acceptate de firmware.
`get_header_footer_capabilities`	Diagnostic	fără	Citire limite de rânduri și lățime pentru antet/subsol.
`get_header_footer`	Diagnostic	fără	Citire antet și subsol curent configurate.
`get_operator_capabilities`	Diagnostic	fără	Citire număr de operatori și limite de parolă.
`raw_command`	Brut	propagare	Trimitere de octeți specifici protocolului către driver.

Bonuri

Emite un bon fiscal

Emite un bon fiscal de vânzare pe AMEF.

Tip: print_receipt

{
  "items": [
    { "name": "Cafea", "quantity": 2, "price": 9.5, "vatRate": 21, "department": 1 }
  ],
  "payments": [
    { "type": "cash", "amount": 19.0 }
  ]
}

Câmp	Tip	Obligatoriu	Note
`items`	listă	da	Trebuie să fie nevidă.
`items[].name`	string	da	Nume de produs nevid.
`items[].quantity`	număr	da	Strict pozitiv.
`items[].price`	număr	da	Preț unitar.
`items[].vatRate`	număr	da	Una din `0`, `9`, `11`, `21` (cote TVA românești).
`items[].department`	număr	nu	Index departament pe dispozitiv.
`payments`	listă	da	Trebuie să fie nevidă.
`payments[].type`	string	da	Una din `cash`, `card`, `voucher`, `other`.
`payments[].amount`	număr	da	Strict pozitiv.

Totalul items (cantitate × preț) trebuie să fie egal cu totalul payments cu o toleranță de 0.01.

La succes: result.fiscalId poartă ID-ul fiscal atribuit de AMEF. Detaliile specifice driverului ajung în result.data.

Vezi și: API Bonuri, Fluxul de emitere a bonului.

Anulează un bon

Anulează un bon fiscal emis anterior, după ID-ul său.

Tip: void_receipt

{ "receiptId": "rcpt_01HZ..." }

Câmp	Tip	Obligatoriu	Note
`receiptId`	string	da	ID-ul bonului de anulat.

Emite un bon de stornare

Emite un storno (bon fiscal de stornare) care anulează legal o vânzare anterioară și face referire la bonul original.

Tip: print_reversal_receipt

{
  "uniqueSaleNumber": "USN-2026-000123",
  "originalReceiptNumber": "0000456",
  "originalReceiptDateTime": "2026-04-20T14:32:11Z",
  "fiscalMemorySerialNumber": "DY12345678",
  "originalZReportNumber": "12",
  "reason": "operator_error",
  "items": [
    { "name": "Cafea", "quantity": 1, "price": 9.5, "vatRate": 21 }
  ],
  "payments": [
    { "type": "cash", "amount": 9.5 }
  ]
}

Câmp	Tip	Obligatoriu	Note
`uniqueSaleNumber`	string	da	USN-ul vânzării originale.
`originalReceiptNumber`	string	da	Numărul bonului de stornat.
`originalReceiptDateTime`	string	da	Dată ISO-8601 validă.
`fiscalMemorySerialNumber`	string	da	Seria AMEF-ului original.
`originalZReportNumber`	string	nu	Numărul raportului Z, dacă este cunoscut.
`reason`	string	da	Una din `operator_error`, `refund`, `tax_base_reduction`.
`items`	listă	da	Aceleași reguli per articol ca la `print_receipt`.
`payments`	listă	nu	Dacă este prezent, urmează aceleași reguli ca la `print_receipt` și se verifică suma.

La succes: ID-ul fiscal al bonului de stornare se întoarce în result.fiscalId.

Vezi și: USN, Storno.

Anulează un bon deschis

Anulează un bon care este deschis în acest moment pe dispozitiv. Folosește această comandă pentru a reseta starea după o întrerupere hardware sau de operator.

Tip: void_open_receipt — fără payload.

Reimprimă ultimul bon

Reimprimă ultimul bon ca duplicat nefiscal.

Tip: print_duplicate — fără payload.

Tipărește un bon nefiscal

Tipărește un bon liber, nefiscal — pre-bon, bon de fidelitate, anunț. Tipăririle nefiscale nu se înscriu în memoria fiscală și nu au ID fiscal.

Tip: non_fiscal_receipt

{
  "lines": ["Mulțumim pentru vizită", "Vă așteptăm cu drag!"],
  "header": "Bon de fidelitate"
}

Câmp	Tip	Obligatoriu	Note
`lines`	string	da	Listă nevidă de rânduri.
`header`	string	nu	Rând de antet opțional.

Rapoarte

Citește un raport X

Citește totalurile zilei fără a o închide. Întoarce totaluri, defalcare TVA și număr de bonuri în result.data.

Tip: x_report — fără payload.

La succes, e-bon trimite suplimentar webhook-ul report.generated.

Vezi și: Raport X.

Închide ziua cu un raport Z

Închide ziua fiscală, îngheață totalurile zilei în memoria fiscală și resetează contoarele zilnice.

Tip: z_report — fără payload.

La succes, e-bon trimite suplimentar webhook-ul report.generated.

Vezi și: Raport Z.

Numerar

Înregistrează o depunere

Înregistrează o depunere de numerar în sertarul dispozitivului.

Tip: cash_in

{ "amount": 200, "description": "Fond de început de zi" }

Câmp	Tip	Obligatoriu	Note
`amount`	număr	da	Strict pozitiv.
`description`	string	nu	Notă text liber.

Înregistrează o ridicare

Înregistrează o ridicare de numerar din sertar. Aceeași schemă ca cash_in.

Tip: cash_out

{ "amount": 50, "description": "Depunere la bancă" }

Citește soldul de numerar

Citește soldul curent de numerar urmărit de dispozitiv pentru sertar. Întoarce { cashBalance, currency } în result.data.

Tip: get_cash_amount — fără payload.

Deschide sertarul de bani

Deschide sertarul de bani fără a tipări nimic.

Tip: open_drawer — fără payload.

Configurare

Setează ceasul dispozitivului

Sincronizează ceasul dispozitivului, opțional la un moment specificat.

Tip: set_datetime

{ "datetime": "2026-04-25T10:00:00Z" }

Câmp	Tip	Obligatoriu	Note
`datetime`	string	nu	Dacă este prezent, trebuie să fie o dată ISO-8601 validă. Dacă lipsește, dispozitivul se sincronizează la ora curentă a serverului.

Încarcă o siglă

Încarcă un bitmap de siglă pe care dispozitivul îl tipărește în partea de sus a bonurilor.

Tip: set_logo

{ "logo": "iVBORw0KGgoAAAANSUhEUgAA..." }

Câmp	Tip	Obligatoriu	Note
`logo`	string	da	Bitmap codat base64.

Fiecare firmware AMEF are propriile limite de dimensiune și format pentru sigle. Verifică documentația dispozitivului înainte de a încărca bitmap-uri mari sau neobișnuite.

Șterge sigla

Elimină sigla configurată pe dispozitiv.

Tip: delete_logo — fără payload.

Configurează cotele TVA

Configurează tabela de cote TVA denumite a dispozitivului (de exemplu A → 21, B → 9).

Tip: set_vat_rates

{
  "rates": [
    { "name": "A", "percentage": 21 },
    { "name": "B", "percentage": 9 }
  ]
}

Câmp	Tip	Obligatoriu	Note
`rates`	listă	da	Cel puțin o intrare.
`rates[].name`	string	da	Nume slot TVA.
`rates[].percentage`	număr	da	Procent non-negativ.

Setează antetul și subsolul

Înlocuiește rândurile tipărite în partea de sus și de jos a fiecărui bon.

Tip: set_header_footer

{
  "header": ["Cafeneaua mea SRL", "Bd. Magheru 12, București"],
  "footer": ["Mulțumim!", "www.exemplu.ro"]
}

Câmp	Tip	Obligatoriu	Note
`header`	string	da	Rânduri de antet (lista poate fi vidă).
`footer`	string	da	Rânduri de subsol (lista poate fi vidă).

Citește mai întâi limitele dispozitivului cu get_header_footer_capabilities — numărul de rânduri și lățimea în caractere variază în funcție de firmware.

Configurează un operator

Adaugă sau înlocuiește un slot de operator (identitate de casier) pe dispozitiv.

Tip: set_operator

{ "operatorId": 1, "name": "Maria", "password": "1234" }

Câmp	Tip	Obligatoriu	Note
`operatorId`	număr	da	Întreg ≥ 1.
`name`	string	da	Numele operatorului.
`password`	string	nu	Parolă opțională.

Citește mai întâi limitele dispozitivului cu get_operator_capabilities — numărul de sloturi și suportul pentru parolă variază în funcție de firmware.

Diagnostic

Citește starea dispozitivului

Citește starea operațională curentă — hârtie, capac, stare zi fiscală și eventuale erori.

Tip: get_status — fără payload.

Citește identitatea dispozitivului

Citește seria, versiunea de firmware, starea memoriei fiscale, producătorul și modelul dispozitivului.

Tip: get_info — fără payload.

Întoarce { serialNumber, firmwareVersion, fiscalMemoryStatus, manufacturer, model? } în result.data.

Citește ultimul bon

Citește metadatele ultimului bon emis.

Tip: get_last_receipt_info — fără payload.

Întoarce { receiptNumber, date, total, fiscalMemoryNumber? } în result.data.

Citește cotele TVA configurate

Citește tabela de cote TVA configurate în acest moment pe dispozitiv.

Tip: get_vat_rates — fără payload.

Întoarce o listă de { name, percentage } în result.data.

Citește cotele TVA suportate

Citește cotele TVA pe care firmware-ul dispozitivului le acceptă (cotele posibile, nu cele configurate).

Tip: get_vat_capabilities — fără payload.

Citește limitele pentru antet/subsol

Citește limitele de antet și subsol ale dispozitivului.

Tip: get_header_footer_capabilities — fără payload.

Întoarce { maxHeaderLines, maxFooterLines, maxCharsPerLine } în result.data.

Citește antetul și subsolul configurate

Citește antetul și subsolul configurate în acest moment pe dispozitiv.

Tip: get_header_footer — fără payload.

Întoarce { header: string[], footer: string[] } în result.data.

Citește limitele de operator

Citește numărul de sloturi de operator și constrângerile de parolă suportate de firmware.

Tip: get_operator_capabilities — fără payload.

Întoarce { maxOperators, maxNameLength, maxPasswordLength, supportsPassword } în result.data.

Trimite o comandă brută

Cale de ieșire specifică driverului pentru trimiterea de octeți specifici protocolului atunci când nu există o comandă tipizată. Orice trimiți în payload este propagat direct către driverul dispozitivului.

Tip: raw_command

raw_command ocolește toate verificările de payload pe care le face e-bon. Folosit incorect, poate aduce un dispozitiv într-o stare nefuncțională sau emite ieșire fiscală neconformă. Tratează-l ca pe un instrument de diagnostic, nu ca pe un primitiv de producție.

Urmărește rezultatul unei comenzi

Fiecare comandă, indiferent de tip, trece prin același ciclu de viață. Câmpul status de pe documentul de comandă ia una din șase valori:

Stare	Când o vezi
`pending`	API-ul a acceptat și a persistat comanda — comanda este în așteptare.
`sent`	Comanda este în drum spre dispozitiv.
`processing`	Dispozitivul a confirmat-o și o procesează.
`completed`	Dispozitivul a întors succes — comanda a fost acceptată. `result.data` și (pentru bonuri) `result.fiscalId` sunt populate.
`failed`	Dispozitivul sau dispecerul au raportat eroare — comanda a fost respinsă. `result.errorCode` și `result.errorMessage` sunt populate.
`timeout`	Dispozitivul nu a răspuns în timp util. `result.errorCode` este `E500` (`TimeoutCommand`). Poți face o nouă încercare.

Plicul complet al rezultatului este { success, data?, fiscalId?, errorCode?, errorMessage? }.

Unde mergi mai departe

API Comenzi — plicul HTTP, polling-ul și idempotența.
SDK Comenzi — învelișuri tipizate peste acest catalog.
Fluxul de emitere a bonului — pipeline cap-coadă.
Erori — valorile errorCode care apar în rezultatele comenzilor.
Glosar — USN, storno, AMEF, MF, raport X / raport Z.

Editează această pagină

Glosar

Referință A→Z pentru termenii fiscali românești și specifici e-bon folosiți în această documentație.

Stările pe care le vezi în bonuri, dispozitive și webhook-uri

Referință pentru fiecare valoare de stare pe care e-bon o întoarce în răspunsurile API, în plicurile de webhook și în portal — ce înseamnă și când o vezi.