API per a desenvolupadors de 4invoices

• L'API pública de 4invoices és REST sobre HTTPS, amb JSON d'entrada i de sortida.
• Un únic host de producció: https://api.4invoices.net/v1. No hi ha un host sandbox separat.
• L'especificació OpenAPI 3.1 és pública i no requereix clau — importa-la directament a Postman o a un generador de clients.
• Cada resposta porta una capçalera X-Request-Id; cita-la quan demanis suport.
• Cada escriptura fiscal és idempotent: un reintent després d'un timeout no emet mai un segon document.

• El cicle complet de l'e-Factura de l'ANAF de Romania a través de l'API: validació prèvia, presentació, seguiment, resposta signada i la safata d'entrada. Cap competidor romanès ho exposa.
• SmartBill no té cap punt final per a la presentació al sistema nacional de facturació electrònica (l'ANAF, a Romania) — l'enviament al SPV és només una opció de configuració del compte a la interfície — i tampoc no té cap punt final per llistar factures.
• Oblio només pot crear clients i productes com a efecte secundari de l'emissió d'un document, no com a recursos de primera classe.
• Generació de XML UBL (a Romania, CIUS-RO) sense presentar: obtens el document legal com a fitxer sense tocar el sistema nacional de facturació electrònica.
• Idempotència en les escriptures fiscals: un reintent després d'un timeout no produeix una segona factura ni gasta un segon número.
• Una safata d'entrada de factures de proveïdors llegible per programari — la base de la conciliació automatitzada.

1. Crea una credencial al panell a Facturació → Configuració → Accés API i copia el client_secret — es mostra una sola vegada.
2. Completa el perfil de l'empresa i activa almenys una sèrie de tipus fiscale; altrament l'emissió retorna issuer_profile_incomplete o no_series_configured.
3. Canvia la credencial per un token: POST /v1/auth/token amb grant_type client_credentials. El token dura una hora — guarda'l a la memòria cau, no en demanis un per cada petició.
4. Emet la factura: POST /v1/invoices amb una capçalera Idempotency-Key i vat_rate com a percentatge (21, no 0.21).
5. Fes la validació prèvia (a Romania, CIUS-RO) amb POST /v1/invoices/{id}/efactura/validate i després envia la factura al sistema nacional de facturació electrònica (a Romania, l'ANAF) amb POST /v1/invoices/{id}/efactura/submit.
6. Segueix l'estat amb GET /v1/efactura/submissions/{id} fins que arribi a accepted o rejected.

bash
# 1 — token (1 hora, guarda'l a la memòria cau)
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 — emet la factura (Idempotency-Key és OBLIGATÒRIA)
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'

javascript
const BASE = "https://api.4invoices.net/v1";

const token = await fetch(`${BASE}/auth/token`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    grant_type: "client_credentials",
    client_id: process.env.FOURINVOICES_CLIENT_ID,
    client_secret: process.env.FOURINVOICES_CLIENT_SECRET,
  }),
}).then((r) => r.json()).then((d) => d.access_token);

