E-faturimi kombëtar përmes API

Verifikimi paraprak (CIUS-RO për Rumaninë), paraqitja në sistemin kombëtar, statusi i normalizuar, përgjigja e nënshkruar dhe kutia hyrëse e furnitorëve.

← Kthehu te dokumentacioni i API-t

Fatura jote e parë në 6 hapa

Ekzekuto POST /v1/invoices/{id}/efactura/validate. Verifikimi paraprak (CIUS-RO për Rumaninë) s'dërgon asgjë në sistemin kombëtar dhe të tregon saktësisht çfarë do të refuzohej.
Paraqite me POST /v1/invoices/{id}/efactura/submit, gjithmonë me një Idempotency-Key. Merr një submission_id dhe një status.
Pyet GET /v1/efactura/submissions/{id} derisa të arrijë accepted ose rejected.
Detyro një kërkesë të re te sistemi kombëtar i e-faturimit me POST /v1/efactura/submissions/{id}/refresh — numëron në grupin 10 për minutë.
Shkarko arkivin e përgjigjes së nënshkruar të sistemit kombëtar me GET /v1/efactura/submissions/{id}/download.

Çdo pikë fundore

Metoda	Pika fundore	Fushëveprimi	Idempotency-Key	Kërkesa / minutë
GET	/invoices/{invoice_id}/xml Shkarkon XML-in UBL (CIUS-RO për Rumaninë)	invoices:read	—	120
POST	/invoices/{invoice_id}/efactura/validate Verifikim paraprak — validon pa dërguar	efactura:read	—	120
POST	/invoices/{invoice_id}/efactura/submit Paraqet faturën në sistemin kombëtar të e-faturimit	efactura:submit	e detyrueshme	10
GET	/efactura/submissions Liston paraqitjet në sistemin kombëtar	efactura:read	—	120
GET	/efactura/submissions/{submission_id} Merr një paraqitje	efactura:read	—	120
POST	/efactura/submissions/{submission_id}/refresh Kërkon gjendjen aktuale nga sistemi kombëtar	efactura:read	—	10
GET	/efactura/submissions/{submission_id}/download Shkarkon arkivin e përgjigjes së nënshkruar	efactura:read	—	120
GET	/efactura/inbox Faturat e furnitorëve të marra përmes sistemit kombëtar	efactura:read	—	120
GET	/efactura/inbox/{inbound_id} Merr një faturë hyrëse	efactura:read	—	120
GET	/efactura/inbox/{inbound_id}/download Shkarkon arkivin e faturës hyrëse	efactura:read	—	120
POST	/efactura/inbox/sync Tërheq mesazhet e reja të sistemit kombëtar në kutinë hyrëse	efactura:read	—	10

Çfarë është API e 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,
# prandaj /inbox/sync numëron në grupin 10/min. Vendose në cron, mos e bëj polling.

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

Cikli i e-faturimit kombëtar

Gabimet

Statusi	Lloji	Kodi
422	invalid_request_error	cius_ro_incomplete

Gabimet e zakonshme

Cikli i jetës i normalizuar: not_sent → validating → queued → sent → processing → accepted | rejected | error.
accepted do të thotë e transmetuar ligjërisht. rejected do të thotë që sistemi kombëtar i e-faturimit e refuzoi: korrigjoje dhe paraqite përsëri. error është dështim transporti nga ana jonë dhe mund të riprovohet pa rrezik.
Paraqitja është e pakthyeshme: një kopje e dytë e së njëjtës faturë nuk mund të tërhiqet nga sistemi kombëtar. Prandaj Idempotency-Key është e detyrueshme.
GET /v1/invoices/{id}/xml të jep XML-in UBL (CIUS-RO për Rumaninë) pa asnjë paraqitje — për arkivin tënd ose për një auditim.
Kutia hyrëse: POST /v1/efactura/inbox/sync tërheq mesazhet e reja, GET /v1/efactura/inbox i liston, dhe /download shkarkon arkivin e secilës faturë hyrëse.
Pikat fundore e-Factura funksionojnë vetëm për klientët rumunë; përndryshe merr 404.

Pyetje dhe përgjigje për zhvilluesit

Sa kohë i duhet sistemit kombëtar të e-faturimit për të pranuar një faturë?

Ndryshon, nga sekonda deri në orë. Mos e blloko shitjen: paraqit asinkron dhe trajto accepted dhe rejected si ngjarje.

A mund ta marr XML-in e faturës pa dërguar asgjë në sistemin kombëtar?

Po. GET /v1/invoices/{id}/xml e gjeneron dokumentin pa paraqitje, dhe /efactura/validate me include_xml=true e kthen të koduar në base64.

Sa shpesh mund të ekzekutoj inbox/sync?

Më së shumti 10 thirrje në minutë, por në praktikë, në Rumani, ANAF lejon afërsisht një thirrje listimi mesazhesh në minutë për CIF. Ekzekutoje nga cron, çdo disa minuta.

Çfarë bëj nëse statusi mbetet error?

error është dështim transporti ose autentikimi nga ana jonë, kështu që mund të riprovohet pa rrezik. Nëse vazhdon, dërgo request_id te mbështetja.

Shih edhe