4invoices fejlesztői API

• A 4invoices nyilvános API-ja REST HTTPS-en keresztül: JSON a bemenet és JSON a kimenet.
• Egyetlen éles host van: https://api.4invoices.net/v1. Külön teszthost nincs.
• Az OpenAPI 3.1 specifikáció nyilvános és kulcs nélkül elérhető — importálja közvetlenül a Postmanbe vagy egy kliensgenerátorba.
• Minden válasz tartalmaz egy X-Request-Id fejlécet; adja meg, amikor a támogatáshoz fordul.
• Minden fiskális írás idempotens: egy időtúllépés utáni újrapróbálás soha nem állít ki második bizonylatot.

• A nemzeti e-számlázási rendszer teljes folyamata az API-n keresztül (Romániában: ANAF e-Factura): előellenőrzés, beküldés, követés, aláírt válasz és bejövő postafiók. Egyetlen román versenytárs sem kínál ilyet.
• A SmartBill-nek egyetlen végpontja sincs a nemzeti e-számlázási rendszerbe történő beküldéshez (ANAF, Romániában) — a beküldés csak a felületen elérhető fiókbeállítás —, és számlalistázó végpontja sincs egyáltalán.
• Az Oblio ügyfeleket és termékeket csak egy bizonylat kiállításának mellékhatásaként tud létrehozni, nem önálló erőforrásként.
• UBL / CIUS-RO XML (Románia) előállítása beküldés nélkül: a jogi bizonylatot fájlként kapja meg anélkül, hogy a nemzeti e-számlázási rendszerhez nyúlna.
• Idempotencia a fiskális írásoknál: egy időtúllépés utáni újrapróbálás nem hoz létre második számlát, és nem használ fel második sorszámot.
• Programozottan olvasható postafiók a beszállítói számlákhoz — az automatizált egyeztetés alapja.

1. Hozzon létre hitelesítő adatot a panelen, a Számlázás → Beállítások → API-hozzáférés alatt, és másolja ki a client_secret értéket — csak egyszer jelenik meg.
2. Töltse ki a cégprofilt, és aktiváljon legalább egy fiscale típusú számlatömböt, különben a kiállítás issuer_profile_incomplete vagy no_series_configured hibát ad.
3. Váltsa a hitelesítő adatot tokenre: POST /v1/auth/token grant_type client_credentials értékkel. A token egy óráig él — gyorsítótárazza, ne kérjen újat minden híváshoz.
4. Állítsa ki a számlát: POST /v1/invoices Idempotency-Key fejléccel és vat_rate százalékként (21, nem 0.21).
5. Futtassa az előellenőrzést (Romániában: CIUS-RO) a POST /v1/invoices/{id}/efactura/validate hívással, majd küldje a nemzeti e-számlázási rendszerbe (Romániában: ANAF) a POST /v1/invoices/{id}/efactura/submit hívással.
6. Kövesse az állapotot a GET /v1/efactura/submissions/{id} hívással, amíg accepted vagy rejected nem lesz.

bash
# 1 — token (1 óra, gyorsítótárazza)
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 — állítsa ki a számlát (Idempotency-Key KÖTELEZŐ)
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}",
    # Egy kulcs minden LOGIKAI műveletre — újrapróbálkozáskor használja újra, soha ne generálja újra.
    "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}],   # százalék, nem 0.21
    "currency": "RON",
}, timeout=60).json()

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

• A folyamat client_credentials: a client_id + client_secret párost egy Bearer access_token-re cseréli.
• A token 3600 másodperc után lejár. Lejárat előtt frissítse, ne minden hívásnál — a POST /auth/token saját, IP-címenkénti korláttal rendelkezik.
• A client_secret csak hash formában tárolódik, és nem állítható vissza. Ha elveszíti, új hitelesítő adatot hoz létre, a régit pedig visszavonja.
• Kizárólag szerver–szerver kommunikáció. A CORS egyetlen böngészős origint sem enged: az oldal JavaScriptjéből a titok kiszivárogna a látogatóhoz.
• A jogosultsági köröket (scopes) hitelesítő adatonként kell megadni. Minden rendszerhez adjon ki külön hitelesítő adatot, és mindegyiknek csak a szükséges minimális jogosultságot adja meg.

