--- title: "Emitere incasare" method: POST path: "/payment" tags: ["Incasari"] --- # Emitere incasare `POST /payment` 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](#api-1/description/erori-api-v1). Mai jos gasesti doar erorile specifice emiterii incasarii.
Erori la emiterea incasarii
Situatie Eroare Sugestie
Datele clientului lipsesc Datele clientului trebuie specificate. Ele se preiau din factura doar in cazul in care usePaymentDetails = true. Trimite obiectul `client` (nume + CIF), sau `useInvoiceDetails: true` ca sa preiei clientul din factura.
Valoarea incasarii lipseste Valoarea incasarii trebuie specificata. Trimite `value` cu suma incasata, sau `useInvoiceDetails: true` ca sa o preiei din factura.
Tipul incasarii lipseste Tipul incasarii trebuie specificat. Trimite `type`, de exemplu `Chitanta`, `Card` sau `Ordin plata`.
CIF client diferit de cel de pe factura (la incasare legata de factura) Ciful clientului de pe factura fac3802 difera de ciful clientului incasarii! La incasare legata de factura, clientul trebuie sa aiba acelasi CIF ca cel de pe factura. Foloseste `useInvoiceDetails: true` ca sa eviti nepotrivirea.
Tip de incasare invalid Tipul documentului nu a fost gasit pe server! 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.
Seria chitantei nu exista in cont Seria nu a fost gasita! Folositi o serie creata in contul de cloud. Trimite in `seriesName` o serie de chitanta creata in contul SmartBill Cloud.
Factura din invoicesList nu exista Factura nu a fost gasita! Verifica `seriesName` si `number` din `invoicesList` - factura trebuie sa existe in cont.
Factura din invoicesList este anulata Factura API0059 este anulata, nu o puteti incasa. Restaurati intai factura sau emiteti incasarea independent de factura. Restaureaza factura cu [PUT /invoice/restore](#tag/facturi/PUT/invoice/restore), sau emite incasarea fara `invoicesList`, trimitand `client` si `value`.
Factura este deja incasata integral sau stornata Factura este incasata sau stornata in totalitate. 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.
Bon fiscal pentru o firma neplatitoare de TVA, fara configurarea corespunzatoare a casei de marcat Configurarea casei de marcat pentru firma neplatitoare de TVA nu a fost facuta. 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.
Nu exista casa de marcat configurata pentru utilizatorul care face apelul Nu s-a gasit casa de marcat pentru userul x. Configureaza o casa de marcat in contul SmartBill Cloud, la `Configurari > Case de marcat`, pentru utilizatorul cu care te autentifici.
Cota de TVA din liniile bonului nu e configurata pe casa de marcat implicita a utilizatorului Cota TVA Normala (21.00%) nu a fost configurata pentru casa de marcat selectata 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.
Bon fiscal emis in alta moneda decat leul Bonurile fiscale pot fi emise doar in Lei! Trimite `currency: RON`, sau omite campul - `RON` este valoarea implicita.
Bon fiscal cu metode de plata care nu sunt configurate pe casa de marcat Au fost inregistrate urmatoarele plati partiale cu metode de plata neconfigurate pe casa de marcat: Card: 10, Numerar: 5 Verifica configurarile casei de marcat din contul SmartBill Cloud - fiecare metoda folosita in campurile `received*` trebuie sa fie configurata pe casa de marcat.
- -- ## Tipuri de incasare
1. Card Emite o incasare cu cardul. Nu necesita serie si nu genereaza document separat. ```json { "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" } ```
2. Chitanta Genereaza un document de chitanta cu numar din seria specificata. Necesita `seriesName` si `isCash: true`. ```json { "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 } ```
3. Chitanta ciorna (draft) Salveaza chitanta ca ciorna - fara numar atribuit pana la finalizare din interfata SmartBill Cloud. Functioneaza doar pentru tipul `Chitanta`. ```json { "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 } ```
4. Bon fiscal 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). ```json { "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`.
5. Ordin de plata Emite o incasare prin ordin de plata. Nu necesita serie si nu genereaza document separat. ```json { "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" } ```
6. Incasare legata de o factura Asociaza incasarea cu una sau mai multe facturi existente prin `invoicesList`. ```json { "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" }] } ```
7. Incasare cu preluare date din factura 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 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.`. ```json { "companyVatCode": "CIF_FIRMA", "issueDate": "2026-06-15", "type": "Ordin plata", "useInvoiceDetails": true, "invoicesList": [{ "seriesName": "SERIA_FACTURII", "number": "0025" }] } ```
## Request body - PaymentRequest - `companyVatCode` string, required — CIF-ul firmei tale, exact ca in SmartBill Cloud. - `type` 'Card' | 'Card online' | 'Chitanta' | 'Bon' | 'Ordin plata' | 'CEC' | 'Bilet ordin' | 'Mandat postal' | 'Extras de cont' | 'Ramburs' | 'Alta incasare', required — Tipul incasarii. Foloseste `Bon` pentru bon fiscal. Litera mare nu conteaza, dar spatiile in plus invalideaza valoarea. - `issueDate` string, date — Data incasarii, in format `YYYY-MM-DD`. - `isDraft` boolean — Creeaza chitanta ca ciorna, daca tipul incasarii permite acest lucru. - `seriesName` string — Seria chitantei, obligatorie pentru incasari de tip `Chitanta`. - `number` string — Numarul bonului fiscal. Daca lipseste, se aloca urmatorul numar disponibil de pe casa de marcat configurata. Se aplica doar incasarilor de tip `Bon`. - `returnFiscalPrinterText` boolean — Doar pentru `type: Bon`. Controleaza cum ajunge bonul la imprimanta fiscala. `true` returneaza continutul bonului in campul `message` al raspunsului, codificat Base64, pentru tiparire directa pe casa de marcat. `false` nu il returneaza, iar bonul se tipareste din contul SmartBill. Se ia in calcul casa de marcat configurata pentru utilizatorul care face apelul. - `observation` string — Alte observatii in legatura cu incasarea. - `useStock` boolean — Opereaza stocul pentru produsele de pe bon. - `client` Client - `name` string, required — Numele clientului, persoana juridica sau persoana fizica. - `vatCode` string — Codul fiscal al clientului. Poate fi CUI/CIF romanesc sau cod TVA extern. - `isTaxPayer` boolean — Indica daca clientul este platitor de TVA. Implicit `false`: un client trimis fara acest camp se salveaza ca neplatitor. - `regCom` string — Numarul de inregistrare la Registrul Comertului. - `address` string — Adresa clientului. - `city` string — Orasul clientului. Daca `county` este "Bucuresti", valoarea trebuie sa fie Sector 1 - Sector 6, altfel e-Factura nu se va valida in SPV. - `county` string — Judetul clientului sau regiunea/statul pentru clienti externi. - `country` string, required — Tara clientului. API-ul accepta text liber; recomandat este numele tarii sau codul uzual, de exemplu `Romania` sau `RO`. - `email` string, email — Adresa de email a clientului. - `phone` string — Numarul de telefon al clientului. - `contact` string — Persoana de contact - `iban` string — IBAN cont bancar - `bank` string — Numele bancii - `code` string — Codul intern al clientului in SmartBill - `saveToDb` boolean — Salveaza clientul in nomenclator daca e nou. Implicit `false`, deci clientul nu se salveaza daca nu ceri explicit - nici la descarcare de gestiune. - `products` Product[] — Liniile de produse sau servicii de pe bon. Se trimit la incasari de tip `Bon`. - `name` string, required — Numele produsului sau serviciului - `code` string — Codul produsului (SKU). **Obligatoriu daca firma ta are activata setarea "Foloseste cod produs"** in SmartBill Cloud, altfel optional. - `productDescription` string — Descriere suplimentara produs - `isService` boolean — Este serviciu (nu produs fizic) - `quantity` number, required — Cantitate. API-ul nu o valideaza: `0` si valorile negative sunt acceptate, iar documentul se emite fara eroare. Valideaza cantitatea in integrarea ta inainte de a trimite. - `measuringUnitName` string, required — Unitate de masura - `price` number, required — Pret unitar - `currency` 'RON' | 'EUR' | 'USD' | 'GBP' | 'CAD' | 'AUD' | 'CHF' | 'TRY' | 'CZK' | 'DKK' | 'HUF' | 'MDL' | 'SEK' | 'NOK' | 'JPY' | 'EGP' | 'PLN' | 'RUB' | 'AED' | 'BRL' | 'CNY' | 'HRK' | 'INR' | 'KRW' | 'MXN' | 'NZD' | 'RSD' | 'THB' | 'UAH' | 'XDR' | 'ZAR' — Moneda pretului - `exchangeRate` number — Curs valutar pentru acest produs - `isTaxIncluded` boolean — Pretul include TVA. Implicit `false`, deci preturile sunt considerate fara TVA. - `taxName` string — Numele cotei TVA - `taxPercentage` number, required — Cota TVA a liniei. SmartBill accepta cotele existente in cont, inclusiv cote personalizate. - `warehouseName` string — Numele gestiunii pentru descarcare stoc (case-sensitive!) - `isDiscount` boolean — Este linie de discount - `numberOfItems` integer — Numarul de linii **imediat anterioare** la care se aplica discountul. **Obligatoriu pe o linie de discount**: fara el discountul e ignorat in silentiu, apelul intoarce `200`, iar documentul se emite cu totalul neredus. - `discountType` 1 | 2 — Tipul discountului. `1` = valoric, cu valoarea in `discountValue`. `2` = procentual, cu procentul in `discountPercentage`. Implicit `2`: o linie de discount fara `discountType`, dar cu ambele valori trimise, aplica procentul. **Trimite doar `1` sau `2`.** O alta valoare nu e respinsa, dar produce un document gresit: discountul valoric se scade din total fara sa ajusteze TVA-ul, iar un discount procentual e ignorat complet. Pentru un produs de 100 lei cu TVA 21% si un discount de 10 lei, `discountType: 1` da 108.9, iar o valoare in afara enumerarii da 111. - `discountValue` number — Valoarea discountului, pentru discount valoric, cand `discountType` este `1`. **Trebuie sa fie negativa**, deci se trimite cu semnul minus: `-10` pentru un discount de 10 lei. O valoare pozitiva nu e respinsa, dar **creste** totalul in loc sa il scada - un produs de 100 lei cu `discountValue: 10` da 133.1, nu 108.9. - `discountPercentage` number — Procentul discountului. Se foloseste pentru discount procentual, cand `discountType` este `2`. Valoarea trebuie sa fie mai mare decat 0 si cel mult 100. - `translatedName` string — Numele produsului in limba documentului - `translatedMeasuringUnit` string — Unitatea de masura in limba documentului - `saveToDb` boolean — Salveaza produsul in nomenclator daca e nou. Cand produsul exista deja si e trimis cu `saveToDb: true`, datele lui din nomenclator se actualizeaza din cerere - inclusiv numele. La descarcare de gestiune (`useStock: true`) actualizarea se face oricum, chiar si cu `saveToDb: false`. - `useSBProductName` boolean — Controleaza ce nume apare pe factura cand produsul este identificat prin `code`, iar denumirea trimisa in `name` difera de cea din nomenclator. `true` = pe factura se foloseste numele produsului din SmartBill, iar numele din nomenclator NU se modifica. `false` sau absent = pe factura se foloseste numele trimis prin `name`, iar acesta suprascrie numele produsului in nomenclator (inclusiv cand `saveToDb` este `false`). Necesita setarea "Foloseste cod produs" activata pe firma. - `value` number — Suma incasata. - `currency` string — Moneda incasarii. Bonul fiscal poate fi emis doar in RON. - `exchangeRate` number — Cursul valutar folosit pentru incasare. - `precision` integer — Numarul de zecimale folosit pentru sume. Valorile suportate sunt `2`, `3` si `4`. O valoare mai mare se limiteaza automat la `4`, fara eroare. - `isCash` boolean — Marcheaza incasarea ca numerar. - `receivedCash` number — Valoarea achitata cu numerar. Modalitate de plata, folosita la incasari de tip `Bon`. - `receivedCard` number — Valoarea achitata cu card. - `receivedTicheteMasa` number — Valoarea achitata cu tichete de masa. - `receivedTicheteCadou` number — Valoarea achitata cu tichete cadou. - `receivedOrdinDePlata` number — Valoarea achitata cu ordin de plata. - `receivedCec` number — Valoarea achitata cu cec. - `receivedCredit` number — Valoarea achitata cu credit. - `receivedCupon` number — Valoarea achitata cu cupoane. - `receivedPuncteDeFidelitate` number — Valoarea achitata cu puncte de fidelitate. - `receivedBonuriValoareFixa` number — Valoarea achitata cu bonuri cu valoare fixa. - `receivedMonedaAlternativa` number — Valoarea achitata cu alta moneda. - `text` string — Descrierea incasarii. - `translatedText` string — Descrierea incasarii in limba documentului. - `language` string — Limba documentului. Valorile valide sunt limbile predefinite in SmartBill Cloud, plus cele definite in cont la `Configurare > Limbi`. O valoare necunoscuta nu e respinsa de server, dar documentul se emite in limba implicita. Pentru numele produsului si unitatea de masura in limba documentului, foloseste `translatedName` si `translatedMeasuringUnit` pe linia de produs. - `useInvoiceDetails` boolean — Preia clientul si suma din factura indicata. Un `value` trimis explicit are prioritate si permite incasarea partiala. - `invoicesList` union — Factura sau lista de facturi pentru care se inregistreaza incasarea. Lista poate contine mai multe facturi, iar un singur apel le acopera pe toate. - object[] - `seriesName` string — Seria facturii. - `number` string — Numarul facturii. - object - `seriesName` string — Seria facturii. - `number` string — Numarul facturii. ## Response `200` Incasare emisa. Campurile din raspuns depind de tipul incasarii: `Chitanta` intoarce `number` si `series`; `Bon` intoarce `id` si `number`, plus `message` cand `returnFiscalPrinterText` este `true`; celelalte tipuri nu genereaza document separat. - PaymentResponse - `errorText` string — Mesaj de eroare (gol la succes). - `id` string — Numar de identificare unic al bonului emis. Se returneaza doar pentru incasari de tip `Bon` si este valoarea care se trimite ca parametru `id` la `GET /payment/text`. - `message` string — Continutul bonului fiscal, codificat Base64. Se returneaza doar cand `returnFiscalPrinterText` este `true`. Dupa decodare, continutul trebuie scris intr-un fisier cu numele si extensia configurate pentru casa de marcat (implicit `bon.inp`). - `number` string — Numarul documentului emis. - `series` string — Seria documentului emis. ## Other responses - `400` — Campuri obligatorii lipsa (client, valoare, tip incasare) sau configurare lipsa a casei de marcat - `401` — Autentificare esuata - `500` — Eroare interna de server. Poate aparea cand numele campurilor sunt trimise cu casing gresit (ex. `Price` in loc de `price`). Raspunsul este `text/html`, nu JSON - nu poate fi parsat programatic. --- [API](https://skmtc.dev/smartbill/apis/smartbill-api.md) · [All operations](https://skmtc.dev/smartbill/apis/smartbill-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/smartbill/smartbill-api/revisions/29940a27d41c/schema)