Documentazione

La documentazione 4invoices ha due livelli: il pannello, che usi senza scrivere codice, e l'API pubblica, con cui il tuo sistema emette fatture e porta il documento attraverso il circuito nazionale della fatturazione elettronica (in Romania, e-Factura dell'ANAF). Questa pagina è il punto d'ingresso al secondo livello.

Apri la documentazione completa dell'API →

Cosa puoi automatizzare

L'API pubblica copre l'emissione di fatture e proforma, gli storni, i clienti con verifica nel registro delle imprese (in Romania, registro ANAF), le serie di numerazione e tutto il percorso nazionale di fatturazione elettronica (in Romania, e-Factura): preflight CIUS-RO, invio all'SPV, monitoraggio dello stato, risposta firmata e inbox delle fatture ricevute dai fornitori.

https://api.4invoices.net/v1 · 25 endpoints · Specifica OpenAPI (senza chiave)

invoices:read · invoices:write · clients:read · clients:write · efactura:read · efactura:submit

Autenticazione

Prima della prima chiamataFatturazione → Impostazioni → Accesso API
bash
curl -sS -X POST https://api.4invoices.net/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "cli_XXXXXXXXXXXX",
    "client_secret": "sec_XXXXXXXXXXXXXXXXXXXX"
  }'

# → {"access_token":"eyJ...","token_type":"Bearer","expires_in":3600,
#    "scope":"invoices:read invoices:write efactura:submit"}
Solo server-to-server. Non chiamare l'API da JavaScript di browser: il client_secret arriverebbe al visitatore e CORS blocca comunque ogni origin.

La prima fattura in 6 passi

  1. Genera una credenziale nel pannello, in Fatturazione → Impostazioni → Accesso API, e copia il client_secret — viene mostrato una sola volta.
  2. Completa il profilo aziendale e attiva almeno una serie di tipo fiscale, altrimenti l'emissione restituisce issuer_profile_incomplete o no_series_configured.
  3. Scambia la credenziale con un token: POST /v1/auth/token con grant_type client_credentials. Il token dura un'ora — mettilo in cache, non richiederne uno per ogni chiamata.
  4. Emetti la fattura: POST /v1/invoices con header Idempotency-Key e vat_rate in percentuale (21, non 0.21).
  5. Per il mercato rumeno, esegui il preflight CIUS-RO con POST /v1/invoices/{id}/efactura/validate, poi invia all'ANAF con POST /v1/invoices/{id}/efactura/submit.
  6. Segui lo stato con GET /v1/efactura/submissions/{id} finché non arriva ad accepted o rejected.
bash
# 1 — token (1 ora, da mettere in cache)
ACCESS_TOKEN=$(curl -sS -X POST https://api.4invoices.net/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"client_credentials","client_id":"cli_XXX","client_secret":"sec_XXX"}' \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["access_token"])')

# 2 — emetti la fattura (Idempotency-Key è OBBLIGATORIO)
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","county":"Cluj","city":"Cluj-Napoca","country":"RO"},
       "lines":[{"description":"Abonament SaaS","quantity":1,"unit_price":400,"vat_rate":21}]}'

# 3 — preflight CIUS-RO, then send to ANAF
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/efactura/validate \
  -H "Authorization: Bearer $ACCESS_TOKEN"

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

Guide per argomento

Ogni argomento ha la sua pagina, con endpoint, esempi ed errori specifici.

Apri la documentazione completa dell'API →