Lëshimi i faturave përmes API

POST /invoices me Idempotency-Key, TVSH si përqindje, plus listimi, storno dhe shënimi si e paguar.

Fatura jote e parë në 6 hapa

Dërgo POST /v1/invoices me një objekt buyer dhe të paktën një hyrje në lines.
Shto header-in Idempotency-Key — është i detyrueshëm, një çelës për çdo operacion logjik.
Dërgo vat_rate si përqindje (21) dhe unit_price si ÇMIM NJËSI NETO.
Përgjigja 201 mban id, number, series, totalet net/vat/gross dhe metadatat që dërgove.
Shkarko dokumentin me GET /v1/invoices/{id}/pdf ose XML-in UBL me GET /v1/invoices/{id}/xml.

Çdo pikë fundore

Metoda	Pika fundore	Fushëveprimi	Idempotency-Key	Kërkesa / minutë
POST	/invoices Lëshon një faturë ose proformë	invoices:write	e detyrueshme	30
GET	/invoices Liston faturat (faqosje me kursor)	invoices:read	—	120
POST	/invoices/preview-totals Llogarit totalet pa krijuar asgjë	invoices:read	—	120
GET	/invoices/{invoice_id} Merr një faturë	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Shkarkon PDF-në e faturës	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Lëshon një notë kredie që anulon këtë faturë	invoices:write	e detyrueshme	30
POST	/invoices/{invoice_id}/payments Shënon faturën si të paguar	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Shënon faturën si të papaguar	invoices:write	—	30

Çfarë është API e 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
# Faqosje me kursor: ndiq next_cursor derisa has_more të jetë 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'

# Nota e kreditit merr NUMRIN E VET fiskal; numri origjinal s'ripërdoret kurrë.

bash
# Shëno si të paguar
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Zhbëj
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

Gabimet

Statusi	Lloji	Kodi
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Gabimet e zakonshme

Listimi bazohet në kursor: ndiq next_cursor derisa has_more të jetë false. Filtrat përfshijnë status, document_kind, buyer_tax_id, issued_from, issued_to dhe q.
Storno është POST /v1/invoices/{id}/storno dhe merr numrin e vet fiskal — numri origjinal s'ripërdoret kurrë.
Një proforma (document_kind proforma) s'konsumon numër fiskal dhe s'mund të paraqitet në sistemin kombëtar të e-faturimit.
metadata kthehet te leximet: vendos aty ID-në e porosisë dhe s'të duhet më një tabelë e veçantë përputhjeje.
POST /v1/invoices/preview-totals kryen të njëjtën aritmetikë pa efekte anësore — e dobishme për të shfaqur totalet në shportën tënde.

Pyetje dhe përgjigje për zhvilluesit

Sa rreshta mund të ketë një faturë?

Ndërmjet 1 dhe 400. description kufizohet në 1024 karaktere, dhe quantity duhet të jetë rreptësisht pozitive.

Çfarë ndodh nëse ridërgoj të njëjtën kërkesë pas timeout-it?

Me të njëjtin Idempotency-Key merr faturën origjinale plus header-in Idempotency-Replayed: true. S'lëshohet asnjë dokument i dytë.

Si e shënoj një faturë si të paguar?

POST /v1/invoices/{id}/payments e shënon si të paguar, dhe DELETE në të njëjtën rrugë e zhbën. Të dyja kërkojnë fushëveprimin invoices:write.

Shih edhe