Izdajanje računov prek API

POST /invoices z Idempotency-Key, DDV v odstotkih, poleg tega seznam, storno in oznaka plačano.

Prvi račun v 6 korakih

Pošljite POST /v1/invoices z objektom buyer in vsaj eno postavko v lines.
Dodajte glavo Idempotency-Key — je obvezna, en ključ na logično operacijo.
vat_rate pošljite kot odstotek (21), unit_price pa kot NETO ceno na enoto.
Odgovor 201 vsebuje id, number, series, zneske net/vat/gross in metadata, ki ste jih poslali.
Dokument prenesite z GET /v1/invoices/{id}/pdf, XML UBL pa z GET /v1/invoices/{id}/xml.

Vse končne točke

Metoda	Končna točka	Scope	Idempotency-Key	Zahtev / minuto
POST	/invoices Izdaj račun ali predračun	invoices:write	obvezno	30
GET	/invoices Seznam računov (paginacija s kazalcem)	invoices:read	—	120
POST	/invoices/preview-totals Izračunaj vsote, ne da bi kaj ustvaril	invoices:read	—	120
GET	/invoices/{invoice_id} Pridobi en račun	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Prenesi PDF računa	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Izdaj dobropis, ki razveljavi ta račun	invoices:write	obvezno	30
POST	/invoices/{invoice_id}/payments Označi račun kot plačan	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Označi račun kot neplačan	invoices:write	—	30

Kaj 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 s kazalcem: sledite next_cursor, dokler has_more ni 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 dobi LASTNO fiskalno številko; številka izvirnika se nikoli ne uporabi znova.

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

# Razveljavi
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

Napake

Stanje	Tip	Koda
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Pogoste napake

Seznam uporablja ostranjevanje s kazalcem: sledite next_cursor, dokler has_more ni false. Filtri vključujejo status, document_kind, buyer_tax_id, issued_from, issued_to in q.
Storno je POST /v1/invoices/{id}/storno in dobi lastno davčno številko — prvotna številka se nikoli ne uporabi znova.
Predračun (document_kind proforma) ne porabi davčne številke in ga ni mogoče oddati v nacionalni sistem e-računov.
metadata se vrne pri branju: vanj vpišite ID svojega naročila in ne potrebujete več ločene tabele preslikav.
POST /v1/invoices/preview-totals izvede enak izračun brez stranskih učinkov — priročno za prikaz zneskov v vaši lastni košarici.

Vprašanja in odgovori za razvijalce

Koliko postavk ima lahko en račun?

Od 1 do 400. description je omejen na 1024 znakov, quantity pa mora biti strogo pozitiven.

Kaj se zgodi, če isto zahtevo po preteku časovne omejitve pošljem znova?

Z istim Idempotency-Key dobite prvotni račun in glavo Idempotency-Replayed: true. Drug dokument se ne izda.

Kako račun označim kot plačan?

POST /v1/invoices/{id}/payments ga označi kot plačanega, DELETE na isti poti pa to razveljavi. Oba potrebujeta obseg invoices:write.

Glejte tudi