Издавање фактури преку API

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

Првата фактура во 6 чекори

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

Сите крајни точки

Метод	Крајна точка	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

Што е 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
# Странично листање по курсор: следете го 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. Филтрите вклучуваат status, document_kind, buyer_tax_id, issued_from, issued_to и q.
Storno е POST /v1/invoices/{id}/storno и добива свој фискален број — оригиналниот број никогаш не се повторно користи.
Проформата (document_kind proforma) не троши фискален број и не може да се поднесе во националниот систем за е-фактурирање.
metadata се враќа при читање: ставете го бројот на вашата нарачка таму и не ви треба посебна табела за мапирање.
POST /v1/invoices/preview-totals ја извршува истата пресметка без странични ефекти — корисно за прикажување вкупни износи во вашата сопствена кошничка.

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

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

Од 1 до 400. description е ограничен на 1024 знаци, а quantity мора да биде строго позитивен.

Што се случува ако го испратам истото барање повторно по истек на времето?

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

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

POST /v1/invoices/{id}/payments ја означува како платена, а DELETE на истата патека ја поништува. И двете бараат scope invoices:write.

Видете исто така