Facturi, proforme și stornări

Creare și emitere

POST /companies/{company_id}/documents face o ciornă. Cu "issue": true o și emite (îi dă numărul următor din serie), iar cu "submit": true o și trimite în RO e-Factura, toate în aceeași cerere:

{
  "client_id": 55,
  "lines": [
    { "product_id": 31, "quantity": 2 },
    { "name": "Transport", "quantity": 1, "unit_price": 40, "vat_percent": 21 }
  ],
  "due_date": "2026-10-30",
  "order_ref": "PO-7781",
  "issue": true,
  "submit": true
}

• Dacă emiterea nu reușește (lipsește județul clientului, seria e dezactivată), cererea întoarce eroarea și nu lasă nicio ciornă în urmă.
• Dacă emiterea reușește, dar ANAF nu primește factura chiar atunci, factura rămâne emisă și programată pentru trimitere; reîncercăm noi.
• Fără issue, documentul rămâne ciornă: îl vezi în aplicație și îl emiți mai târziu, din aplicație sau cu /issue.

Data emiterii este implicit ziua de azi în România, scadența vine din setările firmei, iar totalurile, TVA-ul și cursul valutar le calculăm noi.

Clientul

Dai fie client_id, un client din agendă, fie client, scris direct pe document. Cu "save_client": true, clientul scris direct intră și în agendă (dacă există deja cu același CUI, CNP sau ref, se folosește acela).

• Pentru RO e-Factura, o firmă din România are nevoie de CUI, localitate și județ. În București, localitatea este sectorul: "city": "Sector 3", "county": "București".
• O persoană fizică: "kind": "pf", cu sau fără CNP. Fără CNP, sau cu "send_cnp": false, în e-Factura pleacă 13 zerouri, cum cere ANAF.
• O firmă din alt stat: "country": "DE" și codul ei de TVA în cui.

Liniile și TVA-ul

• quantity și unit_price (în moneda documentului); cu "price_includes_vat": true, prețul conține TVA. discount_percent reduce linia.
• TVA-ul: vat_rate_id (o cotă a firmei, din GET /companies/{company_id}), sau vat_percent cu vat_category, sau nimic, pentru cota implicită a firmei. La o firmă neplătitoare de TVA nu se aplică TVA.
• Unitatea este un cod UN/ECE: H87 bucată (implicit), HUR oră, KGM kilogram, MTR metru, C62 unitate.
• Cu product_id, linia ia din catalog denumirea, prețul, unitatea și cota; ce trimiți în plus are prioritate.

Valuta

Cu "currency": "EUR" și fără exchange_rate, punem cursul BNR pentru data emiterii (ultimul comunicat înaintea ei) și îl arătăm în exchange_rate și exchange_rate_date. Dacă dai tu cursul, rămâne cel dat. Un produs cu prețul în euro pe o factură în lei se convertește la același curs (src_price, src_currency).

Încasată la emitere

Cu "collected": true și payment_method, factura iese încasată integral, cu încasarea înregistrată la emitere. Cu "payment_method": "numerar" se emite și chitanța. "payment_method": "bon_fiscal" face factura de tip 751 (emisă pe baza unui bon fiscal).

Numerotarea

La emitere, numărul este următorul din seria principală a firmei. Altă serie: series_id (seriile sunt în GET /companies/{company_id}); alt număr: number. Un număr deja folosit în serie primește 409 conflict.

Modificare și ștergere

PATCH schimbă doar câmpurile trimise; lines, dacă îl trimiți, înlocuiește toate liniile. Se poate modifica o ciornă și o factură emisă care nu a ajuns la ANAF (de exemplu una respinsă). După ce ANAF a primit-o, factura nu se mai modifică și nu se mai șterge: se stornează. Ștergerea (DELETE) merge pentru ciorne și pentru documentele emise netrimise, fără chitanțe și fără stornări; ea rămâne în jurnalul firmei.

Stornarea

POST …/storno emite factura de stornare: cantități negative, cu trimitere la factura inițială, totală sau doar pe unele linii ({"line_id", "quantity"}, cu id-urile liniilor din document). O factură trimisă în RO e-Factura se stornează după ce ANAF a validat-o. Stornarea se trimite apoi ca orice factură.

Proforme

"type": "proforma" face o proformă, cu seria ei. O proformă nu ajunge în RO e-Factura și nu se stornează. Când clientul plătește, POST …/convert face din ea o ciornă de factură cu aceleași linii, pe care o emiți cu /issue.

PDF și email

GET …/pdf dă PDF-ul, cu sigla firmei și contul bancar. POST …/email îl trimite clientului (sau adreselor din to), de la adresa Chappa, cu suma, scadența și IBAN-ul în mesaj; merge pentru firmele verificate, conectate la ANAF.

Găsirea documentelor

GET …/documents are filtre pentru tip, stare, starea în e-Factura, plată, perioadă și client. Cel mai sigur mod de a regăsi o factură a ta este external_ref: pune la creare id-ul comenzii și caută după el cu ?external_ref=comanda-1042. Lista cuprinde și facturile trimise din alte programe prin SPV ("source": "spv"); pe acestea doar le citești.

Referința

