Emettere fatture tramite API

POST /invoices con Idempotency-Key, IVA in percentuale, più elenco, storno e segna come pagata.

La prima fattura in 6 passi

Invia POST /v1/invoices con un oggetto buyer e almeno una voce in lines.
Aggiungi l’header Idempotency-Key: è obbligatorio, una chiave per operazione logica.
Invia vat_rate come percentuale (21) e unit_price come prezzo unitario NETTO.
La risposta 201 contiene id, number, series, i totali net/vat/gross e i metadata che hai inviato.
Scarica il documento con GET /v1/invoices/{id}/pdf oppure l’XML UBL con GET /v1/invoices/{id}/xml.

Tutti gli endpoint

Metodo	Endpoint	Scope	Idempotency-Key	Richieste / minuto
POST	/invoices Emetti una fattura o una proforma	invoices:write	obbligatorio	30
GET	/invoices Elenca le fatture (paginazione a cursore)	invoices:read	—	120
POST	/invoices/preview-totals Calcola i totali senza creare nulla	invoices:read	—	120
GET	/invoices/{invoice_id} Recupera una fattura	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Scarica il PDF della fattura	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Emetti una nota di credito che storna questa fattura	invoices:write	obbligatorio	30
POST	/invoices/{invoice_id}/payments Segna la fattura come pagata	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Segna la fattura come non pagata	invoices:write	—	30

Cos'è l'API 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
# Paginazione a cursore: segui next_cursor finché has_more è 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'

# La nota di credito riceve un numero fiscale PROPRIO; il numero dell'originale non viene mai riutilizzato.

bash
# Segna come pagata
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Annulla
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

Errori

Stato	Tipo	Codice
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Errori frequenti

L’elenco è paginato tramite cursore: segui next_cursor finché has_more non vale false. I filtri comprendono status, document_kind, buyer_tax_id, issued_from, issued_to e q.
Uno storno si crea con POST /v1/invoices/{id}/storno e riceve un proprio numero fiscale: il numero originale non viene mai riutilizzato.
Una proforma (document_kind proforma) non consuma alcun numero fiscale e non può essere depositata nel sistema nazionale di fatturazione elettronica.
metadata viene restituito nelle letture: inserisci lì l’id del tuo ordine e non ti servirà più una tabella di corrispondenza separata.
POST /v1/invoices/preview-totals esegue lo stesso calcolo senza effetti collaterali: comodo per mostrare i totali nel tuo carrello.

Domande e risposte per sviluppatori

Quante righe può avere una fattura?

Da 1 a 400. description è limitato a 1024 caratteri e quantity deve essere strettamente positivo.

Cosa succede se reinvio la stessa richiesta dopo un timeout?

Con la stessa Idempotency-Key ottieni la fattura originale più un header Idempotency-Replayed: true. Non viene emesso alcun secondo documento.

Come segno una fattura come pagata?

POST /v1/invoices/{id}/payments la segna come pagata e DELETE sullo stesso percorso annulla l’operazione. Entrambe richiedono lo scope invoices:write.

Vedi anche