Laskujen myöntäminen API:n kautta

POST /invoices Idempotency-Keyllä, ALV prosentteina, sekä listaus, hyvitys ja merkintä maksetuksi.

Ensimmäinen lasku 6 vaiheessa

Lähetä POST /v1/invoices, jossa on buyer-objekti ja vähintään yksi merkintä lines-kentässä.
Lisää Idempotency-Key-otsikko — se on pakollinen, yksi avain loogista toimintoa kohden.
Lähetä vat_rate prosenttina (21) ja unit_price NETTO-yksikköhintana.
201-vastaus sisältää id:n, numeron, sarjan, summat net/vat/gross ja lähettämäsi metadatan.
Hae asiakirja kutsulla GET /v1/invoices/{id}/pdf tai UBL-XML kutsulla GET /v1/invoices/{id}/xml.

Kaikki päätepisteet

Metodi	Päätepiste	Scope	Idempotency-Key	Pyyntöjä / minuutti
POST	/invoices Myönnä lasku tai proformalasku	invoices:write	pakollinen	30
GET	/invoices Listaa laskut (kursoripohjainen sivutus)	invoices:read	—	120
POST	/invoices/preview-totals Laske summat luomatta mitään	invoices:read	—	120
GET	/invoices/{invoice_id} Hae yksi lasku	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Lataa laskun PDF	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Myönnä hyvityslasku, joka peruu tämän laskun	invoices:write	pakollinen	30
POST	/invoices/{invoice_id}/payments Merkitse lasku maksetuksi	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Merkitse lasku maksamattomaksi	invoices:write	—	30

Mitä 4invoices-API on

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
# Kursoripohjainen sivutus: seuraa next_cursor-arvoa, kunnes 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'

# Hyvityslasku saa OMAN verotuksellisen numeronsa; alkuperäisen numeroa ei koskaan käytetä uudelleen.

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

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

Virheet

Tila	Tyyppi	Koodi
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Yleiset virheet

Listaus perustuu kursoriin: seuraa next_cursor-arvoa, kunnes has_more on false. Suodattimet: status, document_kind, buyer_tax_id, issued_from, issued_to ja q.
Hyvitys on POST /v1/invoices/{id}/storno ja saa oman verotuksellisen numeronsa — alkuperäisen numeroa ei koskaan käytetä uudelleen.
Proformalasku (document_kind proforma) ei kuluta verotuksellista numeroa eikä sitä voi kirjata kansalliseen sähkölaskujärjestelmään.
metadata palautetaan lukuissa: laita sinne tilaustunnuksesi, niin erillistä vastaavuustaulua ei tarvita.
POST /v1/invoices/preview-totals suorittaa saman laskennan ilman sivuvaikutuksia — hyvä summien näyttämiseen omassa ostoskorissasi.

Kehittäjien kysymykset ja vastaukset

Montako riviä yhdessä laskussa voi olla?

1–400. description on rajattu 1024 merkkiin, ja quantity on oltava ehdottomasti positiivinen.

Mitä tapahtuu, jos lähetän saman pyynnön uudelleen aikakatkaisun jälkeen?

Samalla Idempotency-Keyllä saat alkuperäisen laskun sekä otsikon Idempotency-Replayed: true. Toista asiakirjaa ei luoda.

Miten merkitsen laskun maksetuksi?

POST /v1/invoices/{id}/payments merkitsee sen maksetuksi, ja DELETE samaan polkuun peruu merkinnän. Molemmat vaativat scopen invoices:write.

Katso myös