Arvete väljastamine API kaudu

POST /invoices koos Idempotency-Key'ga, käibemaks protsentidena, plus loend, storno ja märgistamine tasutuks.

Esimene arve 6 sammuga

Saada POST /v1/invoices koos buyer-objektiga ja vähemalt ühe kirjega lines-s.
Lisa päis Idempotency-Key — see on kohustuslik, üks võti loogilise toimingu kohta.
Saada vat_rate protsendina (21) ja unit_price NETO ühikuhinnana.
201 vastus sisaldab id, number, series, summasid net/vat/gross ja sinu saadetud metaandmeid.
Too dokument GET /v1/invoices/{id}/pdf või UBL XML GET /v1/invoices/{id}/xml abil.

Kõik lõpp-punktid

Meetod	Lõpp-punkt	Scope	Idempotency-Key	Päringuid / minut
POST	/invoices Väljasta arve või proformaarve	invoices:write	kohustuslik	30
GET	/invoices Loetle arved (kursoripõhine lehekülgimine)	invoices:read	—	120
POST	/invoices/preview-totals Arvuta summad ilma midagi loomata	invoices:read	—	120
GET	/invoices/{invoice_id} Too üks arve	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Laadi arve PDF alla	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Väljasta kreeditarve, mis tühistab selle arve	invoices:write	kohustuslik	30
POST	/invoices/{invoice_id}/payments Märgi arve tasutuks	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Märgi arve tasumata olevaks	invoices:write	—	30

Mis on 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
# Kursoripõhine lehekülgimine: jälgi next_cursor'it, kuni has_more on 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'

# Kreeditarve saab OMA fiskaalnumbri; algset numbrit ei kasutata kunagi uuesti.

bash
# Märgi tasutuks
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Võta tagasi
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

Vead

Staatus	Tüüp	Kood
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Levinud vead

Loend põhineb kursoril: jälgi next_cursor'it, kuni has_more on false. Filtrid: status, document_kind, buyer_tax_id, issued_from, issued_to ja q.
Storno on POST /v1/invoices/{id}/storno ja saab oma fiskaalnumbri — algset numbrit ei kasutata kunagi uuesti.
Proformaarve (document_kind proforma) ei kuluta fiskaalnumbrit ega saa riigi e-arvete süsteemi esitada.
metadata tagastatakse lugemistel: pane sinna oma tellimuse ID, siis pole eraldi vastavustabelit vaja.
POST /v1/invoices/preview-totals teeb sama arvutuse ilma kõrvalmõjudeta — mugav summade näitamiseks oma ostukorvis.

Arendajate küsimused ja vastused

Mitu rida võib ühel arvel olla?

1–400. description on piiratud 1024 märgiga ja quantity peab olema rangelt positiivne.

Mis juhtub, kui saadan pärast aegumist sama päringu uuesti?

Sama Idempotency-Key'ga saad algse arve ja päise Idempotency-Replayed: true. Teist dokumenti ei looda.

Kuidas arve tasutuks märkida?

POST /v1/invoices/{id}/payments märgib selle tasutuks ja sama tee DELETE tühistab selle. Mõlemad nõuavad scope'i invoices:write.

Vaata ka