const invoice = await fetch(`${BASE}/invoices`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order-${orderId}-invoice`,
  },
  body: JSON.stringify({
    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 }],
    currency: "RON",
    metadata: { order_id: String(orderId) },
  }),
}).then((r) => r.json());

console.log(invoice.number, invoice.totals); // "FCT-000123" { net, vat, gross }

python
import os, uuid, requests

BASE = "https://api.4invoices.net/v1"

token = requests.post(f"{BASE}/auth/token", json={
    "grant_type": "client_credentials",
    "client_id": os.environ["FOURINVOICES_CLIENT_ID"],
    "client_secret": os.environ["FOURINVOICES_CLIENT_SECRET"],
}, timeout=30).json()["access_token"]

headers = {
    "Authorization": f"Bearer {token}",
    # Una clau per cada operació LÒGICA — reutilitza-la en reintentar, mai no la regeneris.
    "Idempotency-Key": f"order-{order_id}-invoice",
}

invoice = requests.post(f"{BASE}/invoices", headers=headers, json={
    "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}],   # percentatge, no 0,21
    "currency": "RON",
}, timeout=60).json()

print(invoice["number"], invoice["totals"])

• El flux és client_credentials: canvies client_id + client_secret per un access_token Bearer.
• El token caduca als 3600 segons. Renova'l abans que caduqui, no a cada crida — POST /auth/token té el seu propi límit per IP.
• El client_secret es guarda només com a hash i no es pot recuperar. Si el perds, crees una nova credencial i revoques la vella.
• Només de servidor a servidor. CORS no deixa passar cap origen del navegador: des del JavaScript de la pàgina, el secret arribaria al visitant.
• Els àmbits s'atorguen per credencial. Emet una credencial separada per a cada sistema i dona a cadascun el mínim d'àmbits que necessita.

Facturació → Configuració → Accés 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"}

javascript
// Guarda el token a la memòria cau; no en generis un per cada petició.
let cached = { token: "", expiresAt: 0 };

async function getToken() {
  if (cached.token && Date.now() < cached.expiresAt - 60_000) return cached.token;

  const res = await fetch("https://api.4invoices.net/v1/auth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "client_credentials",
      client_id: process.env.FOURINVOICES_CLIENT_ID,
      client_secret: process.env.FOURINVOICES_CLIENT_SECRET,
    }),
  });
  if (!res.ok) throw new Error(`token ${res.status}`);

  const data = await res.json();
  cached = { token: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 };
  return cached.token;
}

• vat_rate és un PERCENTATGE: 21 vol dir 21%.
• Els valors dins de (0, 1] es rebutgen — 0,19 és una fracció, i 1 és ambigu entre 1% i 100%.
• 0 és vàlid i significa exempt o autoliquidació (reverse charge); posa la menció legal a notes.
• unit_price és el preu unitari NET quan l'emissor és subjecte passiu de l'IVA.
• Vols els totals abans de confirmar? POST /v1/invoices/preview-totals fa la mateixa aritmètica sense consumir cap número fiscal.

• La capçalera Idempotency-Key és OBLIGATÒRIA a POST /invoices, POST /invoices/{id}/storno i POST /invoices/{id}/efactura/submit.
• Les claus es recorden durant 24 hores. Repetir la mateixa clau amb el mateix cos retorna el resultat original i posa Idempotency-Replayed: true.
• La mateixa clau amb un cos diferent retorna 409 idempotency_key_reuse — un document fiscal ja emès mai no se sobreescriu.
• Una clau per cada operació LÒGICA, no per cada intent HTTP: order-10457-invoice, no un UUID nou a cada reintent.
• El motiu és legal, no tècnic: un número fiscal consumit i una factura presentada al sistema nacional de facturació electrònica (a Romania, el SPV) no es poden retirar.

bash
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",
      "address": "Str. Fabricii 12",
      "city": "Cluj-Napoca",
      "county": "Cluj",
      "country": "RO",
      "email": "[email protected]"
    },
    "lines": [
      { "description": "Abonament SaaS, iulie", "quantity": 1, "unit_price": 400, "vat_rate": 21, "unit": "buc" },
      { "description": "Implementare", "quantity": 6, "unit_price": 250, "vat_rate": 21, "unit": "ora" }
    ],
    "currency": "RON",
    "document_kind": "factura",
    "due_date": "2026-08-15",
    "metadata": { "order_id": "10457" }
  }'

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

• invoices:read
• invoices:write
• clients:read
• clients:write
• efactura:read
• efactura:submit

• El veritable diferenciador: tot el cicle amb el sistema nacional de facturació electrònica (a Romania, l'e-Factura de l'ANAF) s'executa a través de l'API, no només la generació del document.
• POST /invoices/{id}/efactura/validate fa la validació prèvia (a Romania, CIUS-RO) i retorna els camps exactes que el sistema nacional de facturació electrònica rebutjaria, sense enviar res.
• GET /invoices/{id}/xml genera el XML UBL (a Romania, CIUS-RO) sense cap presentació — útil per al teu propi arxiu o per a una auditoria interna.
• POST /invoices/{id}/efactura/submit la presenta al sistema nacional de facturació electrònica (a Romania, el SPV). És irreversible: una segona còpia de la mateixa factura no es pot retirar del sistema.
• El cicle de vida està normalitzat: not_sent → validating → queued → sent → processing → accepted | rejected | error. accepted vol dir transmesa legalment; error és una fallada de transport per la nostra part i es pot reintentar sense risc.
• GET /efactura/submissions/{id}/download descarrega l'arxiu amb la resposta signada del sistema nacional (a Romania, l'ANAF).
• Existeix també la part de recepció: POST /efactura/inbox/sync recull els nous missatges del sistema nacional de facturació electrònica (a Romania, el SPV) i GET /efactura/inbox llista les factures que t'han enviat els teus proveïdors.

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)

• Cada 4xx i 5xx usa el mateix sobre: { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
• type és la classe general segons la qual decideixes («puc reintentar?»), i code és la raó estable que mapeges al teu propi sistema.
• param és el camí amb punts del camp que falla, per exemple lines.0.vat_rate.
• errors[] apareix quan una mateixa petició té problemes en més d'un camp.
• request_id es registra per la nostra part. Cita'l en qualsevol tiquet de suport — fixa la petició exacta.
• També es retorna un 404 per a un id que pertany a un altre client: mai no confirmem que existeixen dades d'un altre.

json
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "Datele trimise nu sunt valide.",
    "param": "lines.0.vat_rate",
    "doc_url": "https://4invoices.net/ro/api-dezvoltatori#errors",
    "request_id": "req_8a893f2f33d4472da8d6e144",
    "errors": [
      { "param": "lines.0.vat_rate", "message": "VAT rate must be a percent (21), not a fraction", "type": "value_error" }
    ]
  }
}

• Els límits són per credencial, per minut: 120 per a lectures, 30 per a escriptures, 10 per a les operacions amb el sistema nacional de facturació electrònica (submit, refresh, inbox/sync).
• X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset apareixen a CADA resposta, inclòs el 429.
• Un 429 porta també Retry-After en segons. Respecta'l; no reintentis en un bucle estret.
• El grup de 10 per minut existeix perquè, a Romania, l'ANAF permet aproximadament una crida de llistat de missatges per minut per CIF.
• Posa /efactura/inbox/sync en un cron, no en un sondeig agressiu.
• Necessites sostres més alts? Demana-ho a través de Contacte, indicant el teu volum diari previst.

X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset · Retry-After

http
HTTP/2 429
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1785312000
Retry-After: 17
Content-Type: application/json

{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded",
 "message":"...","doc_url":"https://4invoices.net/ro/api-dezvoltatori#errors",
 "request_id":"req_..."}}

javascript
// Respecta Retry-After; mai no reintentis un 4xx que no sigui 429.
async function call(url, init, attempt = 0) {
  const res = await fetch(url, init);
  if (res.status === 429 || res.status >= 500) {
    if (attempt >= 5) return res;
    const retryAfter = Number(res.headers.get("Retry-After")) || 2 ** attempt;
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return call(url, init, attempt + 1);
  }
  return res;
}

// Un reintent d'escriptura HA de reutilitzar la MATEIXA Idempotency-Key, altrament emetràs
// un segon document fiscal.

Cada tema té la seva pàgina amb els punts finals, exemples i errors rellevants.

• Autenticació a l'API de 4invoicesCanvies client_id i client_secret per un token Bearer d'una hora, només de servidor a servidor.
• Emissió de factures per l'APIPOST /invoices amb Idempotency-Key, IVA com a percentatges, més el llistat, el storno i el marcatge com a pagada.
• Clients i consulta al registre d'empresesUna inserció o actualització deduplicada per tax_id més una consulta al registre ANAF (Romania) perquè la factura electrònica no sigui rebutjada.
• Sistema nacional de facturació electrònica per l'APIValidació prèvia (a Romania, CIUS-RO), presentació al sistema nacional (a Romania, el SPV), estat normalitzat, resposta signada i safata d'entrada de proveïdors.
• Sèries de numeració a l'APISense una sèrie activa de tipus fiscale, l'emissió retorna 409 no_series_configured.
• Codis d'error i el sobre d'errorUna sola forma a totes les rutes: type, code, message, param, doc_url, request_id i errors.
• Límits de peticions i reintents120 lectures, 30 escriptures i 10 operacions amb el sistema nacional de facturació electrònica per minut per credencial, amb capçaleres X-RateLimit-*.

• Enviar el tipus d'IVA com a fracció (0,19) o com a 1. Els dos es rebutgen; envia 19 o 21.
• Crear un token a cada petició. El token dura una hora; guarda'l a la memòria cau o toparàs amb el límit per IP del punt final del token.
• Generar una clau d'idempotència nova a cada reintent — exactament l'escenari que produeix factures duplicades.
• Cridar des del JavaScript del navegador. CORS bloqueja tots els orígens, i de totes maneres el secret quedaria exposat.
• Presentar al sistema nacional de facturació electrònica sense la validació prèvia (a Romania, CIUS-RO). Un enviament erroni no es pot retirar.
• Sondejar /efactura/submissions/{id}/refresh més de 10 vegades per minut — aquest grup es comparteix amb submit.
• Emetre factures abans que el perfil de l'empresa estigui complet i existeixi una sèrie fiscal activa.