Sąskaitų išrašymas per API

POST /invoices su Idempotency-Key, PVM procentais, taip pat sąrašas, storno ir pažymėjimas apmokėta.

Pirmoji sąskaita per 6 žingsnius

Siųskite POST /v1/invoices su buyer objektu ir bent vienu įrašu lines.
Pridėkite Idempotency-Key antraštę — ji privaloma, po vieną raktą kiekvienai loginei operacijai.
Siųskite vat_rate kaip procentą (21) ir unit_price kaip NETO vieneto kainą.
201 atsakyme yra id, number, series, sumos net/vat/gross ir jūsų pateikti metaduomenys.
Gaukite dokumentą su GET /v1/invoices/{id}/pdf arba UBL XML su GET /v1/invoices/{id}/xml.

Visi galiniai taškai

Metodas	Galinis taškas	Scope	Idempotency-Key	Užklausų / min.
POST	/invoices Išrašyti sąskaitą arba proforma sąskaitą	invoices:write	privaloma	30
GET	/invoices Išvardyti sąskaitas (puslapiavimas žymekliu)	invoices:read	—	120
POST	/invoices/preview-totals Apskaičiuoti sumas nieko nekuriant	invoices:read	—	120
GET	/invoices/{invoice_id} Gauti vieną sąskaitą	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Atsisiųsti sąskaitos PDF	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Išrašyti kreditinę sąskaitą, panaikinančią šią sąskaitą	invoices:write	privaloma	30
POST	/invoices/{invoice_id}/payments Pažymėti sąskaitą apmokėta	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Pažymėti sąskaitą neapmokėta	invoices:write	—	30

Kas yra 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
# Puslapiavimas žymekliu: sekite next_cursor, kol has_more taps 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'

# Kreditinė sąskaita gauna SAVO fiskalinį numerį; pradinis numeris niekada nenaudojamas pakartotinai.

bash
# Pažymėti apmokėta
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Atšaukti
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

Klaidos

Būsena	Tipas	Kodas
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Dažniausios klaidos

Sąrašas grindžiamas žymekliu: sekite next_cursor, kol has_more taps false. Filtrai: status, document_kind, buyer_tax_id, issued_from, issued_to ir q.
Storno yra POST /v1/invoices/{id}/storno ir gauna savo fiskalinį numerį — pradinis numeris niekada nenaudojamas pakartotinai.
Proforma sąskaita (document_kind proforma) nesunaudoja fiskalinio numerio ir negali būti pateikta į nacionalinę e. sąskaitų faktūrų sistemą.
metadata grąžinama skaitant: įrašykite čia savo užsakymo ID, ir atskiros atitikmenų lentelės nebereikės.
POST /v1/invoices/preview-totals atlieka tą patį skaičiavimą be šalutinių efektų — patogu rodyti sumas savo krepšelyje.

Kūrėjų klausimai ir atsakymai

Kiek eilučių gali turėti viena sąskaita?

Nuo 1 iki 400. description ribojamas 1024 simboliais, o quantity turi būti griežtai teigiamas.

Kas nutinka, jei po nutrūkimo siunčiu tą pačią užklausą dar kartą?

Su tuo pačiu Idempotency-Key gausite pradinę sąskaitą ir antraštę Idempotency-Replayed: true. Naujas dokumentas neišrašomas.

Kaip pažymėti sąskaitą apmokėta?

POST /v1/invoices/{id}/payments pažymi ją apmokėta, o DELETE tuo pačiu keliu tai atšaukia. Abiems reikalingas scope invoices:write.

Taip pat žr.