Dokun API dokümanları

Dokun API'si kasa (POS) ve kendi sistemlerinizle entegrasyon içindir. Tüm istekler HTTPS üzerinden JSON ile yapılır. Temel adres:

https://dokun.io/api/v1

Paket gereksinimi

API ve webhook'lar yalnız Pro pakette kullanılabilir. Paket her istekte yeniden denetlenir: deneme süresi biterse veya ödeme alınamazsa istekler 402, Pro dışı pakette 403 döner; webhook'lar gönderilmez.

Kimlik doğrulama

API anahtarını işletme panelinden oluşturun. Anahtar dk_ ile başlar ve yalnız oluşturulduğunda bir kez gösterilir (biz yalnız özetini saklarız). Her istekte Authorization başlığında Bearer şemasıyla gönderin. Anahtar işletmenize bağlıdır; yalnız kendi kartlarınıza erişir.

Authorization: Bearer dk_...

Hız sınırı

Anahtar başına dakikada en fazla 60 istek. Sınır aşılınca 429 döner; retry-after başlığı, yeni dakikanın başlamasına kalan saniyeyi verir.

Hata kodları

Hata yanıtlarının gövdesi JSON değil, düz metindir. Durum koduna göre işlem yapın.

Müşteri listesi

GET /api/v1/customers

İşletmenizin müşterilerini en yeniden eskiye döner. Sayfalama yoktur: yanıt en fazla 200 kayıt içerir (en son kaydolan 200 müşteri). marketing_consent_at, pazarlama izninin verildiği zamandır; izin yoksa null.

curl https://dokun.io/api/v1/customers \
  -H "Authorization: Bearer dk_..."

{ "customers": [ { "id": "…", "name": "Ayşe", "email": "ayse@example.com",
  "created_at": "2026-10-30T09:12:00Z", "marketing_consent_at": null } ] }

Damga ekle

POST /api/v1/stamp

Karta damga ekler. serial, kartın seri numarası ya da kasada okutulan QR metninin tamamıdır (olduğu gibi gönderebilirsiniz). delta isteğe bağlıdır, varsayılan 1. Yanıttaki multiplier, kampanya (ör. çift damga) nedeniyle uygulanan çarpandır. Başarılı damgada kart Apple Cüzdan'da güncellenir ve stamp webhook'u tetiklenir.

curl -X POST https://dokun.io/api/v1/stamp \
  -H "Authorization: Bearer dk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fis-000123" \
  -d '{"serial": "ABC123", "delta": 1}'

{ "ok": true, "balance": 4, "multiplier": 1 }

Idempotency-Key

Ağ hatasında güvenle tekrar denemek için isteğe bağlı Idempotency-Key başlığı gönderin (1–64 yazdırılabilir ASCII karakter, ör. kasa fiş numarası). Aynı anahtar 24 saat boyunca aynı yanıtı döner ve damga tekrarlanmaz; tekrar edilen yanıtta idempotent-replayed: true başlığı bulunur. Yalnız başarılı yanıtlar saklanır; hata alan istek aynı anahtarla yeniden denenebilir.

Webhook'lar

İşletme panelinden bir HTTPS adresi ve olay türü seçerek webhook ekleyin. Her olayda adresinize JSON gövdeli bir POST gönderilir. Gövde biçimi: event (olay adı), data (olay verisi), ts (milisaniye cinsinden Unix zamanı).

POST https://ornek.com/dokun-webhook
content-type: application/json
x-dokun-signature: 5d41402abc4b2a76…
x-dokun-attempt: 1

{ "event": "stamp", "data": { "serial": "ABC123", "balance": 4 }, "ts": 1761815520000 }

Teslimat ve tekrar deneme

Yalnız 2xx yanıt başarılı sayılır; yönlendirmeler (3xx) izlenmez ve istek yaklaşık 5 saniyede zaman aşımına uğrar. Başarısız teslimat en fazla 3 deneme olacak şekilde üstel beklemeyle (yaklaşık 2 ve 4 dakika sonra) yeniden gönderilir; x-dokun-attempt başlığı deneme sırasını verir. Tekrar denemelerde gövde birebir aynıdır: event + ts + data ile çift işlemeyi önleyin.

İmza doğrulama

Her istekte x-dokun-signature başlığı, ham gövdenin webhook gizli anahtarıyla (panelde gösterilen değer, olduğu gibi) hesaplanan HMAC-SHA256 özetidir, hex biçiminde. Gövdeyi JSON olarak ayrıştırmadan önce ham metin üzerinden doğrulayın ve sabit zamanlı karşılaştırma kullanın. İmzada zaman damgası yoktur; tekrar oynatmaya karşı ts alanını kontrol edin (ör. 10 dakikadan eski olayları reddedin).

import { createHmac, timingSafeEqual } from 'node:crypto'

const raw = await req.text() // JSON.parse'tan önce ham gövde
const expected = createHmac('sha256', process.env.DOKUN_WEBHOOK_SECRET).update(raw).digest()
const got = Buffer.from(req.headers.get('x-dokun-signature') ?? '', 'hex')
if (got.length !== expected.length || !timingSafeEqual(got, expected)) return new Response(null, { status: 401 })
const { event, data, ts } = JSON.parse(raw)
if (Date.now() - ts > 10 * 60_000) return new Response(null, { status: 400 })

Sorularınız için: WhatsApp