Számlakiállítás az API-n

POST /invoices Idempotency-Key fejléccel, áfa százalékban, továbbá listázás, sztornó és fizetettre állítás.

Az első számla 6 lépésben

Küldjön POST /v1/invoices kérést egy buyer objektummal és legalább egy tétellel a lines mezőben.
Adja hozzá az Idempotency-Key fejlécet — kötelező, logikai műveletenként egy kulcs.
A vat_rate értékét százalékban (21), a unit_price értékét NETTÓ egységárként küldje.
A 201-es válasz tartalmazza az id, number, series értékeket, a net/vat/gross végösszegeket és az Ön által küldött metadata adatokat.
A bizonylatot a GET /v1/invoices/{id}/pdf, az UBL XML-t a GET /v1/invoices/{id}/xml hívással kérheti le.

Minden végpont

Metódus	Végpont	Scope	Idempotency-Key	Kérés / perc
POST	/invoices Számla vagy proforma kiállítása	invoices:write	kötelező	30
GET	/invoices Számlák listázása (kurzoros lapozás)	invoices:read	—	120
POST	/invoices/preview-totals Összegek kiszámítása, anélkül hogy bármit létrehozna	invoices:read	—	120
GET	/invoices/{invoice_id} Egy számla lekérése	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf A számla PDF-jének letöltése	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Ezt a számlát stornózó helyesbítő bizonylat kiállítása	invoices:write	kötelező	30
POST	/invoices/{invoice_id}/payments A számla megjelölése fizetettként	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments A számla megjelölése nem fizetettként	invoices:write	—	30

Mi a 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
# Kurzoros lapozás: kövesse a next_cursor értékét, amíg has_more nem 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'

# A helyesbítő bizonylat SAJÁT fiskális számot kap; az eredeti számát soha nem használják újra.

bash
# Megjelölés fizetettként
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Visszavonás
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

Hibák

Státusz	Típus	Kód
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Gyakori hibák

A listázás kurzor alapú: kövesse a next_cursor értéket, amíg a has_more false nem lesz. A szűrők: status, document_kind, buyer_tax_id, issued_from, issued_to és q.
A sztornó a POST /v1/invoices/{id}/storno hívás, és saját fiskális sorszámot kap — az eredeti sorszámot soha nem használjuk újra.
A díjbekérő (document_kind proforma) nem használ fel fiskális sorszámot, és nem nyújtható be a nemzeti e-számlázási rendszerbe.
A metadata olvasáskor visszakerül: tegye bele a rendelésazonosítót, és nincs szüksége külön leképezési táblára.
A POST /v1/invoices/preview-totals ugyanazt a számítást végzi el mellékhatások nélkül — kényelmes a végösszegek saját kosárban való megjelenítéséhez.

Kérdések és válaszok fejlesztőknek

Hány tétele lehet egy számlának?

1 és 400 között. A description legfeljebb 1024 karakter lehet, a quantity értékének pedig szigorúan pozitívnak kell lennie.

Mi történik, ha időtúllépés után újra elküldöm ugyanazt a kérést?

Ugyanazzal az Idempotency-Key kulccsal az eredeti számlát kapja vissza, egy Idempotency-Replayed: true fejléccel együtt. Második bizonylat nem jön létre.

Hogyan jelölhetek meg egy számlát fizetettként?

A POST /v1/invoices/{id}/payments fizetettnek jelöli, ugyanazon az útvonalon a DELETE pedig visszavonja. Mindkettőhöz az invoices:write jogosultság kell.

Lásd még