4invoices API za razvijalce

• Javni API 4invoices je REST prek HTTPS: JSON na vhodu in JSON na izhodu.
• Na voljo je en produkcijski gostitelj: https://api.4invoices.net/v1. Ločenega testnega gostitelja ni.
• Specifikacija OpenAPI 3.1 je javna in dostopna brez ključa — uvozite jo neposredno v Postman ali v generator odjemalcev.
• Vsak odgovor vsebuje glavo X-Request-Id; navedite jo, ko se obrnete na podporo.
• Vsak davčni zapis je idempotenten: ponovni poskus po preteku časovne omejitve nikoli ne izda drugega dokumenta.

• Celoten romunski krog ANAF e-Factura prek API: predpregled, oddaja, sledenje, podpisani odgovor in vhodni nabiralnik. Tega ne ponuja noben romunski konkurent.
• SmartBill nima nobene končne točke za oddajo v nacionalni sistem e-računov (ANAF, v Romuniji) — pošiljanje v SPV je le nastavitev računa v uporabniškem vmesniku — in sploh nima končne točke za seznam računov.
• Oblio lahko stranke in izdelke ustvari le kot stranski učinek izdaje dokumenta, ne kot samostojne vire.
• Ustvarjanje XML UBL (v Romuniji CIUS-RO) brez oddaje: pravni dokument dobite kot datoteko, ne da bi se dotaknili nacionalnega sistema e-računov.
• Idempotentnost davčnih zapisov: ponovni poskus po preteku časovne omejitve ne ustvari drugega računa in ne porabi druge številke.
• Programsko berljiv nabiralnik računov dobaviteljev — osnova za samodejno usklajevanje.

1. Ustvarite poverilnico v panelu, pod Izstavljanje računov → Nastavitve → Dostop do API, in kopirajte client_secret — prikaže se samo enkrat.
2. Dopolnite profil podjetja in aktivirajte vsaj en niz vrste fiscale, sicer izdaja vrne issuer_profile_incomplete ali no_series_configured.
3. Poverilnico zamenjajte za žeton: POST /v1/auth/token z grant_type client_credentials. Žeton velja eno uro — shranite ga v predpomnilnik, ne zahtevajte novega ob vsakem klicu.
4. Izdajte račun: POST /v1/invoices z glavo Idempotency-Key in vat_rate kot odstotkom (21, ne 0.21).
5. Zaženite predpregled s POST /v1/invoices/{id}/efactura/validate (za Romunijo profil CIUS-RO) in račun nato pošljite v nacionalni sistem e-računov (v Romuniji ANAF) s POST /v1/invoices/{id}/efactura/submit.
6. Stanje spremljajte z GET /v1/efactura/submissions/{id}, dokler ne doseže accepted ali rejected.

bash
# 1 — žeton (1 ura, shranite ga v predpomnilnik)
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 — izdajte račun (Idempotency-Key je OBVEZEN)
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}",
    # En ključ za VSAKO LOGIČNO operacijo — ob ponovnem poskusu ga ponovno uporabite, nikoli ga ne ustvarjajte znova.
    "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}],   # odstotek, ne 0.21
    "currency": "RON",
}, timeout=60).json()

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

• Potek je client_credentials: client_id in client_secret zamenjate za Bearer access_token.
• Žeton poteče po 3600 sekundah. Osvežite ga pred potekom, ne ob vsakem klicu — POST /auth/token ima lastno omejitev na IP-naslov.
• client_secret se hrani samo kot zgoščena vrednost in ga ni mogoče obnoviti. Če ga izgubite, ustvarite novo poverilnico in prekličete staro.
• Izključno strežnik-strežnik. CORS ne dovoli nobenega izvora iz brskalnika: iz JavaScripta na strani bi skrivnost ušla k obiskovalcu.
• Obsegi (scopes) se dodelijo posamezni poverilnici. Za vsak sistem izdajte ločeno poverilnico in vsaki dodelite le najmanjše obsege, ki jih potrebuje.

Izstavljanje računov → Nastavitve → Dostop do 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
// Žeton shranite v predpomnilnik; ne ustvarjajte ga za vsak zahtevek.
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 je ODSTOTEK: 21 pomeni 21%.
• Vrednosti v intervalu (0, 1] so zavrnjene — 0.19 je ulomek, 1 pa je dvoumna med 1% in 100%.
• 0 je veljavna vrednost in pomeni oprostitev ali obrnjeno davčno obveznost; zakonsko navedbo vpišite v notes.
• unit_price je NETO cena na enoto, kadar je izdajatelj zavezanec za DDV.
• Potrebujete zneske, preden zapis potrdite? POST /v1/invoices/preview-totals izvede enak izračun, ne da bi porabil davčno številko.

• Glava Idempotency-Key je OBVEZNA pri POST /invoices, POST /invoices/{id}/storno in POST /invoices/{id}/efactura/submit.
• Ključi se hranijo 24 ur. Ponovna uporaba istega ključa z enakim telesom vrne prvotni rezultat in nastavi Idempotency-Replayed: true.
• Isti ključ z drugačnim telesom vrne 409 idempotency_key_reuse — že izdan davčni dokument se nikoli ne prepiše.
• En ključ na LOGIČNO operacijo, ne na poskus HTTP: order-10457-invoice, ne nov UUID ob vsakem ponovnem poskusu.
• Razlog je pravni, ne tehnični: porabljene davčne številke in računa, oddanega v nacionalni sistem e-računov (v Romuniji SPV), ni mogoče umakniti.

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

