Издаване на фактури през 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 или XML във формат UBL с 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.

Вижте също