Emissió de factures per l'API

POST /invoices amb Idempotency-Key, IVA com a percentatges, més el llistat, el storno i el marcatge com a pagada.

La teva primera factura en 6 passos

Envia POST /v1/invoices amb un objecte buyer i almenys una entrada a lines.
Afegeix la capçalera Idempotency-Key — és obligatòria, una clau per cada operació lògica.
Envia vat_rate com a percentatge (21) i unit_price com a preu unitari NET.
La resposta 201 porta id, number, series, els totals net/vat/gross i les metadades que has enviat.
Descarrega el document amb GET /v1/invoices/{id}/pdf o el XML UBL amb GET /v1/invoices/{id}/xml.

Tots els punts finals

Mètode	Punt final	Àmbit	Idempotency-Key	Peticions / minut
POST	/invoices Emet una factura o una proforma	invoices:write	obligatori	30
GET	/invoices Llista les factures (paginació per cursor)	invoices:read	—	120
POST	/invoices/preview-totals Calcula els totals sense crear res	invoices:read	—	120
GET	/invoices/{invoice_id} Recupera una factura	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Descarrega el PDF de la factura	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Emet una nota de crèdit que anul·la aquesta factura	invoices:write	obligatori	30
POST	/invoices/{invoice_id}/payments Marca la factura com a pagada	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Marca la factura com a no pagada	invoices:write	—	30

Què és l'API de 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
# Paginació per cursor: segueix next_cursor fins que has_more sigui 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'

# El storno rep el seu PROPI número fiscal; el número original mai no es reutilitza.

bash
# Marca com a pagada
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Desfés
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

Errors

Estat	Tipus	Codi
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Errors habituals

El llistat és per cursor: segueix next_cursor fins que has_more sigui false. Els filtres inclouen status, document_kind, buyer_tax_id, issued_from, issued_to i q.
Un storno és POST /v1/invoices/{id}/storno i rep el seu propi número fiscal — el número original mai no es reutilitza.
Una proforma (document_kind proforma) no consumeix cap número fiscal i no es pot presentar al sistema nacional de facturació electrònica.
metadata es retorna a les lectures: posa-hi l'id de la teva comanda i ja no necessites una taula de mapeig separada.
POST /v1/invoices/preview-totals fa la mateixa aritmètica sense efectes secundaris — pràctic per mostrar els totals al teu propi carro.

Preguntes i respostes per a desenvolupadors

Quantes línies pot tenir una factura?

Entre 1 i 400. description té un límit de 1024 caràcters, i quantity ha de ser estrictament positiva.

Què passa si torno a enviar la mateixa petició després d'un timeout?

Amb la mateixa Idempotency-Key obtens la factura original més una capçalera Idempotency-Replayed: true. No s'emet cap segon document.

Com marco una factura com a pagada?

POST /v1/invoices/{id}/payments la marca com a pagada i DELETE al mateix camí la desfà. Totes dues necessiten l'àmbit invoices:write.

Vegeu també