{
  "object": "list",
  "data": [
    { "id": 812, "object": "document", "type": "invoice", "status": "issued", "number": "FCT 42",
      "issue_date": "2026-10-09", "currency": "RON", "client": { "kind": "pj", "name": "Beta Construct SRL", "cui": "RO18547290", "country": "RO" },
      "totals": { "net": 610, "vat": 128.1, "total": 738.1 },
      "efactura": { "applies": true, "status": "accepted", "upload_index": "5012345678", "errors": null, "scheduled_at": null, "anaf_id": null },
      "payment": { "status": "unpaid", "paid": 0, "outstanding": 738.1, "overdue": false }, "…": "…" }
  ],
  "has_more": true,
  "next_cursor": 812
}

{
  "type": "invoice",
  "client": {
    "name": "Beta Construct SRL",
    "cui": "RO18547290",
    "address": "Str. Fabricii 12",
    "city": "Sector 3",
    "county": "București",
    "email": "contabilitate@beta.ro"
  },
  "save_client": true,
  "lines": [
    { "name": "Abonament lunar", "unit": "H87", "quantity": 1, "unit_price": 250, "vat_percent": 21 },
    { "name": "Ore suport", "unit": "HUR", "quantity": 3, "unit_price": 120, "vat_percent": 21 }
  ],
  "payment_method": "ordin_plata",
  "external_ref": "comanda-1042",
  "issue": true,
  "submit": true
}

{
  "id": 812,
  "object": "document",
  "company_id": 7,
  "type": "invoice",
  "status": "issued",
  "source": "chappa",
  "number": "FCT 42",
  "series": "FCT",
  "sequence": 42,
  "issue_date": "2026-10-09",
  "due_date": "2026-10-23",
  "currency": "RON",
  "exchange_rate": null,
  "exchange_rate_date": null,
  "client_id": 55,
  "client": {
    "kind": "pj", "name": "Beta Construct SRL", "cui": "RO18547290", "cnp": null, "send_cnp": false,
    "reg_com": null, "address": "Str. Fabricii 12", "city": "Sector 3", "county": "București",
    "country": "RO", "email": "contabilitate@beta.ro", "phone": null
  },
  "lines": [
    { "id": 3301, "position": 1, "product_id": null, "code": null, "name": "Abonament lunar", "description": null,
      "unit": "H87", "quantity": 1, "unit_price": 250, "price_includes_vat": false, "discount_percent": 0,
      "vat_rate_id": 14, "vat_percent": 21, "vat_category": "S", "exemption_code": null, "exemption_text": null,
      "net": 250, "vat": 52.5, "gross": 302.5, "storno_of_line_id": null, "src_price": null, "src_currency": null },
    { "id": 3302, "position": 2, "product_id": null, "code": null, "name": "Ore suport", "description": null,
      "unit": "HUR", "quantity": 3, "unit_price": 120, "price_includes_vat": false, "discount_percent": 0,
      "vat_rate_id": 14, "vat_percent": 21, "vat_category": "S", "exemption_code": null, "exemption_text": null,
      "net": 360, "vat": 75.6, "gross": 435.6, "storno_of_line_id": null, "src_price": null, "src_currency": null }
  ],
  "totals": { "net": 610, "vat": 128.1, "total": 738.1 },
  "notes": null,
  "internal_note": null,
  "order_ref": null,
  "contract_ref": null,
  "external_ref": "comanda-1042",
  "payment_method": "ordin_plata",
  "bank_account_id": 3,
  "vat_on_collection": false,
  "storno_of": null,
  "stornos": [],
  "converted_from_id": null,
  "converted_to_id": null,
  "efactura": {
    "applies": true,
    "status": "processing",
    "upload_index": "5012345678",
    "errors": null,
    "scheduled_at": null,
    "deadline": "2026-10-16",
    "anaf_id": null,
    "history": [{ "status": "processing", "upload_index": "5012345678", "errors": null, "at": "2026-10-09 14:02" }]
  },
  "payment": { "status": "unpaid", "paid": 0, "outstanding": 738.1, "overdue": false, "collected_at_issue": false },
  "payments": [],
  "created_at": "2026-10-09T14:02:11+03:00",
  "issued_at": "2026-10-09T14:02:11+03:00"
}

{ "due_date": "2026-10-30", "notes": "Plata în două tranșe." }

{ "series_id": 2 }

{ "lines": [{ "line_id": 3302, "quantity": 1 }], "reason": "O oră facturată în plus" }

{ "to": "contabilitate@beta.ro", "message": "Vă mulțumim pentru comandă." }

Obiectul DocumentInput

Ce trimiți la creare și la modificare. La modificare, câmpurile lipsă rămân cum erau; lines trimis înlocuiește toate liniile.

Obiectul DocumentCreate

DocumentInput, plus ce poate face aceeași cerere:

Obiectul LineInput

O linie, cum o trimiți.

Obiectul Document

O factură, o proformă sau o stornare.

Obiectul Line

O linie, cum o citești: câmpurile din LineInput, plus:

Obiectul ClientSnapshot

Clientul cum a rămas pe document.

Obiectul IssueInput

Emiterea unei ciorne. Toate opționale.

Obiectul StornoInput

O stornare (factură cu cantități negative care face trimitere la cea inițială).

Obiectul EmailInput

Trimiterea PDF-ului pe email, de la adresa Chappa, în numele firmei. Doar pentru o firmă verificată, conectată la ANAF.

Obiectul Email

Emailul trimis.