biHesapbiHesap
Hızlı başlangıç

5 dakikada ilk event'inizi gönderin

API anahtarı, ilk istek, idempotency ve audit görüntüleme — buradan başlayın.

Swagger / ReDocKimlik doğrulama
  1. 1

    API anahtarınızı alın

    biHesap admin panelden Partner → API Anahtarları → Yeni anahtar. Üretilen biint_live_… değerini güvenli bir env değişkenine kaydedin; production'da KEY'i log'lara basmayın.

  2. 2

    İlk satış event'inizi gönderin

    Bir POS satışını /api/integrations/v1/sales uç noktasına POST edin. externalId partner tarafındaki tekil satış ID'sidir — aynı externalId ikinci kez gönderilirse 200 (replay) döner, downstream tekrar yazılmaz.

  3. 3

    Response'u okuyun

    202 Accepted aldığınız anda olay outbox'a atomik yazılmıştır. id alanı IntegrationEvent satırının ID'sidir — audit veya replay için bu ID'yi kullanırsınız.

  4. 4

    Idempotency-Key ekleyin

    Network retry'da duplicate üretmemek için her POST'a UUID v4 bir Idempotency-Key header'ı ekleyin. 24h cache window içinde aynı key tekrar gelirse partner-api 200 dönüp orijinal sonucu replay eder.

  5. 5

    Audit + DLQ'yu izleyin

    biHesap panelinden Partner → Olay Logu menüsünden her event'i, durumunu (PUBLISHED/DEAD), gecikmesini ve eğer reddedildiyse DLQ kaydını görürsünüz. Reddedilen olaylar replay edilebilir.

Örnek istek

Bir satış event'ini gönderme

curl -X POST https://partner-api.bihesap.com/api/integrations/v1/sales \
  -H "Content-Type: application/json" \
  -H "X-Integration-Key: biint_live_5f2c4b…" \
  -H "Idempotency-Key: 0e1a4b2f-5c33-4d61-aa11-2b3c5d6e7f8a" \
  -d '{
    "externalId": "POS-2026-05-14-00042",
    "currency": "TRY",
    "occurredAt": "2026-05-14T11:42:08Z",
    "customerExternalId": "ACME-1029",
    "lines": [
      { "productId": "prd_01J9X…", "quantity": 2, "unitAmountMinor": 14900 }
    ]
  }'
response
HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "data": {
    "id": "ie_01J9XK7…",
    "status": "queued",
    "eventType": "partner.sale.recorded",
    "externalId": "POS-2026-05-14-00042",
    "occurredAt": "2026-05-14T11:42:08.000Z"
  }
}

Önemli notlar

  • • Tüm amount alanları minor unit (kuruş). 149.00 TL = 14900.
  • • occurredAt her zaman ISO 8601 UTC. Yerel saat göndermeyin.
  • • externalId aynı sourceId için tekildir — duplicate gönderim 200 ile döner.
Geliştiriciler ana sayfaSonraki: Kimlik doğrulama