Vystavovanie faktúr cez API

POST /invoices s Idempotency-Key, DPH v percentách, plus zoznam, storno a označenie zaplatené.

Prvá faktúra v 6 krokoch

Pošlite POST /v1/invoices s objektom buyer a aspoň jednou položkou v lines.
Pridajte hlavičku Idempotency-Key — je povinná, jeden kľúč na logickú operáciu.
vat_rate posielajte v percentách (21) a unit_price ako jednotkovú cenu BEZ DPH.
Odpoveď 201 obsahuje id, number, series, sumy net/vat/gross a metadata, ktoré ste poslali.
Doklad stiahnete cez GET /v1/invoices/{id}/pdf alebo XML UBL cez GET /v1/invoices/{id}/xml.

Všetky endpointy

Metóda	Endpoint	Scope	Idempotency-Key	Požiadaviek / minútu
POST	/invoices Vystaviť faktúru alebo proformu	invoices:write	povinné	30
GET	/invoices Zoznam faktúr (stránkovanie kurzorom)	invoices:read	—	120
POST	/invoices/preview-totals Vypočítať súčty bez vytvorenia čohokoľvek	invoices:read	—	120
GET	/invoices/{invoice_id} Získať jednu faktúru	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Stiahnuť PDF faktúry	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Vystaviť dobropis, ktorý túto faktúru stornuje	invoices:write	povinné	30
POST	/invoices/{invoice_id}/payments Označiť faktúru ako uhradenú	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Označiť faktúru ako neuhradenú	invoices:write	—	30

Čo je 4invoices API

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

bash
# Stránkovanie kurzorom: sledujte next_cursor, kým has_more nebude false.
curl -sS "https://api.4invoices.net/v1/invoices?limit=50&status=issued&issued_from=2026-07-01" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# → {"object":"list","data":[...],"has_more":true,"next_cursor":"inv_01J..."}

curl -sS "https://api.4invoices.net/v1/invoices?limit=50&cursor=inv_01J..." \
  -H "Authorization: Bearer $ACCESS_TOKEN"

bash
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/storno \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: storno-inv_01J7ABC-1'

# Dobropis dostane VLASTNÉ fiškálne číslo; číslo pôvodnej faktúry sa nikdy nepoužije znova.

bash
# Označiť ako uhradenú
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Vrátiť späť
curl -sS -X DELETE https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

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

Chyby

Stav	Typ	Kód
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Časté chyby

Výpis je založený na kurzore: pokračujte podľa next_cursor, kým has_more nie je false. Filtre zahŕňajú status, document_kind, buyer_tax_id, issued_from, issued_to a q.
Storno je POST /v1/invoices/{id}/storno a dostane vlastné fiškálne číslo — pôvodné číslo sa nikdy znovu nepoužije.
Zálohová faktúra (document_kind proforma) nespotrebúva fiškálne číslo a nemožno ju podať do národného systému elektronickej fakturácie.
metadata sa vracajú pri čítaní: uložte tam id objednávky a samostatnú mapovaciu tabuľku už nepotrebujete.
POST /v1/invoices/preview-totals vykoná rovnaký výpočet bez vedľajších účinkov — praktické na zobrazenie súm vo vlastnom košíku.

Otázky a odpovede pre vývojárov

Koľko položiek môže mať jedna faktúra?

Od 1 do 400. description je obmedzený na 1024 znakov a quantity musí byť striktne kladné.

Čo sa stane, ak po vypršaní časového limitu pošlem rovnakú požiadavku znova?

S rovnakým Idempotency-Key dostanete pôvodnú faktúru a hlavičku Idempotency-Replayed: true. Druhý doklad sa nevystaví.

Ako označím faktúru ako uhradenú?

POST /v1/invoices/{id}/payments ju označí ako uhradenú a DELETE na tej istej ceste to vráti späť. Obe vyžadujú rozsah invoices:write.

Pozrite tiež