Izdavanje faktura preko API-ja

POST /invoices sa Idempotency-Key, PDV kao procenti, plus listanje, storno i označavanje plaćenim.

Vaša prva faktura u 6 koraka

Pošaljite POST /v1/invoices sa objektom buyer i bar jednom stavkom u lines.
Dodajte zaglavlje Idempotency-Key — obavezno je, jedan ključ po logičkoj operaciji.
Šaljite vat_rate kao procenat (21), a unit_price kao NETO jediničnu cijenu.
Odgovor 201 nosi id, number, series, ukupne iznose net/vat/gross i metapodatke koje ste poslali.
Preuzmite dokument sa GET /v1/invoices/{id}/pdf ili UBL XML sa GET /v1/invoices/{id}/xml.

Sve krajnje tačke

Metod	Krajnja tačka	Opseg	Idempotency-Key	Zahtjeva / minut
POST	/invoices Izdaje fakturu ili predračun	invoices:write	obavezno	30
GET	/invoices Listanje faktura (paginacija po kursoru)	invoices:read	—	120
POST	/invoices/preview-totals Računa ukupne iznose bez kreiranja bilo čega	invoices:read	—	120
GET	/invoices/{invoice_id} Dohvata jednu fakturu	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Preuzima PDF fakture	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Izdaje knjižno odobrenje (storno) koje poništava ovu fakturu	invoices:write	obavezno	30
POST	/invoices/{invoice_id}/payments Označava fakturu kao plaćenu	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Označava fakturu kao neplaćenu	invoices:write	—	30

Šta je API 4invoices

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
# Paginacija po kursoru: pratite next_cursor dok has_more ne bude 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'

# Storno dobija SVOJ fiskalni broj; originalni broj se nikada ne koristi ponovo.

bash
# Označi kao plaćeno
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Poništi
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

Greške

Status	Tip	Kod
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Česte greške

Listanje je po kursoru: pratite next_cursor dok has_more ne bude false. Filteri uključuju status, document_kind, buyer_tax_id, issued_from, issued_to i q.
Storno je POST /v1/invoices/{id}/storno i dobija sopstveni fiskalni broj — originalni broj se nikada ne koristi ponovo.
Predračun (document_kind proforma) ne troši fiskalni broj i ne može se podnijeti u nacionalni sistem e-fakturisanja.
metadata se vraća pri čitanjima: upišite tu ID svoje narudžbine i ne treba vam posebna tabela preslikavanja.
POST /v1/invoices/preview-totals radi istu aritmetiku bez nuspojava — zgodno za prikaz ukupnih iznosa u vašoj korpi.

Pitanja i odgovori za programere

Koliko stavki jedna faktura može imati?

Između 1 i 400. description je ograničen na 1024 znaka, a quantity mora biti strogo pozitivan.

Šta se dešava ako ponovo pošaljem isti zahtjev nakon isteka vremena?

Sa istim Idempotency-Key dobijate originalnu fakturu i zaglavlje Idempotency-Replayed: true. Ne izdaje se drugi dokument.

Kako fakturu označavam kao plaćenu?

POST /v1/invoices/{id}/payments je označava kao plaćenu, a DELETE na istoj putanji to poništava. Oba zahtijevaju opseg invoices:write.

Vidi također