Számlázás → Beállítások → API-hozzáférés

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
// Gyorsítótárazza a tokent; ne kérjen újat minden kéréshez.
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;
}

• A vat_rate SZÁZALÉK: a 21 azt jelenti, 21%.
• A (0, 1] tartományba eső értékeket elutasítjuk — a 0.19 tört, az 1 pedig nem egyértelmű 1% és 100% között.
• A 0 érvényes, és adómentességet vagy fordított adózást jelent; a jogszabályi hivatkozást a notes mezőbe írja.
• A unit_price a NETTÓ egységár, ha a kiállító ÁFA-alany.
• Véglegesítés előtt szüksége van a végösszegekre? A POST /v1/invoices/preview-totals ugyanazt a számítást végzi el fiskális sorszám felhasználása nélkül.

• Az Idempotency-Key fejléc KÖTELEZŐ a POST /invoices, a POST /invoices/{id}/storno és a POST /invoices/{id}/efactura/submit hívásoknál.
• A kulcsokat 24 óráig tároljuk. Ugyanazzal a kulccsal és ugyanazzal a törzzsel ismételt kérés az eredeti eredményt adja vissza, és beállítja az Idempotency-Replayed: true fejlécet.
• Ugyanaz a kulcs eltérő törzzsel 409 idempotency_key_reuse választ ad — egy már kiállított fiskális bizonylatot soha nem írunk felül.
• Egy kulcs LOGIKAI műveletenként, nem HTTP-próbálkozásonként: order-10457-invoice, nem pedig minden újrapróbálásnál új UUID.
• Az ok jogi, nem technikai: egy felhasznált fiskális sorszámot és egy a nemzeti e-számlázási rendszerbe benyújtott számlát nem lehet visszavonni.

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

• A valódi különbség: a nemzeti e-számlázási rendszer teljes folyamata (Romániában: ANAF e-Factura) az API-n keresztül fut, nem csak a bizonylat előállítása.
• A POST /invoices/{id}/efactura/validate lefuttatja az előellenőrzést (Romániában: CIUS-RO), és pontosan azokat a mezőket adja vissza, amelyeket a nemzeti e-számlázási rendszer elutasítana, anélkül hogy bármit elküldene.
• A GET /invoices/{id}/xml beküldés nélkül előállítja az UBL / CIUS-RO XML-t (Románia) — hasznos a saját archívumhoz vagy belső audithoz.
• A POST /invoices/{id}/efactura/submit benyújtja a számlát a nemzeti e-számlázási rendszerbe (Romániában: az ANAF SPV-jébe). Ez visszafordíthatatlan: ugyanannak a számlának egy második példányát már nem lehet visszavonni.
• Az életciklus normalizált: not_sent → validating → queued → sent → processing → accepted | rejected | error. Az accepted jogilag érvényes továbbítást jelent; az error a mi oldalunkon fellépő átviteli hiba, és biztonságosan újrapróbálható.
• A GET /efactura/submissions/{id}/download letölti az ANAF (Románia) aláírt válaszát tartalmazó archívumot.
• A bejövő oldal is létezik: a POST /efactura/inbox/sync lekéri az új SPV-üzeneteket (Románia), a GET /efactura/inbox pedig listázza a beszállítók által Önnek küldött számlákat.

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)

