Partner API referansı

Hızlı başlangıç ve imza doğrulama. Uçların tam listesi ve şemaları için bu deponun packages/contracts/openapi/kefildar-v1.yaml dosyasına bakın -- bu API'nin tek doğruluk kaynağı odur; her canlı uç bu dosyaya karşı otomatik doğrulanır.

1. Anahtarınızı alın

Kefildar hesabınızın telefon numarasıyla birlikte [E-POSTA ADRESİ] adresine yazarak başvurun. İki Kefildar yetkilisi ayrı ayrı onayladıktan sonra X-Kefildar-Key ve gizli anahtarınız size bir kez iletilir. Bu site (developer.kefildar.com) hiçbir hesap veya anahtar bilgisi tutmaz -- yalnızca dokümantasyondur.

2. İstekleri imzalayın

Kimlik doğrulamalı her uç dört başlık ister; tek doğrulama biçimi budur:

X-Kefildar-Key: kf_live_...
X-Kefildar-Timestamp: <unix zaman damgası>
X-Kefildar-Nonce: <yalnızca bir kez kullanılan rastgele değer>
X-Kefildar-Signature: HMAC-SHA256(secret, METHOD.PATH.TIMESTAMP.NONCE.SHA256(body))

Zaman damgası sunucu saatinden 5 dakikadan fazla sapamaz; her nonce yalnızca bir kez kabul edilir. Aşağıdaki örnek Node.js ile imzayı hesaplar:

const crypto = require('crypto')

function signRequest({ method, path, body, keyId, secret }) {
  const timestamp = Math.floor(Date.now() / 1000).toString()
  const nonce = crypto.randomBytes(16).toString('hex')
  const bodyHash = crypto.createHash('sha256').update(body ?? '').digest('hex')
  const canonical = [method.toUpperCase(), path, timestamp, nonce, bodyHash].join('.')
  const signature = crypto.createHmac('sha256', secret).update(canonical).digest('hex')

  return {
    'X-Kefildar-Key': keyId,
    'X-Kefildar-Timestamp': timestamp,
    'X-Kefildar-Nonce': nonce,
    'X-Kefildar-Signature': signature,
  }
}

3. Yetkiler (scopes)

Başvurunuz onaylanırken size hangi yetkilerin verileceği belirlenir:

contracts:create -- satışlarınızdan taslak sözleşme oluşturma
contracts:read -- sözleşme durumu okuma
payments:read -- ödeme durumu okuma
escrow:read -- havuzda bekleyen tutarı okuma
webhooks:manage -- webhook uç noktası ekleme/listeleme

4. Sık kullanılan uçlar

GET /api/v1/public/documents/{verification_code} -- kimlik gerektirmez, evrak doğrulama
POST /api/v1/partner/contracts -- satıştan taslak sözleşme oluşturma (Idempotency-Key zorunlu)
GET /api/v1/partner/contracts/{verification_code}/payment-status -- ödeme durumu
GET /api/v1/partner/webhook-endpoints / POST /api/v1/partner/webhook-endpoints -- webhook uç noktası yönetimi

5. Webhook olayları

Her istek webhook-id, webhook-timestamp ve webhook-signature: v1,HMAC-SHA256(secret, "{id}.{timestamp}.{ham gövde}") başlıklarını taşır. Yeniden deneme aralıkları: 5sn, 1dk, 5dk, 30dk, 2sa, 6sa, 12sa, 24sa. Aynı olayı birden fazla kez alabilirsiniz (en-az-bir-kez teslim) -- id alanına göre tekilleştirin.

contract.created
contract.accepted
escrow.funded
payment.failed
milestone.paid
dispute.opened
dispute.resolved

6. Hata biçimi

{"error": {"type": "validation_error", "code": "invalid_buyer_phone", "message": "...", "request_id": "req_...", "details": {"field": "buyer.phone"}}}