Per la Romania: preflight CIUS-RO, invio all'SPV, stato normalizzato, risposta firmata e inbox delle fatture ricevute.
← Torna alla documentazione API
La prima fattura in 6 passi
- Esegui POST /v1/invoices/{id}/efactura/validate. Il controllo preliminare CIUS-RO (Romania) non invia nulla ad ANAF e ti dice esattamente cosa verrebbe rifiutato.
- Deposita la fattura con POST /v1/invoices/{id}/efactura/submit, sempre con una Idempotency-Key. Ricevi un submission_id e uno status.
- Interroga GET /v1/efactura/submissions/{id} finché non raggiunge accepted o rejected.
- Forza una nuova interrogazione ad ANAF (Romania) con POST /v1/efactura/submissions/{id}/refresh: viene conteggiata nel limite di 10 al minuto.
- Scarica l’archivio con la risposta firmata di ANAF (Romania) tramite GET /v1/efactura/submissions/{id}/download.
Tutti gli endpoint
| Metodo | Endpoint | Scope | Idempotency-Key | Richieste / minuto |
|---|---|---|---|---|
| GET | /invoices/{invoice_id}/xml Scarica l'XML UBL / CIUS-RO (Romania) | invoices:read | — | 120 |
| POST | /invoices/{invoice_id}/efactura/validate Preflight CIUS-RO (Romania) — convalida senza inviare | efactura:read | — | 120 |
| POST | /invoices/{invoice_id}/efactura/submit Invia la fattura ad ANAF (SPV, Romania) | efactura:submit | obbligatorio | 10 |
| GET | /efactura/submissions Elenca gli invii ad ANAF (Romania) | efactura:read | — | 120 |
| GET | /efactura/submissions/{submission_id} Recupera un invio | efactura:read | — | 120 |
| POST | /efactura/submissions/{submission_id}/refresh Chiedi ad ANAF (Romania) lo stato attuale | efactura:read | — | 10 |
| GET | /efactura/submissions/{submission_id}/download Scarica l'archivio della risposta firmata | efactura:read | — | 120 |
| GET | /efactura/inbox Fatture passive ricevute tramite SPV (Romania) | efactura:read | — | 120 |
| GET | /efactura/inbox/{inbound_id} Recupera una fattura ricevuta | efactura:read | — | 120 |
| GET | /efactura/inbox/{inbound_id}/download Scarica l'archivio della fattura ricevuta | efactura:read | — | 120 |
| POST | /efactura/inbox/sync Scarica i nuovi messaggi SPV (ANAF, Romania) nella casella | efactura:read | — | 10 |
Cos'è l'API 4invoices
bash
# CIUS-RO preflight. Sends NOTHING to ANAF.
curl -sS -X POST "https://api.4invoices.net/v1/invoices/inv_01J7ABC/efactura/validate?include_xml=true" \
-H "Authorization: Bearer $ACCESS_TOKEN"
# → {"invoice_id":"inv_01J7ABC","valid":false,
# "errors":["buyer.county is required for RO buyers"],
# "xml_base64":"PD94bWwg..."}bash
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'
# → {"submission_id":"sub_01J7XYZ","status":"queued"}python
import time, requests
BASE = "https://api.4invoices.net/v1"
TERMINAL = {"accepted", "rejected"}
H = {"Authorization": f"Bearer {token}"}
def wait_for_anaf(submission_id, timeout=900):
deadline = time.time() + timeout
delay = 15
while time.time() < deadline:
r = requests.get(f"{BASE}/efactura/submissions/{submission_id}", headers=H, timeout=30)
r.raise_for_status()
status = r.json()["status"]
if status in TERMINAL:
return r.json()
# /refresh asks ANAF directly and shares the 10/min submit bucket.
requests.post(f"{BASE}/efactura/submissions/{submission_id}/refresh", headers=H, timeout=30)
time.sleep(delay)
delay = min(delay * 2, 120)
raise TimeoutError(submission_id)bash
# Pull new SPV messages, then read the inbound supplier invoices.
curl -sS -X POST https://api.4invoices.net/v1/efactura/inbox/sync \
-H "Authorization: Bearer $ACCESS_TOKEN"
curl -sS "https://api.4invoices.net/v1/efactura/inbox?limit=50" \
-H "Authorization: Bearer $ACCESS_TOKEN"
# ANAF allows roughly ONE message-list call per minute per CIF,
# quindi /inbox/sync conta nel bucket di invio da 10/min. Schedulalo con cron, non fare polling.https://api.4invoices.net/v1 · https://api.4invoices.net/v1/openapi.json
Il percorso ANAF e-Factura (Romania)
Errori
| Stato | Tipo | Codice |
|---|---|---|
| 422 | invalid_request_error | cius_ro_incomplete |
Errori frequenti
- Ciclo di vita normalizzato: not_sent → validating → queued → sent → processing → accepted | rejected | error.
- accepted significa trasmessa a norma di legge. rejected significa che il sistema nazionale di fatturazione elettronica (in Romania: ANAF) l’ha rifiutata: correggi e invia di nuovo. error è un errore di trasporto dal nostro lato e si può ritentare senza rischi.
- L’invio è irreversibile: una seconda copia della stessa fattura non può essere ritirata dal sistema nazionale di fatturazione elettronica. Per questo la Idempotency-Key è obbligatoria.
- GET /v1/invoices/{id}/xml ti fornisce l’XML UBL / CIUS-RO (il profilo rumeno) senza alcun invio: per il tuo archivio o per un audit.
- Casella in entrata: POST /v1/efactura/inbox/sync recupera i nuovi messaggi, GET /v1/efactura/inbox li elenca e /download scarica l’archivio di ogni fattura ricevuta.
- Gli endpoint e-Factura funzionano solo per i tenant rumeni; altrimenti ricevi un 404.
Domande e risposte per sviluppatori
Quanto tempo impiega ANAF (Romania) ad accettare una fattura?
Dipende: da pochi secondi a diverse ore. Non bloccare la vendita: invia in modo asincrono e gestisci accepted e rejected come eventi.
Posso ottenere l’XML CIUS-RO (Romania) senza inviare nulla ad ANAF?
Sì. GET /v1/invoices/{id}/xml genera il documento senza alcun invio, e /efactura/validate con include_xml=true lo restituisce codificato in base64.
Con quale frequenza posso eseguire inbox/sync?
Al massimo 10 chiamate al minuto, ma in pratica, in Romania, ANAF consente circa una chiamata all’elenco messaggi al minuto per CIF. Eseguilo da un cron, ogni pochi minuti.
Cosa faccio se lo stato resta su error?
error è un errore di trasporto o di autenticazione dal nostro lato, quindi ritentare è sicuro. Se persiste, invia il request_id all’assistenza.