Documentație

Documentația 4invoices are două straturi: panoul, pe care îl folosești fără să scrii cod, și API-ul public, prin care sistemul tău emite facturi și duce documentul până la ANAF. Pagina asta e punctul de intrare pentru al doilea strat.

Deschide documentația completă a API-ului →

Ce poți automatiza

API-ul public acoperă emiterea de facturi și proforme, storno, clienți cu verificare în registrul ANAF, seriile de numerotare și tot circuitul e-Factura: preflight CIUS-RO, depunere în SPV, urmărirea stării, răspunsul semnat și inbox-ul de facturi primite de la furnizori.

https://api.4invoices.net/v1 · 25 endpoints · Specificația OpenAPI (fără cheie)

invoices:read · invoices:write · clients:read · clients:write · efactura:read · efactura:submit

Autentificare

Înainte de primul apelFacturare → Setări → Acces API
bash
curl -sS -X POST https://api.4invoices.net/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "cli_XXXXXXXXXXXX",
    "client_secret": "sec_XXXXXXXXXXXXXXXXXXXX"
  }'

# → {"access_token":"eyJ...","token_type":"Bearer","expires_in":3600,
#    "scope":"invoices:read invoices:write efactura:submit"}
Doar server-to-server. Nu apela API-ul din JavaScript de browser: client_secret ar ajunge la utilizator, iar CORS blochează oricum orice origin.

Prima factură în 6 pași

  1. Generează o credențială în panou, la Facturare → Setări → Acces API, și notează client_secret — se afișează o singură dată.
  2. Completează profilul companiei și activează cel puțin o serie de tip fiscale, altfel emiterea returnează issuer_profile_incomplete sau no_series_configured.
  3. Schimbă credențiala pe un token: POST /v1/auth/token cu grant_type client_credentials. Tokenul e valabil o oră — pune-l în cache, nu cere unul la fiecare request.
  4. Emite factura: POST /v1/invoices cu antetul Idempotency-Key și vat_rate ca procent (21, nu 0.21).
  5. Rulează preflight-ul CIUS-RO cu POST /v1/invoices/{id}/efactura/validate, apoi trimite la ANAF cu POST /v1/invoices/{id}/efactura/submit.
  6. Urmărește starea cu GET /v1/efactura/submissions/{id} până ajunge în accepted sau rejected.
bash
# 1 — token (1 oră, ține-l în memoria cache)
ACCESS_TOKEN=$(curl -sS -X POST https://api.4invoices.net/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"client_credentials","client_id":"cli_XXX","client_secret":"sec_XXX"}' \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["access_token"])')

# 2 — emite factura (Idempotency-Key este OBLIGATORIU)
curl -sS -X POST https://api.4invoices.net/v1/invoices \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-10457-invoice' \
  -d '{"buyer":{"name":"Exemplu Comert SRL","tax_id":"RO12345678","county":"Cluj","city":"Cluj-Napoca","country":"RO"},
       "lines":[{"description":"Abonament SaaS","quantity":1,"unit_price":400,"vat_rate":21}]}'

# 3 — preflight CIUS-RO, then send to ANAF
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/efactura/validate \
  -H "Authorization: Bearer $ACCESS_TOKEN"

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'

Ghiduri pe subiect

Fiecare subiect are pagina lui, cu endpoint-urile, exemplele și erorile specifice.

Deschide documentația completă a API-ului →