Nacionalni sistem e-računov prek API

Predpregled (v Romuniji CIUS-RO), oddaja v nacionalni sistem (v Romuniji SPV), normalizirano stanje, podpisan odgovor in prejeti računi dobaviteljev.

← Nazaj na dokumentacijo API

Prvi račun v 6 korakih

Zaženite POST /v1/invoices/{id}/efactura/validate. Predpregled (v Romuniji CIUS-RO) nacionalnemu sistemu e-računov ne pošlje ničesar in vam natančno pove, kaj bi bilo zavrnjeno.
Račun oddajte s POST /v1/invoices/{id}/efactura/submit, vedno z Idempotency-Key. Dobite submission_id in status.
GET /v1/efactura/submissions/{id} kličite, dokler stanje ne doseže accepted ali rejected.
Novo poizvedbo pri nacionalnem sistemu e-računov vsilite s POST /v1/efactura/submissions/{id}/refresh — šteje v kvoto 10 na minuto.
Arhiv s podpisanim odgovorom nacionalnega sistema (v Romuniji ANAF) prenesite prek GET /v1/efactura/submissions/{id}/download.

Vse končne točke

Metoda	Končna točka	Scope	Idempotency-Key	Zahtev / minuto
GET	/invoices/{invoice_id}/xml Prenesi XML UBL (v Romuniji CIUS-RO)	invoices:read	—	120
POST	/invoices/{invoice_id}/efactura/validate Predpregled (v Romuniji CIUS-RO) — preveri brez pošiljanja	efactura:read	—	120
POST	/invoices/{invoice_id}/efactura/submit Pošlji račun v nacionalni sistem e-računov (v Romuniji ANAF/SPV)	efactura:submit	obvezno	10
GET	/efactura/submissions Seznam oddaj v nacionalni sistem e-računov	efactura:read	—	120
GET	/efactura/submissions/{submission_id} Pridobi eno oddajo	efactura:read	—	120
POST	/efactura/submissions/{submission_id}/refresh Vprašaj nacionalni sistem e-računov o trenutnem stanju	efactura:read	—	10
GET	/efactura/submissions/{submission_id}/download Prenesi arhiv podpisanega odgovora	efactura:read	—	120
GET	/efactura/inbox Dobaviteljski računi, prejeti prek nacionalnega sistema e-računov	efactura:read	—	120
GET	/efactura/inbox/{inbound_id} Pridobi en prejet račun	efactura:read	—	120
GET	/efactura/inbox/{inbound_id}/download Prenesi arhiv prejetega računa	efactura:read	—	120
POST	/efactura/inbox/sync Prenesi nova sporočila nacionalnega sistema e-računov v predal	efactura:read	—	10

Kaj je 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,
# zato se /inbox/sync šteje v kvoto pošiljanja 10/min. Zaženite ga prek crona, ne anketirajte.

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

Pot do nacionalnega sistema e-računov

Napake

Stanje	Tip	Koda
422	invalid_request_error	cius_ro_incomplete

Pogoste napake

Normaliziran življenjski cikel: not_sent → validating → queued → sent → processing → accepted | rejected | error.
accepted pomeni pravno veljaven prenos. rejected pomeni, da ga je nacionalni sistem e-računov zavrnil: popravite ga in oddajte znova. error je napaka prenosa na naši strani in ponovni poskus je varen.
Oddaja je nepovratna: druge kopije istega računa ni mogoče umakniti iz nacionalnega sistema e-računov. Zato je Idempotency-Key obvezen.
GET /v1/invoices/{id}/xml vam da XML UBL (v Romuniji CIUS-RO) povsem brez oddaje — za lasten arhiv ali revizijo.
Nabiralnik: POST /v1/efactura/inbox/sync prevzame nova sporočila, GET /v1/efactura/inbox jih izpiše, /download pa prenese arhiv vsakega prejetega računa.
Končne točke za e-Factura delujejo samo za romunske najemnike; sicer dobite 404.

Vprašanja in odgovori za razvijalce

Koliko časa nacionalni sistem e-računov potrebuje, da sprejme račun?

Različno, od nekaj sekund do nekaj ur. Ne blokirajte prodaje: oddajajte asinhrono ter accepted in rejected obravnavajte kot dogodka.

Ali lahko dobim XML (v Romuniji CIUS-RO), ne da bi nacionalnemu sistemu e-računov karkoli poslal?

Da. GET /v1/invoices/{id}/xml ustvari dokument brez oddaje, /efactura/validate z include_xml=true pa ga vrne kodiranega v base64.

Kako pogosto lahko zaganjam inbox/sync?

Največ 10 klicev na minuto, v praksi pa v Romuniji ANAF dovoli približno en klic za seznam sporočil na minuto na CIF. Zaganjajte ga s cronom, vsakih nekaj minut.

Kaj naj storim, če stanje ostane error?

error je napaka prenosa ali avtentikacije na naši strani, zato je ponovni poskus varen. Če se ponavlja, pošljite request_id podpori.

Glejte tudi