Emitere incasare

Emite o incasare. Tipul incasarii (type) determina ce campuri sunt necesare si daca se genereaza un document numerotat.

Chitanta si Bon genereaza documente numerotate - chitanta pe seria trimisa in seriesName, bonul fiscal pe casa de marcat configurata. Celelalte tipuri (Card, Ordin plata etc.) emit incasarea fara document separat.

Emiterea unui bon fiscal

Pentru bon fiscal trimite type: Bon. Inainte de primul apel trebuie sa existe o casa de marcat implicita configurata in contul de Cloud, la Configurari > Case de marcat - pe ea se emit bonurile. Configurarea se face per utilizator: casa de marcat trebuie configurata pentru utilizatorul cu care te autentifici.

Exista doua moduri de a tipari bonul, alese prin campul returnFiscalPrinterText:

1. Tiparire din contul SmartBill - returnFiscalPrinterText: false (implicit)

Bonul este inserat in SmartBill prin API si se tipareste din contul SmartBill. Campul message din raspuns vine gol. Recomandat cand casa de marcat se afla in alta locatie fizica.

2. Tiparire directa pe casa de marcat - returnFiscalPrinterText: true

Raspunsul contine campul message cu continutul bonului codificat Base64. Continutul trebuie decodat si scris intr-un fisier cu numele si extensia configurate pentru casa de marcat (implicit bon.inp).

La emiterea unui bon, raspunsul contine id (identificatorul unic al bonului, cu care poti prelua ulterior continutul prin GET /payment/text), number (la emiterea prin API vine 0 - numarul se aloca pe casa de marcat, la tiparire) si, in cazul al doilea, message.

Modalitatea de plata se detaliaza prin campurile receivedCash, receivedCard, receivedTicheteMasa si celelalte campuri received*.

Bonul fiscal se emite doar in lei: currency trebuie sa fie RON (valoarea implicita).

Pe liniile de bon, trimite doar taxPercentage si omite taxName. Un cont poate avea mai multe cote cu acelasi procent, iar daca cea trimisa in taxName nu e configurata pe casa de marcat, apelul e respins. Fara taxName, serverul alege o cota configurata pe casa.

Casa de marcat implicita este legata de utilizator, nu de firma: bonul se emite pe casa de marcat implicita a utilizatorului cu care se face apelul la API, chiar daca alt utilizator al aceleiasi firme are alta casa setata implicit. Cotele de TVA si metodele de plata se configureaza separat pe fiecare casa de marcat, iar un bon care foloseste o cota neconfigurata pe casa respectiva este respins.

Discount pe bon fiscal

Pe bon se pot acorda discounturi, ca linii separate cu isDiscount: true.

Pentru a evita anumite limitari ale caselor de marcat (sau blocarea acestora), un discount care acopera mai multe produse se imparte in discounturi mai mici, cate unul pentru fiecare produs. Exemplu: pentru un bon cu 3 produse si un discount total aferent lor, discountul se imparte in 3 bucati, astfel incat bonul va avea 6 pozitii.

Discountul poate fi procentual (discountPercentage) sau valoric (discountValue).

La discountul valoric, discountValue se trimite negativ si se scade din totalul bonului ca valoare cu TVA. Linia de discount urmeaza aceeasi regula de preturi ca liniile de produs: cu isTaxIncluded: true sumele sunt cu TVA inclus, cu false sunt fara.

Vezi exemplul Bon fiscal cu discount valoric din lista de exemple a request-ului.

Ai primit o eroare la emiterea incasarii?

Erorile de autentificare si autorizare sunt comune tuturor endpoint-urilor V1. Pentru email/token, companyVatCode, drepturi pe firma sau pe serie, vezi Erori API V1. Mai jos gasesti doar erorile specifice emiterii incasarii.

