4invoices API til udviklere

• Det offentlige 4invoices API er REST over HTTPS, med JSON ind og JSON ud.
• Én produktionsvært: https://api.4invoices.net/v1. Der findes ingen separat sandbox-vært.
• OpenAPI 3.1-specifikationen er offentlig og kræver ingen nøgle — importér den direkte i Postman eller en klientgenerator.
• Hvert svar bærer en X-Request-Id-header; angiv den, når du beder om support.
• Alle fiskale skrivninger er idempotente: et nyt forsøg efter timeout udsteder aldrig et andet dokument.

• Hele ANAF e-Factura-forløbet (Rumænien) over API'et: forhåndskontrol, indsendelse, opfølgning, signeret svar og den indgående indbakke. Ingen rumænsk konkurrent eksponerer dette.
• SmartBill har intet endpoint til indsendelse i det nationale e-fakturasystem (ANAF, i Rumænien) — afsendelse er kun en kontoindstilling i brugerfladen — og slet intet endpoint til at liste fakturaer.
• Oblio kan kun oprette kunder og produkter som en bivirkning af at udstede et dokument, ikke som førsteklasses ressourcer.
• UBL-XML-generering (CIUS-RO for Rumænien) uden indsendelse: du får det juridiske dokument som en fil, uden at røre det nationale e-fakturasystem.
• Idempotens på fiskale skrivninger: et nyt forsøg efter timeout producerer ikke en ekstra faktura og forbruger ikke et ekstra nummer.
• En programmatisk læsbar indbakke med leverandørfakturaer — grundlaget for automatiseret afstemning.

1. Opret legitimationsoplysninger i panelet under Fakturering → Indstillinger → API-adgang, og kopiér client_secret — det vises kun én gang.
2. Udfyld virksomhedsprofilen og aktivér mindst én serie af typen fiscale, ellers returnerer udstedelse issuer_profile_incomplete eller no_series_configured.
3. Byt legitimationsoplysningerne til et token: POST /v1/auth/token med grant_type client_credentials. Tokenet varer én time — gem det i cache, og udsted ikke et nyt pr. anmodning.
4. Udsted fakturaen: POST /v1/invoices med en Idempotency-Key-header og vat_rate som procent (21, ikke 0.21).
5. Kør forhåndskontrollen (CIUS-RO for Rumænien) med POST /v1/invoices/{id}/efactura/validate, og send derefter fakturaen til det nationale e-fakturasystem med POST /v1/invoices/{id}/efactura/submit.
6. Følg status med GET /v1/efactura/submissions/{id}, indtil den når accepted eller rejected.

bash
# 1 — token (1 time, gem i 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 — udsted fakturaen (Idempotency-Key er PÅKRÆVET)
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}",
    # Én nøgle pr. LOGISK operation — genbrug den ved nyt forsøg, generér aldrig en ny.
    "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}],   # procent, ikke 0.21
    "currency": "RON",
}, timeout=60).json()

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

• Flowet er client_credentials: du bytter client_id + client_secret til et Bearer access_token.
• Tokenet udløber efter 3600 sekunder. Forny det før udløb, ikke ved hvert kald — POST /auth/token har sin egen hastighedsgrænse pr. IP.
• client_secret gemmes kun som hash og kan ikke genskabes. Mister du det, opretter du nye legitimationsoplysninger og tilbagekalder de gamle.
• Kun server-til-server. Ingen browser-origin tillades via CORS: fra sidens JavaScript ville secret lække til den besøgende.
• Scopes tildeles pr. legitimationsoplysning. Opret separate legitimationsoplysninger til hvert system, og giv hver især det mindste sæt scopes, den har brug for.

Fakturering → Indstillinger → API-adgang

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
// Gem tokenet i cache; udsted ikke et nyt pr. anmodning.
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 er en PROCENT: 21 betyder 21 %.
• Værdier i (0, 1] afvises — 0,19 er en brøkdel, og 1 er tvetydig mellem 1 % og 100 %.
• 0 er gyldigt og betyder momsfritaget eller omvendt betalingspligt; skriv den lovmæssige angivelse i notes.
• unit_price er den NETTO enhedspris, når udstederen er momspligtig.
• Har du brug for totalerne, før du gennemfører? POST /v1/invoices/preview-totals kører den samme beregning uden at forbruge et fiskalt nummer.

• Headeren Idempotency-Key er PÅKRÆVET på POST /invoices, POST /invoices/{id}/storno og POST /invoices/{id}/efactura/submit.
• Nøgler huskes i 24 timer. Gentagelse af samme nøgle med samme krop returnerer det oprindelige resultat og sætter Idempotency-Replayed: true.
• Samme nøgle med en anden krop returnerer 409 idempotency_key_reuse — et allerede udstedt fiskalt dokument overskrives aldrig.
• Én nøgle pr. LOGISK operation, ikke pr. HTTP-forsøg: order-10457-invoice, ikke en ny UUID ved hvert nyt forsøg.
• Begrundelsen er juridisk, ikke teknisk: et forbrugt fiskalt nummer og en faktura indsendt i det nationale e-fakturasystem (i Rumænien: SPV) kan ikke trækkes tilbage.

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

