Panelin yaptığı her şeyi, aynı kurallarla, kendi yazılımınızdan yapın.

1. Anahtarınızı doğrulayın

Her istek Authorization: Bearer başlığıyla gelir. İlk çağrınız, anahtarın hangi işletmeye ve hangi şirkete bağlı olduğunu, hangi yetkileri taşıdığını söyler:

curl -s "https://api.kumpara.net/v1/me" \
  -H "Authorization: Bearer kp_live_a1b2c3d4_…"

{
  "data": {
    "tenant":    { "id": "…", "name": "Örnek Ticaret A.Ş.", "plan": "Pro" },
    "company":   { "id": "…", "legalName": "Örnek Ticaret A.Ş.", "baseCurrency": "TRY" },
    "apiClient": { "prefix": "kp_live_a1b2c3d4", "environment": "live",
                   "scopes": ["me:read", "contacts:write", "sales:write", "sales:approve"] }
  },
  "meta": { "requestId": "0HN…" }
}

GET /v1/capabilities ise bu şirkette e-belge bağlantısı var mı, kontör bakiyesi kaç, baz para birimi ne — akışınızı buna göre kurarsınız.

2. Cariyi dış kimliğinizle eşleyin

Kendi veritabanınızdaki müşteriyi her seferinde yeniden aramanız gerekmez: VKN ya da cari kodu ile upsert edin. Kayıt varsa güncellenir, yoksa açılır.

curl -s -X POST "https://api.kumpara.net/v1/contacts/actions/upsert?matchBy=taxNumber" \
  -H "Authorization: Bearer kp_live_…" \
  -H "Idempotency-Key: contact-4711-2026-09-23" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Örnek Gıda Ltd. Şti.",
        "type": "customer",
        "taxNumber": "1234567890",
        "preferredCurrency": "TRY",
        "paymentTermDays": 30
      }'

Yanıt { "data": { "id": "…", "name": "…", "created": true } } döner. created alanı kaydın yeni mi açıldığını, yoksa var olanın mı güncellendiğini söyler. matchBy yalnız taxNumber veya code olur.

3. Faturayı kesin ve onaylayın

Fatura satırında tutar alanı yoktur. Siz miktar, birim fiyat, iskonto ve KDV oranını gönderirsiniz; satır toplamı, tevkif edilen KDV, baz tutar ve belge numarası sunucuda üretilir.

curl -s -X POST "https://api.kumpara.net/v1/sales-invoices" \
  -H "Authorization: Bearer kp_live_…" \
  -H "Idempotency-Key: order-88213-invoice" \
  -H "Content-Type: application/json" \
  -d '{
        "contactId": "6f1c…",
        "currency": "TRY",
        "approve": true,
        "lines": [
          { "productId": "9a3e…", "quantity": 10, "unitPrice": 250, "vatRate": 20 },
          { "description": "Nakliye", "quantity": 1, "unitPrice": 150, "vatRate": 20 }
        ]
      }'

{
  "data": { "id": "c41b…", "number": "SF-2026-000412", "status": "approved", "approved": true },
  "meta": { "requestId": "0HN…" }
}

approve: true oluşturma ve onayı tek transaction'da yapar: belge numarası, cari borcu ve stok çıkışı birlikte doğar. Bu bir para mutasyonudur; bu yüzden anahtarınızda sales:write yanında sales:approve de olmalıdır — aksi hâlde 403 insufficient_scope alırsınız.

4. Tahsilatı kaydedin ve faturayı kapatın

curl -s -X POST "https://api.kumpara.net/v1/payments" \
  -H "Authorization: Bearer kp_live_…" \
  -H "Idempotency-Key: payment-88213" \
  -H "Content-Type: application/json" \
  -d '{
        "contactId": "6f1c…",
        "cashAccountId": "2b77…",
        "direction": "incoming",
        "amount": 3060,
        "invoiceType": "sales_invoice",
        "invoiceId": "c41b…"
      }'

Kasa defteri, cari defteri ve fatura kapaması aynı transaction'da yazılır. Birden çok faturaya dağıtmak için allocations[], sonradan kapatmak için POST /v1/payments/{id}/actions/allocate.

5. Değişiklikleri çekin

