Wystawianie faktur przez API

POST /invoices z Idempotency-Key, VAT w procentach, plus lista, korekta i oznaczenie jako zapłacona.

Pierwsza faktura w 6 krokach

Wyślij POST /v1/invoices z obiektem buyer i co najmniej jedną pozycją w lines.
Dodaj nagłówek Idempotency-Key — jest wymagany, jeden klucz na operację logiczną.
Wysyłaj vat_rate w procentach (21), a unit_price jako cenę jednostkową NETTO.
Odpowiedź 201 zawiera id, number, series, sumy net/vat/gross oraz przesłane przez Ciebie metadata.
Pobierz dokument przez GET /v1/invoices/{id}/pdf lub XML UBL przez GET /v1/invoices/{id}/xml.

Wszystkie endpointy

Metoda	Endpoint	Scope	Idempotency-Key	Żądania / minutę
POST	/invoices Wystaw fakturę lub proformę	invoices:write	wymagane	30
GET	/invoices Wyświetl faktury (stronicowanie kursorem)	invoices:read	—	120
POST	/invoices/preview-totals Oblicz sumy bez tworzenia czegokolwiek	invoices:read	—	120
GET	/invoices/{invoice_id} Pobierz jedną fakturę	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Pobierz PDF faktury	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Wystaw fakturę korygującą anulującą tę fakturę	invoices:write	wymagane	30
POST	/invoices/{invoice_id}/payments Oznacz fakturę jako opłaconą	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Oznacz fakturę jako nieopłaconą	invoices:write	—	30

Czym jest 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
# Paginacja kursorem: idź za next_cursor, aż has_more będzie 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'

# Faktura korygująca dostaje WŁASNY numer fiskalny; numer oryginału nigdy nie jest ponownie używany.

bash
# Oznacz jako opłaconą
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

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

Błędy

Status	Typ	Kod
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Częste błędy

Listowanie opiera się na kursorze: podążaj za next_cursor, aż has_more będzie false. Filtry obejmują status, document_kind, buyer_tax_id, issued_from, issued_to i q.
Storno to POST /v1/invoices/{id}/storno i otrzymuje własny numer fiskalny — pierwotny numer nigdy nie jest używany ponownie.
Proforma (document_kind proforma) nie zużywa numeru fiskalnego i nie może zostać złożona w krajowym systemie e-fakturowania.
metadata jest zwracane przy odczytach: umieść tam id zamówienia, a osobna tabela mapowań przestanie być potrzebna.
POST /v1/invoices/preview-totals wykonuje te same obliczenia bez skutków ubocznych — wygodne do pokazywania sum we własnym koszyku.

Pytania i odpowiedzi dla programistów

Ile pozycji może mieć jedna faktura?

Od 1 do 400. description jest ograniczony do 1024 znaków, a quantity musi być ściśle dodatnie.

Co się stanie, jeśli po przekroczeniu limitu czasu wyślę to samo żądanie ponownie?

Z tym samym Idempotency-Key otrzymasz pierwotną fakturę oraz nagłówek Idempotency-Replayed: true. Drugi dokument nie zostanie wystawiony.

Jak oznaczyć fakturę jako opłaconą?

POST /v1/invoices/{id}/payments oznacza ją jako opłaconą, a DELETE na tej samej ścieżce cofa oznaczenie. Oba wymagają zakresu invoices:write.

Zobacz też