Genel bakış
hikie üzerine geliştirme yapanlar için teknik dokümantasyon. Webhooklar, imza doğrulama, event kataloğu ve entegrasyon örnekleri.
Burası hikie Developer Documentation — mağazasını kendi sistemlerine bağlamak isteyen geliştiriciler için teknik başvuru kaynağı.
Şu an iki alan dokümante edilir. Webhooks, mağazanızda bir şey olduğunda sizin sunucunuza gönderilen imzalı olay bildirimleridir. Mağaza API'si, yazılımınızın mağazayı okumasını ve ürünleri, ödeme alma linklerini ve indirim kodlarını yönetmesini sağlar.
hikie Webhooks
hikie Webhooks, mağazanızda bir şey olduğunda sizin sunucunuza haber veren
sistemdir. Sipariş ödendi, abonelik yenilendi, ürün güncellendi — her biri
sizin belirlediğiniz adrese, imzalanmış bir POST isteği olarak gider.
Tipik kullanımlar:
- Dijital teslimat — ödeme tamamlandığı anda lisans anahtarını üretip müşteriye gönderirsiniz.
- Erişim açma — dijital ürün satın alındığında kullanıcının hesabında ilgili paketi otomatik tanımlarsınız.
- Sistem senkronizasyonu — siparişi kendi ERP, muhasebe ya da stok sisteminize anında düşürürsünüz.
- Bildirim — yeni siparişi Slack, Telegram, Discord ya da e-posta ile ekibinize duyurursunuz.
Ortak nokta: kimsenin panele girip elle işlem yapması gerekmez.
Anlık
Sipariş ödendiği saniye içinde sunucunuz haberdar olur. API'yi dakikada bir yoklamanıza gerek kalmaz.
Doğrulanabilir
Her isteğin gövdesi size özel bir secret ile imzalanır. Gerçekten hikie'den geldiğini matematiksel olarak doğrularsınız.
Kayıp yok
Sunucunuz kapalıysa teslimat 72 saate yayılan 10 denemeyle tekrarlanır.
Tekrar yok
Ödeme sağlayıcısı aynı siparişi iki kez bildirse bile size tek bildirim gider.
Nasıl görünür
Bir sipariş ödendiğinde sunucunuza düşen istek:
POST /hikie/webhook HTTP/1.1
Host: sunucunuz.com
Content-Type: application/json
Hikie-Event: order.paid
Hikie-Webhook-Id: wh_1f0c8ab29e7d453b6c1a0e94f27d3b85
Hikie-Account-Id: 6512ab3d9f1e4c0012a7bc45
Hikie-Timestamp: 1785945600
Hikie-Occurred-At: 2026-08-07T09:20:00.000Z
Hikie-Api-Version: 2026-09-04
Hikie-Signature: 4c1f9d0a7e2b8c6f1d3a5e90b47c2f8ae61d0937c5b2408fe93a17d6c2b0459e
Hikie-Delivery-Attempt: 1
{
"orderId": "17716204135268844HKS",
"status": "COMPLETED",
"currency": "TRY",
"totals": { "subtotal": "249.90", "shipping": "0.00", "discount": "0.00", "total": "249.90" },
"customerInfo": { "firstName": "Ayşe", "lastName": "Yılmaz", "email": "[email protected]" },
"items": [
{ "itemId": "66b1efd21c9a4e0021f3ab77", "title": "VIP Paket", "quantity": 1, "unitPrice": "249.90" }
]
}Sizin yapmanız gereken: imzayı doğrulamak, işi kuyruğa atmak ve 200 dönmek.
Akış
flowchart LR
A["Mağazanızda bir olay<br/>sipariş, abonelik, ürün…"] --> B["hikie<br/>event'i kaydeder"]
B --> C["İlgili abonelikleriniz<br/>bulunur ve imzalanır"]
C --> D["Sunucunuza POST"]
D -->|"2xx"| E["Teslim edildi"]
D -->|"hata / zaman aşımı"| F["Yeniden denenir<br/>72 saatlik pencere"]
F --> D
Sözleşmenin özeti
| Konu | Değer |
|---|---|
| Metot | POST, Content-Type: application/json |
| İmza | HMAC_SHA256(secret, "<timestamp>.<ham gövde>"), hex |
| API sürümü | 2026-09-04 — Hikie-Api-Version başlığında |
| Tekrar anahtarı | Hikie-Webhook-Id — yeniden denemelerde değişmez |
| Yanıt süresi | 5 saniye |
| Başarı ölçütü | Herhangi bir 2xx |
| Yeniden deneme | 10 deneme, 72 saatlik pencere |
| Yönlendirme | Takip edilmez — 3xx kalıcı hata sayılır |
| Şema | Yalnızca https:// |
Endpoint'iniz 5 saniye içinde yanıt dönmeli. Veritabanı yazma, dış sistemlere istek, e-posta — bunları yanıtı döndükten sonra yapın. Ayrıntı: Endpoint gereksinimleri.
Nereden başlamalı
Mağaza API'si
Sipariş ve satışları okuyun, ürün oluşturup yayına alın, ödeme alma linki üretin. Yapay zekâ asistanları için OpenAPI dosyası da var.
Hızlı başlangıç
Abonelik oluşturmaktan ilk doğrulanmış teslimata kadar adım adım.
Hazır örnekler
Express, Fastify ve NestJS için kopyalanabilir tam sunucu kodu.
Event kataloğu
Hangi event ne zaman tetiklenir, payload'ında hangi alanlar var.
Sık sorulanlar
Sabit IP var mı, secret'ı kaybettim, imza tutmuyor…