Riigi e-arvete süsteem API kaudu

Eelkontroll (Rumeenias CIUS-RO), esitamine süsteemi, normaliseeritud staatus, allkirjastatud vastus ja sissetulev tarnijate kast.

← Tagasi API dokumentatsiooni juurde

Esimene arve 6 sammuga

Käivita POST /v1/invoices/{id}/efactura/validate. Eelkontroll (Rumeenias CIUS-RO) ei saada riigi e-arvete süsteemile midagi ja ütleb täpselt, mis tagasi lükataks.
Esita POST /v1/invoices/{id}/efactura/submit alati koos Idempotency-Key'ga. Saad submission_id ja staatuse.
Päri GET /v1/efactura/submissions/{id} seni, kuni staatus on accepted või rejected.
Sunni värske päring riigi e-arvete süsteemist POST /v1/efactura/submissions/{id}/refresh abil — see kulutab 10 minutis grupi.
Laadi riigi e-arvete süsteemi allkirjastatud vastuse arhiiv GET /v1/efactura/submissions/{id}/download abil.

Kõik lõpp-punktid

Meetod	Lõpp-punkt	Scope	Idempotency-Key	Päringuid / minut
GET	/invoices/{invoice_id}/xml Laadi alla UBL XML (Rumeenias CIUS-RO)	invoices:read	—	120
POST	/invoices/{invoice_id}/efactura/validate Eelkontroll (Rumeenias CIUS-RO) — valideeri saatmata	efactura:read	—	120
POST	/invoices/{invoice_id}/efactura/submit Esita arve riigi e-arvete süsteemi	efactura:submit	kohustuslik	10
GET	/efactura/submissions Loetle e-arvete süsteemi esitused	efactura:read	—	120
GET	/efactura/submissions/{submission_id} Too üks esitus	efactura:read	—	120
POST	/efactura/submissions/{submission_id}/refresh Küsi riigi e-arvete süsteemilt praegune olek	efactura:read	—	10
GET	/efactura/submissions/{submission_id}/download Laadi alla allkirjastatud vastuste arhiiv	efactura:read	—	120
GET	/efactura/inbox Riigi e-arvete süsteemi kaudu saadud tarnijaarved	efactura:read	—	120
GET	/efactura/inbox/{inbound_id} Too üks sissetulev arve	efactura:read	—	120
GET	/efactura/inbox/{inbound_id}/download Laadi alla sissetuleva arve arhiiv	efactura:read	—	120
POST	/efactura/inbox/sync Too riigi e-arvete süsteemi uued sõnumid sissetulevasse kasti	efactura:read	—	10

Mis on 4invoices API

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,
# seega /inbox/sync arvestatakse 10/min esitusgrupi alla. Käivita see cron'iga, ära küsitle pidevalt.

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

Riigi e-arvete süsteem

Vead

Staatus	Tüüp	Kood
422	invalid_request_error	cius_ro_incomplete

Levinud vead

Normaliseeritud elutsükkel: not_sent → validating → queued → sent → processing → accepted | rejected | error.
accepted tähendab seaduslikult edastatud. rejected tähendab, et riigi e-arvete süsteem keeldus: paranda ja esita uuesti. error on meie poolne edastusviga ja selle võib turvaliselt uuesti proovida.
Esitamine on pöördumatu: sama arve teist koopiat ei saa riigi e-arvete süsteemist tagasi võtta. Seetõttu on Idempotency-Key kohustuslik.
GET /v1/invoices/{id}/xml annab UBL XML-i (Rumeenias CIUS-RO) ilma esitamata — oma arhiivi või auditi jaoks.
Sissetulev kast: POST /v1/efactura/inbox/sync toob uued sõnumid, GET /v1/efactura/inbox loetleb need ja /download laadib iga sissetuleva arve arhiivi.
e-Factura lõpp-punktid töötavad ainult Rumeenia tenant'idele; muidu saad 404.

Arendajate küsimused ja vastused

Kui kaua kulub riigi e-arvete süsteemil arve vastuvõtmiseks?

See varieerub sekunditest tundideni. Ära blokeeri müüki: esita asünkroonselt ja käsitle accepted ning rejected sündmustena.

Kas ma saan XML-i (Rumeenias CIUS-RO) riigi e-arvete süsteemile midagi saatmata?

Jah. GET /v1/invoices/{id}/xml genereerib dokumendi ilma esitamata ja /efactura/validate tagastab selle base64-kodeerituna, kui include_xml=true.

Kui sageli ma saan inbox/sync käivitada?

Kuni 10 kutsu minutis, aga praktikas lubab Rumeenia ANAF umbes ühe sõnumiloendi päringu minutis maksukohustuslase numbri (CIF) kohta. Käivita see cron'ist paari minuti tagant.

Mida teha, kui staatus jääb error-iks?

error on meie poolne edastus- või autentimisviga, seega seda võib turvaliselt uuesti proovida. Kui see püsib, saada request_id toele.

Vaata ka