Faktur elektronik nasional melalui API

Pemeriksaan awal (CIUS-RO untuk Rumania), pengajuan ke sistem nasional, status ternormalisasi, respons bertanda tangan, dan kotak masuk faktur pemasok.

← Kembali ke dokumentasi API

Faktur pertama Anda dalam 6 langkah

Jalankan POST /v1/invoices/{id}/efactura/validate. Pemeriksaan awal (CIUS-RO untuk Rumania) tidak mengirim apa pun ke sistem nasional dan memberi tahu Anda tepatnya apa yang akan ditolak.
Ajukan dengan POST /v1/invoices/{id}/efactura/submit, selalu dengan Idempotency-Key. Anda mendapat submission_id dan status.
Pantau GET /v1/efactura/submissions/{id} hingga mencapai accepted atau rejected.
Paksa permintaan status baru ke sistem faktur elektronik nasional dengan POST /v1/efactura/submissions/{id}/refresh — ini dihitung dalam ember 10 per menit.
Unduh arsip respons bertanda tangan dari sistem nasional dengan GET /v1/efactura/submissions/{id}/download.

Semua endpoint

Metode	Endpoint	Scope	Idempotency-Key	Permintaan / menit
GET	/invoices/{invoice_id}/xml Unduh XML UBL (CIUS-RO untuk Rumania)	invoices:read	—	120
POST	/invoices/{invoice_id}/efactura/validate Pemeriksaan awal — validasi tanpa mengirim	efactura:read	—	120
POST	/invoices/{invoice_id}/efactura/submit Ajukan faktur ke sistem faktur elektronik nasional	efactura:submit	wajib	10
GET	/efactura/submissions Daftar pengajuan ke sistem nasional	efactura:read	—	120
GET	/efactura/submissions/{submission_id} Ambil satu pengajuan	efactura:read	—	120
POST	/efactura/submissions/{submission_id}/refresh Minta status terkini dari sistem nasional	efactura:read	—	10
GET	/efactura/submissions/{submission_id}/download Unduh arsip respons bertanda tangan	efactura:read	—	120
GET	/efactura/inbox Faktur pemasok yang diterima melalui sistem nasional	efactura:read	—	120
GET	/efactura/inbox/{inbound_id} Ambil satu faktur masuk	efactura:read	—	120
GET	/efactura/inbox/{inbound_id}/download Unduh arsip faktur masuk	efactura:read	—	120
POST	/efactura/inbox/sync Tarik pesan baru dari sistem nasional ke kotak masuk	efactura:read	—	10

Apa itu 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,
# sehingga /inbox/sync dihitung dalam ember pengajuan 10/menit. Jadwalkan dengan cron, jangan di-polling.

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

Alur faktur elektronik nasional

Error

Status	Tipe	Kode
422	invalid_request_error	cius_ro_incomplete

Kesalahan umum

Siklus hidup ternormalisasi: not_sent → validating → queued → sent → processing → accepted | rejected | error.
accepted berarti telah dikirim secara sah. rejected berarti sistem faktur elektronik nasional menolaknya: perbaiki dan ajukan lagi. error adalah kegagalan transportasi di pihak kami dan aman untuk dicoba ulang.
Pengajuan tidak dapat dibatalkan: salinan kedua dari faktur yang sama tidak dapat ditarik dari sistem nasional. Itulah sebabnya Idempotency-Key wajib.
GET /v1/invoices/{id}/xml memberi Anda XML UBL (CIUS-RO untuk Rumania) tanpa pengajuan sama sekali — untuk arsip atau audit Anda sendiri.
Kotak masuk: POST /v1/efactura/inbox/sync menarik pesan baru, GET /v1/efactura/inbox mendaftarkannya, dan /download mengambil arsip setiap faktur masuk.
Endpoint e-Factura hanya berfungsi untuk tenant Rumania; selain itu Anda mendapat 404.

Tanya jawab untuk pengembang

Berapa lama sistem faktur elektronik nasional menerima faktur?

Bervariasi, dari detik hingga jam. Jangan menghalangi penjualan: ajukan secara asinkron dan perlakukan accepted serta rejected sebagai peristiwa.

Bisakah saya mendapatkan XML faktur tanpa mengirim apa pun ke sistem nasional?

Bisa. GET /v1/invoices/{id}/xml menghasilkan dokumen tanpa pengajuan, dan /efactura/validate dengan include_xml=true mengembalikannya dalam format base64.

Seberapa sering saya bisa menjalankan inbox/sync?

Paling banyak 10 panggilan per menit, tetapi dalam praktiknya di Rumania ANAF mengizinkan sekitar satu panggilan daftar pesan per menit per CIF. Jalankan dari cron, setiap beberapa menit.

Apa yang harus saya lakukan jika statusnya tetap error?

error adalah kegagalan transportasi atau autentikasi di pihak kami, sehingga aman untuk dicoba ulang. Jika terus berlanjut, kirim request_id ke dukungan.

Lihat juga