Karşı sistemi güncel tutmak için akışı düzenli çekersiniz. Akış değişen kaydın tipini ve kimliğini verir; ayrıntıyı kendi ucundan okursunuz.

curl -s "https://api.kumpara.net/v1/changes?since=2026-09-23T06:00:00Z&types=sales_invoice,payment" \
  -H "Authorization: Bearer kp_live_…"

{
  "data": [
    { "type": "sales_invoice", "id": "c41b…", "action": "created", "occurredAt": "2026-09-23T07:12:44Z" },
    { "type": "payment",       "id": "77af…", "action": "created", "occurredAt": "2026-09-23T07:13:02Z" }
  ],
  "meta": { "checkpoint": "2026-09-23T07:13:02Z", "nextCursor": null, "hasMore": false }
}

Bir sonraki çağrıda meta.checkpoint değerini since olarak verirsiniz — sınır dışlayıcıdır, aynı kayıt ikinci kez gelmez. Commit sırası ile damga sırası arasındaki boşluğa karşı beş dakikalık örtüşme bırakmanızı öneririz; okuma idempotent olduğu için tekrar gelen kayıt zararsızdır.

Kimlik ve yetki

Anahtar Authorization: Bearer kp_live_… (ya da X-Api-Key) ile gönderilir. Anahtarın düz değeri saklanmaz — Kumpara yalnız SHA-256 özetini ve gösterim önekini tutar. Her anahtar tek şirkete kilitlidir; başka şirketin verisi mimari olarak dönmez. Anahtarın yetkisi, onu üreten kullanıcının rol yetkisini aşamaz.

Yetkiler {kaynak}:{eylem} biçimindedir ve yirmi sekiz tanedir:

Yetkisi olmayan uç 403 insufficient_scope döner ve eksik yetkiyi adıyla söyler.

Idempotency

Her yazma isteği Idempotency-Key başlığı ister. Anahtar, kaydı yazan transaction'ın içinde saklanır — dual-write yoktur. Aynı anahtar ikinci kez gelirse iş tekrar yapılmaz. Yanıt iki biçimden biridir: 409 idempotency_replayed (oluşan kaydı GET ile okursunuz) ya da 200 ile ilk yanıtın gövdesi ve replayed: true bayrağı. İkisi de "işlem zaten uygulandı" demektir; istemciniz her ikisini de başarı olarak ele almalıdır. Anahtarın kapsamı (işletme, API anahtarı, uç, anahtar) dörtlüsüdür: iki farklı entegratörün aynı anahtarı çakışmaz.

Para, kur ve sayısal tipler

Tutarlar numeric(19,4) olarak saklanır ve JSON'da string ondalık döner — kayan nokta yuvarlaması yaşanmaz. Tutar ile para birimi hiçbir zaman ayrılmaz.

Her finansal satır kendi kur snapshot'ını taşır: originalAmount, originalCurrency, exchangeRate, baseAmount, baseCurrency. Kur listesi sonradan güncellense bile geçmiş belge değişmez. Kuru exchangeRate alanıyla siz verebilirsiniz; göndermezseniz 1 kullanılır — çapraz kurlu bir belge kesiyorsanız bu alanı doldurun.

Sayfalama ve filtre

Listeler cursor ile sayfalanır; offset yoktur. Yanıt meta.nextCursor ve meta.hasMore taşır. Sayfa boyutu pageSize ile verilir: varsayılan 50, üst sınır 200. Delta çekmek için updatedAfter sorgu parametresi ya da /v1/changes akışı kullanılır.

Hatalar

Hatalar RFC 9457 application/problem+json biçimindedir ve kararlı bir code alanı taşır. Sözlük dondurulmuştur: dokümante edilen kod değişmez.

{
  "type": "https://docs.kumpara.net/errors/insufficient_scope",
  "title": "Yetki yok",
  "status": 403,
  "detail": "Bu uç `sales:approve` yetkisi ister; anahtarınızda yok.",
  "code": "insufficient_scope",
  "requestId": "0HN…"
}

Alan bazlı hatalarda gövdeye errors[] eklenir: her satır pointer, code ve detail taşır.

İstek sınırı

