Национално е-фактурирање преку API

Предпроверка (CIUS-RO за Романија), поднесување во националниот систем, нормализиран статус, потпишан одговор и влезно сандаче за фактури од добавувачи.

← Назад кон API документацијата

Првата фактура во 6 чекори

Извршете POST /v1/invoices/{id}/efactura/validate. Предпроверката (CIUS-RO за Романија) не испраќа ништо до националниот систем и ви кажува точно што би било отфрлено.
Поднесете со POST /v1/invoices/{id}/efactura/submit, секогаш со Idempotency-Key. Добивате submission_id и статус.
Следете GET /v1/efactura/submissions/{id} додека не стигне до accepted или rejected.
Присилете свежо барање до националниот систем за е-фактурирање со POST /v1/efactura/submissions/{id}/refresh — се смета во кофата од 10 во минута.
Преземете ја архивата со потпишаниот одговор од националниот систем преку GET /v1/efactura/submissions/{id}/download.

Сите крајни точки

Метод	Крајна точка	Scope	Idempotency-Key	Барања / минута
GET	/invoices/{invoice_id}/xml Преземање UBL XML (CIUS-RO за Романија)	invoices:read	—	120
POST	/invoices/{invoice_id}/efactura/validate Предпроверка — валидација без испраќање	efactura:read	—	120
POST	/invoices/{invoice_id}/efactura/submit Поднесување на фактура до националниот систем за е-фактурирање	efactura:submit	задолжително	10
GET	/efactura/submissions Листа на поднесувања до националниот систем	efactura:read	—	120
GET	/efactura/submissions/{submission_id} Преглед на едно поднесување	efactura:read	—	120
POST	/efactura/submissions/{submission_id}/refresh Барање тековна состојба од националниот систем	efactura:read	—	10
GET	/efactura/submissions/{submission_id}/download Преземање архива со потпишан одговор	efactura:read	—	120
GET	/efactura/inbox Фактури од добавувачи примени преку националниот систем	efactura:read	—	120
GET	/efactura/inbox/{inbound_id} Преглед на една влезна фактура	efactura:read	—	120
GET	/efactura/inbox/{inbound_id}/download Преземање архива на влезна фактура	efactura:read	—	120
POST	/efactura/inbox/sync Повлекување нови пораки од националниот систем во сандачето	efactura:read	—	10

Што е 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,
# па /inbox/sync се смета во кофата за поднесување од 10/мин. Ставете го на cron, не го пратете со polling.

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

Постапката на националното е-фактурирање

Грешки

Статус	Тип	Код
422	invalid_request_error	cius_ro_incomplete

Чести грешки

Нормализиран животен циклус: not_sent → validating → queued → sent → processing → accepted | rejected | error.
accepted значи законски пренесено. rejected значи дека националниот систем за е-фактурирање ја одбил: поправете и поднесете повторно. error е транспортна грешка на наша страна и безбедно е да се повтори.
Поднесувањето е неповратно: вториот примерок од истата фактура не може да се повлече од националниот систем. Затоа Idempotency-Key е задолжителен.
GET /v1/invoices/{id}/xml ви го дава UBL XML (CIUS-RO за Романија) без никакво поднесување — за ваша архива или ревизија.
Сандаче: POST /v1/efactura/inbox/sync повлекува нови пораки, GET /v1/efactura/inbox ги листа, а /download ја презема архивата на секоја влезна фактура.
Крајните точки за e-Factura работат само за румунски тенанти; инаку добивате 404.

Прашања и одговори за програмери

Колку време му треба на националниот систем за е-фактурирање да прифати фактура?

Зависи, од секунди до часови. Не ја блокирајте продажбата: поднесувајте асинхроно и третирајте ги accepted и rejected како настани.

Можам ли да добијам XML на фактурата без да испратам ништо до националниот систем?

Можете. GET /v1/invoices/{id}/xml го генерира документот без поднесување, а /efactura/validate со include_xml=true го враќа base64-кодиран.

Колку често можам да ја извршувам inbox/sync?

Највеќе 10 повици во минута, но во пракса, во Романија, ANAF дозволува приближно едно барање за список на пораки по минута по CIF. Извршувајте го од cron, на секои неколку минути.

Што да направам ако статусот остане error?

error е транспортна или автентикациска грешка на наша страна, па безбедно е да се повтори. Ако упорно се повторува, испратете го request_id на поддршката.

Видете исто така