• Minden 4xx és 5xx ugyanazt a borítékot használja: { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
• A type a durva kategória, amely alapján elágazik a logika („újrapróbálhatom?”), a code pedig a stabil ok, amelyet a saját rendszerére képez le.
• A param a hibás mező pontokkal tagolt útvonala, például lines.0.vat_rate.
• Az errors[] akkor jelenik meg, ha egyetlen kérésben egynél több mezővel van probléma.
• A request_id a mi oldalunkon naplózásra kerül. Adja meg minden támogatási jegyben — pontosan azonosítja a kérést.
• 404-et adunk vissza egy másik tenanthoz tartozó id esetén is: soha nem erősítjük meg, hogy más adatai léteznek.

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

• A korlátok hitelesítő adatonként és percenként értendők: olvasásra 120, írásra 30, az e-számlázási műveletekre (submit, refresh, inbox/sync) 10.
• Az X-RateLimit-Limit, X-RateLimit-Remaining és X-RateLimit-Reset MINDEN válaszban megjelenik, a 429-et is beleértve.
• A 429 Retry-After értéket is tartalmaz másodpercben. Tartsa be; ne próbálkozzon újra szoros ciklusban.
• A 10/perc keret azért létezik, mert Romániában maga az ANAF is nagyjából percenként egy üzenetlista-hívást enged CIF-enként.
• A /efactura/inbox/sync hívást cronból futtassa, ne agresszív lekérdezéssel.
• Magasabb korlátokra van szüksége? Írjon a Kapcsolat oldalon keresztül, megadva a várható napi volument.

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
// Tartsa be a Retry-After értéket; a 429-en kívüli 4xx hibát soha ne ismételje meg.
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;
}

// Egy írási újrapróbálkozásnál UGYANAZT az Idempotency-Key-t KELL használni, különben kiállít
// egy második fiskális bizonylatot.

Minden témának saját oldala van a hozzá tartozó végpontokkal, példákkal és hibákkal.

• Hitelesítés a 4invoices API-banA client_id és client_secret párost egy órás Bearer tokenre váltja, kizárólag szerver-szerver módon.
• Számlakiállítás az API-nPOST /invoices Idempotency-Key fejléccel, áfa százalékban, továbbá listázás, sztornó és fizetettre állítás.
• Vevők és ANAF nyilvántartás-ellenőrzés (Románia)tax_id alapján deduplikált beszúrás vagy frissítés (upsert) és ANAF nyilvántartás-lekérdezés (Románia), hogy az e-számlát ne utasítsák el.
• ANAF e-Factura (Románia) az API-nRomániában: CIUS-RO előellenőrzés, SPV-beadás, normalizált státusz, aláírt válasz és beérkező szállítói számlák.
• Számlatömbök az API-banAktív fiscale típusú számlatömb nélkül a kiállítás 409 no_series_configured hibát ad.
• Hibakódok és a hibaborítékEgyetlen forma minden útvonalon: type, code, message, param, doc_url, request_id és errors.
• Kéréslimitek és újrapróbálkozásHitelesítő adatonként percenként 120 olvasás, 30 írás és 10 e-számlázási művelet, X-RateLimit-* fejlécekkel.

• Az ÁFA törtként (0.19) vagy 1-ként való küldése. Mindkettőt elutasítjuk; küldjön 19-et vagy 21-et.
• Token kérése minden kéréshez. A token egy óráig érvényes; gyorsítótárazza, különben beleütközik a token-végpont IP-címenkénti korlátjába.
• Új idempotenciakulcs generálása minden újrapróbálásnál — pontosan ez a forgatókönyv hoz létre duplikált számlákat.
• Hívás böngészős JavaScriptből. A CORS minden origint blokkol, és a titok amúgy is kiszivárogna.
• Benyújtás a nemzeti e-számlázási rendszerbe előellenőrzés (Romániában: CIUS-RO) nélkül. Egy hibás beküldést nem lehet visszavonni.
• A /efactura/submissions/{id}/refresh percenként 10-nél többszöri lekérdezése — ez a keret közös a submit hívással.
• Kiállítás, mielőtt a cégprofil teljes lenne, és létezne aktív fiskális sorozat.