Издавање фактура преко API-ја

POST /invoices са Idempotency-Key, ПДВ у процентима, уз листу, сторно и означавање плаћеног.

Прва фактура у 6 корака

Пошаљите POST /v1/invoices са објектом купац и бар једном ставком у редови.
Додајте заглавље Idempotency-Key — обавезно је, један кључ по логичкој операцији.
vat_rate пошаљите као проценат (21), а unit_price као НЕТО јединичну цену.
Одговор 201 садржи id, број, серија, износе net/vat/gross и метаподаци које сте послали.
Документ преузмите са GET /v1/invoices/{id}/pdf, а UBL XML са GET /v1/invoices/{id}/xml.

Сви endpoint-и

Метода	Endpoint	Scope	Idempotency-Key	Захтева / минут
POST	/invoices Издај фактуру или профактуру	invoices:write	обавезно	30
GET	/invoices Листа фактура (пагинација курсором)	invoices:read	—	120
POST	/invoices/preview-totals Израчунај збирове без стварања ичега	invoices:read	—	120
GET	/invoices/{invoice_id} Преузми једну фактуру	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Преузми PDF фактуре	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Издај кредитну напомену која поништава ову фактуру	invoices:write	обавезно	30
POST	/invoices/{invoice_id}/payments Означи фактуру као плаћену	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Означи фактуру као неплаћену	invoices:write	—	30

Шта је 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
# Пагинација курсором: пратите next_cursor док has_more не постане 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'

# Кредитна напомена добија СОПСТВЕН фискални број; број оригинала се никад не користи поново.

bash
# Означи као плаћену
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Поништи
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

Грешке

Статус	Тип	Код
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Честе грешке

Листа се страничи курсором: пратите next_cursor док has_more не постане false. Филтери обухватају статус, document_kind, buyer_tax_id, issued_from, issued_to и q.
Сторно је POST /v1/invoices/{id}/storno и добија сопствени фискални број — првобитни број се никада поново не користи.
Предрачун (document_kind proforma) не троши фискални број и не може се предати у национални систем е-фактурисања.
метаподаци се враћа при читању: упишите ту ID своје поруџбине и више вам не треба засебна табела мапирања.
POST /v1/invoices/preview-totals изводи исти обрачун без споредних ефеката — згодно за приказ износа у сопственој корпи.

Питања и одговори за програмере

Колико ставки може да има једна фактура?

Између 1 и 400. опис је ограничен на 1024 знака, а количина мора бити строго позитиван.

Шта се дешава ако исти захтев поново пошаљем после истека времена?

Са истим Idempotency-Key добијате првобитну фактуру и заглавље Idempotency-Replayed: true. Други документ се не издаје.

Како да означим фактуру као плаћену?

POST /v1/invoices/{id}/payments је означава као плаћену, а DELETE на истој путањи то поништава. Оба захтевају опсег invoices:write.

Види такође