• Den reelle forskel: hele forløbet med det nationale e-fakturasystem (i Rumænien: ANAF e-Factura) kører via API'et, ikke kun dokumentgenerering.
• POST /invoices/{id}/efactura/validate kører forhåndskontrollen (CIUS-RO for Rumænien) og returnerer de præcise felter, det nationale e-fakturasystem ville afvise, uden at sende noget.
• GET /invoices/{id}/xml genererer UBL-XML (CIUS-RO for Rumænien) uden indsendelse — nyttigt til dit eget arkiv eller en intern revision.
• POST /invoices/{id}/efactura/submit indsender den i det nationale e-fakturasystem (i Rumænien: SPV). Det kan ikke gøres om: en anden kopi af samme faktura kan ikke trækkes tilbage fra systemet.
• Livscyklussen er normaliseret: not_sent → validating → queued → sent → processing → accepted | rejected | error. accepted betyder lovligt transmitteret; error er en transportfejl på vores side, og den er sikker at forsøge igen.
• GET /efactura/submissions/{id}/download henter arkivet med det nationale e-fakturasystems signerede svar (i Rumænien: ANAF).
• Den indgående side findes også: POST /efactura/inbox/sync henter nye beskeder fra det nationale e-fakturasystem (i Rumænien: SPV), og GET /efactura/inbox lister de fakturaer, dine leverandører har sendt dig.

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)

• Hver 4xx- og 5xx-fejl bruger samme kuvert: { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
• type er den grove klasse, du forgrener på ("kan jeg forsøge igen?"), og code er den stabile årsag, du mapper ind i dit eget system.
• param er den punkterede sti til det fejlende felt, for eksempel lines.0.vat_rate.
• errors[] optræder, når en enkelt anmodning har problemer i mere end ét felt.
• request_id logges på vores side. Angiv den i enhver supportsag — den peger på den præcise anmodning.
• Et 404 returneres også for et id, der tilhører en anden tenant: vi bekræfter aldrig, at en andens data findes.

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" }
    ]
  }
}

• Grænserne gælder pr. legitimationsoplysning, pr. minut: 120 for læsninger, 30 for skrivninger og 10 for operationerne mod det nationale e-fakturasystem (submit, refresh, inbox/sync).
• X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset optræder på ALLE svar, inklusive 429.
• Et 429 bærer også Retry-After i sekunder. Respektér det; forsøg ikke igen i en stram løkke.
• Kvoten på 10 pr. minut findes, fordi ANAF i Rumænien selv tillader cirka ét kald til beskedlisten pr. minut pr. CIF.
• Sæt /efactura/inbox/sync på en cron-job, ikke på aggressiv polling.
• Har du brug for højere lofter? Spørg via Kontakt med dit forventede daglige volumen.

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
// Respektér Retry-After; forsøg aldrig igen ved en 4xx andet end 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;
}

// Et nyt forsøg af en skrivning SKAL genbruge DEN SAMME Idempotency-Key, ellers udsteder du
// et andet fiskalt dokument.

Hvert emne har sin egen side med de relevante endpoints, eksempler og fejl.

• Godkendelse i 4invoices APIByt client_id og client_secret til et Bearer-token, der er gyldigt i én time, kun server-til-server.
• Udstedelse af fakturaer via APIPOST /invoices med en Idempotency-Key, moms som procenter, plus opslag, storno og markering som betalt.
• Kunder og opslag i ANAF-registret (Rumænien)En indsættelse eller opdatering deduplikeret på tax_id plus et opslag i ANAF-registret (Rumænien), så e-fakturaen ikke afvises.
• National e-fakturering via APIForhåndskontrol (CIUS-RO for Rumænien), indsendelse i det nationale e-fakturasystem, normaliseret status, signeret svar og den indgående leverandørindbakke.
• Nummerserier i API'etUden en aktiv serie af typen fiscale returnerer udstedelse 409 no_series_configured.
• Fejlkoder og fejlkuvertenÉn form på alle ruter: type, code, message, param, doc_url, request_id og errors.
• Hastighedsgrænser og nye forsøg120 læsninger, 30 skrivninger og 10 operationer mod det nationale e-fakturasystem pr. minut pr. legitimationsoplysning, med X-RateLimit-*-headere.

• Sender moms som brøkdel (0.19) eller som 1. Begge afvises; send 19 eller 21.
• Udsteder et token pr. anmodning. Tokenet holder en time; gem det i cache, ellers rammer du token-endpointets grænse pr. IP.
• Genererer en ny idempotensnøgle ved hvert nyt forsøg — præcis det scenarie, der giver dublerede fakturaer.
• Kalder fra browser-JavaScript. CORS blokerer alle origins, og secret ville alligevel blive eksponeret.
• Indsender i det nationale e-fakturasystem uden forhåndskontrol (CIUS-RO for Rumænien). En forkert indsendelse kan ikke trækkes tilbage.
• Poller /efactura/submissions/{id}/refresh mere end 10 gange i minuttet — den kvote deles med submit.
• Udsteder, før virksomhedsprofilen er komplet, og før der findes en aktiv fiskal serie.