API üzerinden fatura kesmek

Idempotency-Key ile POST /invoices, yüzde olarak KDV, ayrıca listeleme, iade faturası ve ödendi işareti.

6 adımda ilk fatura

Bir buyer nesnesi ve lines içinde en az bir öğe ile POST /v1/invoices gönderin.
Idempotency-Key başlığını ekleyin — zorunludur, mantıksal işlem başına bir anahtar.
vat_rate’i yüzde olarak (21), unit_price’ı ise NET birim fiyat olarak gönderin.
201 yanıtı id, number, series, net/vat/gross toplamlarını ve gönderdiğiniz metadata’yı taşır.
Belgeyi GET /v1/invoices/{id}/pdf ile veya UBL XML’ini GET /v1/invoices/{id}/xml ile alın.

Tüm uç noktalar

Metot	Uç nokta	Scope	Idempotency-Key	İstek / dakika
POST	/invoices Fatura veya proforma düzenle	invoices:write	zorunlu	30
GET	/invoices Faturaları listele (imleçle sayfalama)	invoices:read	—	120
POST	/invoices/preview-totals Hiçbir şey oluşturmadan toplamları hesapla	invoices:read	—	120
GET	/invoices/{invoice_id} Bir faturayı getir	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Faturanın PDF'ini indir	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Bu faturayı iptal eden bir iade faturası düzenle	invoices:write	zorunlu	30
POST	/invoices/{invoice_id}/payments Faturayı ödendi olarak işaretle	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Faturayı ödenmedi olarak işaretle	invoices:write	—	30

4invoices API'si nedir

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
# İmleçle sayfalama: has_more false olana kadar next_cursor'ı takip edin.
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'

# İade faturası KENDİ mali numarasını alır; orijinalin numarası asla yeniden kullanılmaz.

bash
# Ödendi olarak işaretle
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Geri al
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

Hatalar

Durum	Tip	Kod
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Sık yapılan hatalar

Listeleme cursor tabanlıdır: has_more false olana kadar next_cursor’ı izleyin. Filtreler arasında status, document_kind, buyer_tax_id, issued_from, issued_to ve q bulunur.
İptal (storno) POST /v1/invoices/{id}/storno ile yapılır ve kendi mali numarasını alır — orijinal numara asla yeniden kullanılmaz.
Bir proforma (document_kind proforma) mali numara tüketmez ve ulusal e-fatura sistemine gönderilemez.
metadata okumalarda aynen geri döner: sipariş id’nizi buraya koyun, ayrı bir eşleme tablosuna artık ihtiyacınız kalmaz.
POST /v1/invoices/preview-totals aynı hesaplamayı yan etki olmadan yapar — toplamları kendi sepetinizde göstermek için kullanışlıdır.

Geliştiriciler için soru ve cevaplar

Bir faturada kaç satır olabilir?

1 ile 400 arasında. description 1024 karakterle sınırlıdır ve quantity kesinlikle pozitif olmalıdır.

Timeout sonrasında aynı isteği yeniden gönderirsem ne olur?

Aynı Idempotency-Key ile orijinal faturayı ve Idempotency-Replayed: true başlığını alırsınız. İkinci bir belge düzenlenmez.

Bir faturayı ödendi olarak nasıl işaretlerim?

POST /v1/invoices/{id}/payments faturayı ödendi olarak işaretler, aynı yol üzerindeki DELETE ise bunu geri alır. İkisi de invoices:write scope’unu gerektirir.

Ayrıca bakın