Okuma ve yazma ayrı kovadır — rapor çeken bir işlem fatura kesmeyi kilitlemez. Varsayılanlar anahtar başına dakikada 600 okuma ve 120 yazma'dır; her yanıtta RateLimit-Limit, RateLimit-Remaining ve RateLimit-Reset başlıkları döner. Sınır aşılırsa 429 + Retry-After alırsınız.

İstek kimliği

Her yanıt X-Request-Id taşır; aynı değer hata gövdesinde requestId olarak da görünür. Destek talebinde bunu paylaşın. Kendi kimliğinizi göndermek isterseniz istekte X-Request-Id başlığını doldurun (en çok 64 karakter), yanıt aynı değeri geri verir.

Keşif

Sözleşmenin tamamı OpenAPI 3 olarak yayınlanır: https://api.kumpara.net/v1/openapi.json makine tarafından okunur, https://api.kumpara.net/v1/docs ise tarayıcıda gezilir. Spec kimlik doğrulama istemez — sözleşme geneldir, veri içermez.

Aşağıdaki tablo bugün yayında olan yüzeyin tamamıdır. Her satırın tam parametreleri, gövdesi ve yanıt şeması OpenAPI'de durur: https://api.kumpara.net/v1/docs.

Belge zinciri nasıl bağlanır? İrsaliye gövdesinde orderId, fatura gövdesinde orderId ve deliveryNoteIds[] alanları vardır; satır bazında orderLineId ve deliveryNoteLineId ile eşleştirme yaparsınız. Kalan miktar persisted bir sayaçtan değil, iptal edilmemiş faturalardan türetilir — iptal edilen fatura tüketim sayılmaz, sipariş yeniden faturalanabilir.

Stok çıkışı tek yerde doğar. Sevk ve fatura onayı aynı malı iki kez düşürmez: satış tarafındaki toplam çıkış max(Σ sevk, Σ onaylı fatura) olarak hesaplanır ve her belge yalnız kendi farkını yazar. Fatura önce onaylandıysa sevk hiç hareket üretmeyebilir — bu doğru davranıştır.

İzolasyon veritabanı seviyesindedir. İşletmeleri birbirinden ayıran şey uygulamadaki bir filtre değil, PostgreSQL'in kendi satır düzeyi güvenlik katmanıdır. API isteği en az yetkili bir rolle bağlanır ve bağlam her bağlantı açılışında veritabanına yazılır; bir sorgu yanlış yazılsa bile başka bir işletmenin satırı dönmez. Şirket ayrımı bunun üstüne gelir: anahtar tek şirkete kilitlidir.

Anahtar saklanmaz. Yalnız SHA-256 özeti ve gösterim öneki (kp_live_a1b2c3d4) tutulur. Düz değer bir kez, oluşturma yanıtında görünür; kaybederseniz kurtarılamaz, yenisini üretirsiniz. Anahtar loglara yazılmaz — log'a yalnız önek düşer. İptal anında etkilidir.

Yetki yükseltmesi yoktur. Anahtarın scope'u onu üreten kullanıcının rol yetkisini aşamaz. approve: true ile fatura oluşturmak sales:write yanında sales:approve ister; eksikse istek reddedilir, sessizce taslak kaydedilmez.

Her işlem iz bırakır. API'den yapılan her yazma denetim kaydına aktör olarak anahtar önekiyle yazılır (api:kp_live_a1b2c3d4). Kimin ne zaman ne yaptığı sonradan sorulabilir; panel, mobil ve API aynı iz defterine düşer.

Kişisel veri dar kapsamlıdır. TCKN, IBAN, ad-adres gibi alanlar pii:read yetkisi olmayan anahtarlara maskelenerek döner — son dört karakter görünür, uç yine çalışır. Entegrasyonunuz kişisel veriye ihtiyaç duymuyorsa bu yetkiyi hiç vermeyin; en iyi koruma, verinin hiç gitmemesidir.

Anahtarı nasıl saklamalısınız? Sunucu tarafında, ortam değişkeninde ya da bir sır yöneticisinde tutun; kaynak koda, tarayıcıya veya mobil uygulamaya gömmeyin. Her entegrasyona ayrı anahtar üretin — birini iptal etmek diğerlerini etkilemesin. Destek talebi açarken requestId ve Idempotency-Key paylaşın; anahtarınızı asla paylaşmayın.