• Resnična prednost: celoten krog oddaje v nacionalni sistem e-računov (v Romuniji ANAF e-Factura) poteka prek API, ne le ustvarjanje dokumenta.
• POST /invoices/{id}/efactura/validate izvede predpregled (v Romuniji CIUS-RO) in vrne natanko tista polja, ki bi jih nacionalni sistem e-računov zavrnil, ne da bi karkoli poslal.
• GET /invoices/{id}/xml ustvari XML UBL (v Romuniji CIUS-RO) brez oddaje — uporabno za lasten arhiv ali notranjo revizijo.
• POST /invoices/{id}/efactura/submit račun odda v nacionalni sistem e-računov (v Romuniji SPV). To je nepovratno: druge kopije istega računa ni mogoče umakniti iz sistema.
• Življenjski cikel je normaliziran: not_sent → validating → queued → sent → processing → accepted | rejected | error. accepted pomeni pravno veljaven prenos; error je napaka prenosa na naši strani in ponovni poskus je varen.
• GET /efactura/submissions/{id}/download prenese arhiv s podpisanim odgovorom nacionalnega sistema (v Romuniji ANAF).
• Obstaja tudi vhodna stran: POST /efactura/inbox/sync prevzame nova sporočila iz nacionalnega sistema e-računov (v Romuniji SPV), GET /efactura/inbox pa izpiše račune, ki so vam jih poslali dobavitelji.

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)

• Vsak odgovor 4xx in 5xx uporablja isto ovojnico: { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
• type je groba kategorija, po kateri razvejite logiko („ali lahko poskusim znova?“), code pa je stabilen razlog, ki ga preslikate v svoj sistem.
• param je pot do problematičnega polja v zapisu s pikami, na primer lines.0.vat_rate.
• errors[] se pojavi, kadar ima ena zahteva težave v več poljih.
• request_id beležimo na naši strani. Navedite ga v vsakem zahtevku za podporo — z njim natanko določimo zahtevo.
• 404 se vrne tudi za id, ki pripada drugemu najemniku (tenantu): nikoli ne potrdimo, da tuji podatki obstajajo.

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

• Omejitve veljajo na poverilnico in na minuto: 120 za branja, 30 za zapise, 10 za operacije z nacionalnim sistemom e-računov (submit, refresh, inbox/sync).
• X-RateLimit-Limit, X-RateLimit-Remaining in X-RateLimit-Reset so prisotne v VSAKEM odgovoru, tudi v 429.
• Odgovor 429 vsebuje tudi Retry-After v sekundah. Upoštevajte ga; ne ponavljajte v tesni zanki.
• Kvota 10/min obstaja zato, ker v Romuniji ANAF dovoli približno en klic za seznam sporočil na minuto na CIF.
• /efactura/inbox/sync zaganjajte s cronom, ne z agresivnim pozivanjem.
• Potrebujete višje omejitve? Pišite nam prek strani Kontakt in navedite pričakovani dnevni obseg.

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
// Upoštevajte Retry-After; nikoli ne ponavljajte 4xx razen 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;
}

// Ponovni poskus zapisa MORA uporabiti ISTI Idempotency-Key, sicer izdate
// drugi fiskalni dokument.

Vsaka tema ima svojo stran z ustreznimi končnimi točkami, primeri in napakami.

• Avtentikacija v API 4invoicesZamenjate client_id in client_secret za enourni žeton Bearer, izključno strežnik-strežnik.
• Izdajanje računov prek APIPOST /invoices z Idempotency-Key, DDV v odstotkih, poleg tega seznam, storno in oznaka plačano.
• Stranke in preverjanje v registru podjetijVstavljanje ali posodabljanje (upsert), deduplicirano po tax_id, in poizvedba v registru ANAF (Romunija), da e-račun ni zavrnjen.
• Nacionalni sistem e-računov prek APIPredpregled (v Romuniji CIUS-RO), oddaja v nacionalni sistem (v Romuniji SPV), normalizirano stanje, podpisan odgovor in prejeti računi dobaviteljev.
• Nizi številčenja v APIBrez aktivnega niza vrste fiscale izdaja vrne 409 no_series_configured.
• Kode napak in ovojnica napakeEna oblika na vseh poteh: type, code, message, param, doc_url, request_id in errors.
• Omejitve zahtev in ponovni poskusi120 branj, 30 pisanj in 10 operacij z nacionalnim sistemom e-računov na minuto na poverilnico, z glavami X-RateLimit-*.

• Pošiljanje DDV kot ulomka (0.19) ali kot 1. Oboje je zavrnjeno; pošljite 19 ali 21.
• Pridobivanje žetona za vsako zahtevo. Žeton velja eno uro; shranite ga v predpomnilnik, sicer boste naleteli na omejitev na IP-naslov pri končni točki za žetone.
• Ustvarjanje novega ključa idempotentnosti ob vsakem ponovnem poskusu — prav ta scenarij ustvarja podvojene račune.
• Klicanje iz JavaScripta v brskalniku. CORS blokira vsak izvor, skrivnost pa bi bila tako ali tako izpostavljena.
• Oddaja v nacionalni sistem e-računov brez predpregleda (v Romuniji CIUS-RO). Napačne oddaje ni mogoče umakniti.
• Klicanje /efactura/submissions/{id}/refresh več kot 10-krat na minuto — ta kvota je skupna s submit.
• Izdajanje, preden je profil podjetja dopolnjen in obstaja aktiven davčni niz.