Emiterea facturilor prin API

POST /invoices cu Idempotency-Key, TVA în procente, plus listare, storno și marcare ca plătită.

Prima factură în 6 pași

Trimite POST /v1/invoices cu un obiect buyer și cel puțin o linie în lines.
Adaugă antetul Idempotency-Key — este obligatoriu, o cheie per operațiune logică.
Trimite vat_rate ca procent (21) și unit_price ca preț NET pe unitate.
Răspunsul 201 conține id, number, series, totals net/vat/gross și metadata pe care ai trimis-o.
Descarcă documentul cu GET /v1/invoices/{id}/pdf sau XML-ul UBL cu GET /v1/invoices/{id}/xml.

Toate endpoint-urile

Metodă	Endpoint	Scope	Idempotency-Key	Cereri / minut
POST	/invoices Emite o factură sau o proformă	invoices:write	obligatoriu	30
GET	/invoices Listează facturile (paginare cu cursor)	invoices:read	—	120
POST	/invoices/preview-totals Calculează totalurile fără să creeze nimic	invoices:read	—	120
GET	/invoices/{invoice_id} Returnează o factură	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Descarcă PDF-ul facturii	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Emite o notă de credit care stornează această factură	invoices:write	obligatoriu	30
POST	/invoices/{invoice_id}/payments Marchează factura ca plătită	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Marchează factura ca neplătită	invoices:write	—	30

Ce este API-ul 4invoices

bash
curl -sS -X POST https://api.4invoices.net/v1/invoices \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-10457-invoice' \
  -d '{
    "buyer": {
      "name": "Exemplu Comert SRL",
      "tax_id": "RO12345678",
      "address": "Str. Fabricii 12",
      "city": "Cluj-Napoca",
      "county": "Cluj",
      "country": "RO",
      "email": "[email protected]"
    },
    "lines": [
      { "description": "Abonament SaaS, iulie", "quantity": 1, "unit_price": 400, "vat_rate": 21, "unit": "buc" },
      { "description": "Implementare", "quantity": 6, "unit_price": 250, "vat_rate": 21, "unit": "ora" }
    ],
    "currency": "RON",
    "document_kind": "factura",
    "due_date": "2026-08-15",
    "metadata": { "order_id": "10457" }
  }'

bash
# Paginare cu cursor: urmărește next_cursor până când has_more devine false.
curl -sS "https://api.4invoices.net/v1/invoices?limit=50&status=issued&issued_from=2026-07-01" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# → {"object":"list","data":[...],"has_more":true,"next_cursor":"inv_01J..."}

curl -sS "https://api.4invoices.net/v1/invoices?limit=50&cursor=inv_01J..." \
  -H "Authorization: Bearer $ACCESS_TOKEN"

bash
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/storno \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: storno-inv_01J7ABC-1'

# Nota de credit primește PROPRIUL număr fiscal; numărul originalului nu se refolosește niciodată.

bash
# Marchează ca plătită
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Anulează
curl -sS -X DELETE https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

https://api.4invoices.net/v1 · https://api.4invoices.net/v1/openapi.json

Erori

Status	Tip	Cod
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Greșeli frecvente

Listarea este cu cursor: urmărește next_cursor până când has_more devine false. Filtrele includ status, document_kind, buyer_tax_id, issued_from, issued_to și q.
Storno-ul se face cu POST /v1/invoices/{id}/storno și primește propriul număr fiscal — numărul original nu se refolosește niciodată.
O proformă (document_kind proforma) nu consumă un număr fiscal și nu se poate depune în SPV.
metadata este ecouată la citire: pune acolo id-ul comenzii tale și nu mai ții o tabelă de corespondență separată.
POST /v1/invoices/preview-totals face aceeași aritmetică fără efecte secundare — util pentru afișarea totalurilor în coșul tău.

Întrebări frecvente de la dezvoltatori

Câte linii pot pune pe o factură?

Între 1 și 400. description are maximum 1024 de caractere, iar quantity trebuie să fie strict pozitivă.

Ce se întâmplă dacă retrimit același request după un timeout?

Cu aceeași Idempotency-Key primești factura originală și antetul Idempotency-Replayed: true. Nu se emite un al doilea document.

Cum marchez o factură ca plătită?

POST /v1/invoices/{id}/payments o marchează plătită, iar DELETE pe același path anulează marcajul. Ambele cer scope invoices:write.

Vezi și