Виставлення рахунків через 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.

Усі ендпоїнти

Метод	Ендпоїнт	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. Фільтри включають статус, 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.

Дивіться також