<details> <summary><strong>Erori la emiterea incasarii</strong></summary> <table> <thead> <tr> <th>Situatie</th> <th>Eroare</th> <th>Sugestie</th> </tr> </thead> <tbody> <tr> <td>Datele clientului lipsesc</td> <td><code>Datele clientului trebuie specificate. Ele se preiau din factura doar in cazul in care usePaymentDetails = true.</code></td> <td>Trimite obiectul `client` (nume + CIF), sau `useInvoiceDetails: true` ca sa preiei clientul din factura.</td> </tr> <tr> <td>Valoarea incasarii lipseste</td> <td><code>Valoarea incasarii trebuie specificata.</code></td> <td>Trimite `value` cu suma incasata, sau `useInvoiceDetails: true` ca sa o preiei din factura.</td> </tr> <tr> <td>Tipul incasarii lipseste</td> <td><code>Tipul incasarii trebuie specificat.</code></td> <td>Trimite `type`, de exemplu `Chitanta`, `Card` sau `Ordin plata`.</td> </tr> <tr> <td>CIF client diferit de cel de pe factura (la incasare legata de factura)</td> <td><code>Ciful clientului de pe factura fac3802 difera de ciful clientului incasarii!</code></td> <td>La incasare legata de factura, clientul trebuie sa aiba acelasi CIF ca cel de pe factura. Foloseste `useInvoiceDetails: true` ca sa eviti nepotrivirea.</td> </tr> <tr> <td>Tip de incasare invalid</td> <td><code>Tipul documentului nu a fost gasit pe server!</code></td> <td>Foloseste un `type` valid: `Chitanta`, `Bon`, `Card`, `Card online`, `Ordin plata`, `Cec`, `Bilet ordin`, `Mandat postal`, `Extras de cont`, `Ramburs` sau `Alta incasare`. Litera mare nu conteaza (`Cec`, `CEC` si `cec` merg la fel), dar spatiile in plus invalideaza valoarea.</td> </tr> <tr> <td>Seria chitantei nu exista in cont</td> <td><code>Seria nu a fost gasita! Folositi o serie creata in contul de cloud.</code></td> <td>Trimite in `seriesName` o serie de chitanta creata in contul SmartBill Cloud.</td> </tr> <tr> <td>Factura din <code>invoicesList</code> nu exista</td> <td><code>Factura nu a fost gasita!</code></td> <td>Verifica `seriesName` si `number` din `invoicesList` - factura trebuie sa existe in cont.</td> </tr> <tr> <td>Factura din <code>invoicesList</code> este anulata</td> <td><code>Factura API0059 este anulata, nu o puteti incasa. Restaurati intai factura sau emiteti incasarea independent de factura.</code></td> <td>Restaureaza factura cu [PUT /invoice/restore](#tag/facturi/PUT/invoice/restore), sau emite incasarea fara `invoicesList`, trimitand `client` si `value`.</td> </tr> <tr> <td>Factura este deja incasata integral sau stornata</td> <td><code>Factura este incasata sau stornata in totalitate.</code></td> <td>Verifica intai cu [GET /invoice/paymentstatus](#tag/facturi/GET/invoice/paymentstatus) cat mai e de incasat. O factura cu `unpaidAmount` zero nu mai accepta incasari.</td> </tr> <tr> <td>Bon fiscal pentru o firma neplatitoare de TVA, fara configurarea corespunzatoare a casei de marcat</td> <td><code>Configurarea casei de marcat pentru firma neplatitoare de TVA nu a fost facuta.</code></td> <td>Verifica in contul SmartBill Cloud, la `Configurari > Case de marcat`, ca modalitatile de incasare au ID-urile salvate pe casa de marcat, ca ID-urile cotelor TVA sunt completate la `Configurari > Cote TVA` si ca te autentifici cu utilizatorul pe care este configurata casa de marcat - configurarea se face per utilizator.</td> </tr> <tr> <td>Nu exista casa de marcat configurata pentru utilizatorul care face apelul</td> <td><code>Nu s-a gasit casa de marcat pentru userul x.</code></td> <td>Configureaza o casa de marcat in contul SmartBill Cloud, la `Configurari > Case de marcat`, pentru utilizatorul cu care te autentifici.</td> </tr> <tr> <td>Cota de TVA din liniile bonului nu e configurata pe casa de marcat implicita a utilizatorului</td> <td><code>Cota TVA Normala (21.00%) nu a fost configurata pentru casa de marcat selectata</code></td> <td>Cel mai simplu: omite `taxName` si trimite doar `taxPercentage` - serverul alege atunci o cota configurata pe casa. Altfel, configureaza cota trimisa in `taxName` pe casa de marcat, in contul SmartBill Cloud la `Configurari > Case de marcat`. Cotele se configureaza pe fiecare casa separat, iar casa implicita difera de la un utilizator la altul.</td> </tr> <tr> <td>Bon fiscal emis in alta moneda decat leul</td> <td><code>Bonurile fiscale pot fi emise doar in Lei!</code></td> <td>Trimite `currency: RON`, sau omite campul - `RON` este valoarea implicita.</td> </tr> <tr> <td>Bon fiscal cu metode de plata care nu sunt configurate pe casa de marcat</td> <td><code>Au fost inregistrate urmatoarele plati partiale cu metode de plata neconfigurate pe casa de marcat: Card: 10, Numerar: 5</code></td> <td>Verifica configurarile casei de marcat din contul SmartBill Cloud - fiecare metoda folosita in campurile `received*` trebuie sa fie configurata pe casa de marcat.</td> </tr> </tbody> </table> </details>

---

Tipuri de incasare

<details> <summary><strong>1. Card</strong></summary>

Emite o incasare cu cardul. Nu necesita serie si nu genereaza document separat.

{
  "companyVatCode": "CIF_FIRMA",
  "issueDate": "2026-06-15",
  "client": {
    "name": "Client SRL",
    "vatCode": "RO22222222",
    "address": "Str. Lalelei 1",
    "city": "Sector 1",
    "county": "Bucuresti",
    "country": "Romania"
  },
  "value": 119,
  "type": "Card"
}

</details> <details> <summary><strong>2. Chitanta</strong></summary>

Genereaza un document de chitanta cu numar din seria specificata. Necesita seriesName si isCash: true.

{
  "companyVatCode": "CIF_FIRMA",
  "seriesName": "SERIA_CHITANTEI",
  "issueDate": "2026-06-15",
  "client": {
    "name": "Client SRL",
    "vatCode": "RO22222222",
    "address": "Str. Lalelei 1",
    "city": "Sector 1",
    "county": "Bucuresti",
    "country": "Romania"
  },
  "value": 119,
  "text": "Plata factura",
  "type": "Chitanta",
  "isCash": true
}

</details> <details> <summary><strong>3. Chitanta ciorna (draft)</strong></summary>

Salveaza chitanta ca ciorna - fara numar atribuit pana la finalizare din interfata SmartBill Cloud. Functioneaza doar pentru tipul Chitanta.

{
  "companyVatCode": "CIF_FIRMA",
  "seriesName": "SERIA_CHITANTEI",
  "issueDate": "2026-06-15",
  "isDraft": true,
  "client": {
    "name": "Client SRL",
    "vatCode": "RO22222222",
    "address": "Str. Lalelei 1",
    "city": "Sector 1",
    "county": "Bucuresti",
    "country": "Romania"
  },
  "value": 119,
  "text": "Plata factura",
  "type": "Chitanta",
  "isCash": true
}

</details> <details> <summary><strong>4. Bon fiscal</strong></summary>

Emite un bon pe casa de marcat configurata implicit in contul de Cloud (Configurari > Case de marcat). Necesita type: Bon si liniile de produse in products.

Campul returnFiscalPrinterText alege modul de tiparire:

• false (implicit) - bonul se tipareste din contul SmartBill, iar campul message din raspuns vine gol. Recomandat cand casa de marcat se afla in alta locatie fizica.
• true - raspunsul contine message, continutul bonului codificat Base64. Trebuie decodat si scris intr-un fisier cu numele si extensia configurate pentru casa de marcat (implicit bon.inp).

Modalitatea de plata se detaliaza prin campurile received*. Bonul se emite doar in lei: currency trebuie sa fie RON (valoarea implicita).

{
  "companyVatCode": "CIF_FIRMA",
  "issueDate": "2026-06-15",
  "client": {
    "name": "Client SRL",
    "vatCode": "RO22222222",
    "address": "Str. Lalelei 1",
    "city": "Sector 1",
    "county": "Bucuresti",
    "country": "Romania"
  },
  "products": [
    {
      "name": "Produs 1",
      "code": "PRD001",
      "quantity": 1,
      "measuringUnitName": "buc",
      "taxPercentage": 21,
      "price": 10
    }
  ],
  "value": 10,
  "type": "Bon",
  "returnFiscalPrinterText": true,
  "receivedCash": 10
}

Raspunsul contine id (folosit ulterior la GET /payment/text), number si, cand returnFiscalPrinterText este true, message.

</details> <details> <summary><strong>5. Ordin de plata</strong></summary>

Emite o incasare prin ordin de plata. Nu necesita serie si nu genereaza document separat.

{
  "companyVatCode": "CIF_FIRMA",
  "issueDate": "2026-06-15",
  "client": {
    "name": "Client SRL",
    "vatCode": "RO22222222",
    "address": "Str. Lalelei 1",
    "city": "Sector 1",
    "county": "Bucuresti",
    "country": "Romania"
  },
  "value": 119,
  "text": "Plata factura",
  "type": "Ordin plata"
}

</details> <details> <summary><strong>6. Incasare legata de o factura</strong></summary>

Asociaza incasarea cu una sau mai multe facturi existente prin invoicesList.

{
  "companyVatCode": "CIF_FIRMA",
  "seriesName": "SERIA_CHITANTEI",
  "issueDate": "2026-06-15",
  "client": {
    "name": "Client SRL",
    "vatCode": "RO22222222",
    "address": "Str. Lalelei 1",
    "city": "Sector 1",
    "county": "Bucuresti",
    "country": "Romania"
  },
  "value": 119,
  "type": "Chitanta",
  "isCash": true,
  "invoicesList": [{ "seriesName": "SERIA_FACTURII", "number": "0025" }]
}

</details> <details> <summary><strong>7. Incasare cu preluare date din factura</strong></summary>

Cu useInvoiceDetails: true, clientul si suma sunt preluate automat din factura - nu mai e nevoie sa le trimiti explicit.

Doua lucruri de stiut:

• value nu e ignorat daca il trimiti oricum. Pe o factura de 111 lei, o incasare cu value: 50 inregistreaza 50 si lasa 61 de incasat. Asa se face o incasare partiala.
• invoicesList accepta mai multe facturi. Un singur apel inregistreaza incasarea pe toate facturile din lista.

O factura anulata nu poate fi incasata: apelul intoarce 400 cu Factura <serie><numar> este anulata, nu o puteti incasa. Restaurati intai factura sau emiteti incasarea independent de factura.. O factura deja incasata integral intoarce 400 cu Factura este incasata sau stornata in totalitate..

{
  "companyVatCode": "CIF_FIRMA",
  "issueDate": "2026-06-15",
  "type": "Ordin plata",
  "useInvoiceDetails": true,
  "invoicesList": [{ "seriesName": "SERIA_FACTURII", "number": "0025" }]
}

</details>

{
  "client": {
    "name": "Acme SRL",
    "vatCode": "RO22222222",
    "regCom": "J40/1234/2020",
    "address": "Str. Exemplu 1",
    "city": "Sector 1",
    "county": "Bucuresti",
    "country": "Romania",
    "email": "client@example.com"
  },
  "products": [
    {
      "name": "Produs 1",
      "quantity": 1,
      "measuringUnitName": "buc",
      "price": 100,
      "taxName": "Normala",
      "taxPercentage": 21
    }
  ]
}