Geliştiriciler · API v1
Sürümlü bir REST API, imzalı webhook'lar ve üretilmiş veriyle çalışan bir sandbox. Bu sayfa, her uç nokta için geçerli olan kuralları anlatır.
# The sandbox base URL and key are issued together
export POOCRAFT_API="https://<your-sandbox-host>"
export POOCRAFT_KEY="pk_sandbox_••••••••"
curl "$POOCRAFT_API/api/v1/sportsbook/events?state=live" \
--header "Authorization: Bearer $POOCRAFT_KEY"Bu sayfadaki örnekler temsilidir. Bir sözleşmeyi değil, kuralları ve veri yapılarını gösterir. Nihai uç noktalar ve veri yapıları entegrasyon sürecinde kesinleşir; canlı ortam erişimi de bu süreçte düzenlenir.
Poocraft API, /api/v1 altında HTTPS üzerinden sunulan bir REST API'dir. İstekler ve yanıtlar JSON biçimindedir. Her yanıt bir X-Request-Id başlığı taşır; belirli bir çağrı hakkında bize yazarken bu değeri iletebilirsiniz.
Operatör konsolu bu API üzerine kuruludur; ekibinizin arayüzde yaptığı her şey otomatikleştirilebilir. Erişim kapsamla sınırlıdır: bir anahtar yalnızca ait olduğu kiracıyı görür ve yalnızca kapsamlarının izin verdiği işlemleri yapar.
Kurallar
/api/v12500 = 25,00X-Request-IdHer isteği, bearer token olarak gönderilen bir API anahtarıyla doğrulayın: Authorization: Bearer <key>. Anahtarlar ortam ve entegrasyon bazında oluşturulur; tam değer yalnızca oluşturma anında bir kez gösterilir.
Her anahtar, yapabileceklerini sınırlayan kapsamlar taşır. Bir entegrasyona yalnızca ihtiyaç duyduğu kapsamları verin: raporlama işi, para hareket ettirebilen bir anahtar taşımamalıdır.
GET /api/v1/wallet/balances?player_id=pl_9041
Authorization: Bearer pk_sandbox_••••••••Örnek kapsamlar
| Kapsam | İzin verdiği işlem |
|---|---|
wallet:read | Bakiyeleri ve işlemleri okuma |
wallet:write | Borç, alacak ve geri alma |
games:read | Oyun kataloğunu okuma |
launch:write | Başlatma oturumu oluşturma |
sportsbook:read | Etkinlikleri, marketleri ve oranları okuma |
compliance:write | Uyum kontrolü isteme |
webhooks:manage | Webhook uç noktalarını oluşturma ve yönetme |
reports:read | Olayları ve dışa aktarımları sorgulama |
Kapsam adları örnektir. Kullanabileceğiniz kapsamlar anahtarınızla birlikte listelenir.
Eksik, hatalı biçimli ya da iptal edilmiş bir anahtar, unauthorized koduyla 401 döndürür. Geçerli olup gerekli kapsamı taşımayan bir anahtar ise forbidden koduyla 403 döndürür.
Anahtarları sunucularınızda tutun. Tarayıcıya ya da mobil uygulamaya asla koymayın. Bir anahtarı yenilemek için yenisini oluşturun, devreye alın, ardından eskisini iptal edin.
Ağlar hata verir ve istemci, isteğin işlenip işlenmediğini her zaman bilemez. Idempotency anahtarları yeniden denemeyi güvenli kılar: durumu değiştiren her istekle birlikte bir Idempotency-Key başlığı gönderin. Cüzdan işlemlerinde bu başlık zorunludur.
Anahtarlar nasıl davranır
"idempotent_replay": true yer alır.idempotency_mismatch koduyla 422 olarak reddedilir.5xx yanıtından sonra aynı anahtarla yeniden deneyin. Yeniden deneme için yeni anahtar üretmeyin.POST /api/v1/wallet/debit
Authorization: Bearer pk_sandbox_••••••••
Idempotency-Key: 7c1e9a52-0b7e-4f0e-9a51-2f6f3b1c8d10
Content-Type: application/json
{
"player_id": "pl_9041",
"amount": 2500,
"currency": "EUR",
"reference": "round_58210"
}Yeniden denenen isteğe verilen yanıt
HTTP/1.1 200 OK
X-Request-Id: req_01HZX4W2
{
"transaction_id": "txn_8f2a41",
"status": "posted",
"balance": { "amount": 147500, "currency": "EUR" },
"idempotent_replay": true
}Hatalar, alışılmış HTTP durum kodlarını ve tek bir JSON zarfını kullanır. code sabittir ve kodunuzda dallanmak için güvenlidir. message insanlar için yazılmıştır ve değişebilir. request_id, X-Request-Id başlığıyla aynıdır.
HTTP/1.1 409 Conflict
X-Request-Id: req_01HZX7B3
{
"error": {
"code": "idempotency_mismatch",
"message": "This Idempotency-Key was already used with a different request body.",
"request_id": "req_01HZX7B3"
}
}| Durum | Kod | Anlamı | Ne yapmalı |
|---|---|---|---|
| 400 | invalid_request | İstek hatalı biçimlendirilmiş ya da bir alan doğrulamadan geçememiş. | İsteği düzeltin. Değiştirmeden yeniden denemeyin. |
| 401 | unauthorized | API anahtarı eksik, hatalı biçimli ya da iptal edilmiş. | Authorization başlığını ve ortamı kontrol edin. |
| 403 | forbidden | Anahtar geçerli, ancak gerekli kapsamı taşımıyor. | Gerekli kapsamı taşıyan bir anahtar kullanın. |
| 404 | not_found | Kaynak yok ya da bu anahtar tarafından görülemiyor. | Kimliği ve ortamı kontrol edin. |
| 409 | conflict | İstek mevcut durumla çelişiyor; örneğin bir işlemin ikinci kez geri alınması. | Karar vermeden önce güncel durumu okuyun. |
| 422 | idempotency_mismatch | Idempotency-Key daha önce farklı bir gövdeyle kullanılmış. | Yeni bir işlem için yeni bir anahtar kullanın. |
| 429 | rate_limited | Anahtar hız sınırını aşmış. | Retry-After süresince bekleyin, sonra yeniden deneyin. |
| 500 | internal_error | Bizim tarafımızda bir hata oluştu. | Aynı idempotency anahtarıyla yeniden deneyin. Sürerse request_id değerini iletin. |
Liste uç noktaları imleç tabanlı sayfalama kullanır. Her yanıt bir data dizisi ve bir next_cursor içerir. Sonraki sayfayı almak için bu değeri cursor olarak gönderin. next_cursor değeri null ise sona ulaşmışsınızdır.
İmleçler opaktır. Saklayın ve olduğu gibi geri gönderin; ayrıştırmayın, kendiniz oluşturmayın. İmleç, üretildiği sorgu için geçerlidir; sayfalar arasında gezerken filtreleri değiştirmeyin.
| Ad | Yer | Anlamı |
|---|---|---|
limit | Sorgu | Sayfa boyutu. Üst sınır her uç noktanın belgesinde yer alır. |
cursor | Sorgu | Önceki yanıttaki next_cursor değeri. |
next_cursor | Yanıt | Sonraki sayfanın imleci; son sayfada null. |
GET /api/v1/reports/events?type=wallet.transaction.posted&limit=50&cursor=c_eyJvIjo1MH0
Authorization: Bearer pk_sandbox_••••••••HTTP/1.1 200 OK
X-Request-Id: req_01HZX6K8
{
"data": [
{ "id": "evt_3c9d61", "type": "wallet.transaction.posted", "occurred_at": "2026-11-13T19:04:52Z" }
],
"next_cursor": null
}Hız sınırları API anahtarı bazında uygulanır. Anahtarlarınızın sınırları ortama ve sözleşmenize göre değişir; bu yüzden burada rakam verilmez. Her yanıt, geçerli sınırı ve kalan hakkı başlıklarda bildirir.
| Başlık | Anlamı |
|---|---|
RateLimit-Limit | Bu anahtar için geçerli pencerede izin verilen istek sayısı. |
RateLimit-Remaining | Geçerli pencerede kalan istek sayısı. |
RateLimit-Reset | Geçerli pencerenin sıfırlanacağı zaman. |
Retry-After | 429 ile birlikte gönderilir: yeniden denemeden önce beklenecek saniye. |
Bir anahtar sınırını aştığında API, rate_limited koduyla 429 döndürür. Retry-After başlığındaki süre kadar bekleyin, ardından aynı idempotency anahtarıyla yeniden deneyin. İstemcinize sabit bir sınır yazmak yerine başlıkları okuyun.
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: <requests allowed in the window>
RateLimit-Remaining: 0
RateLimit-Reset: <when the window resets>
Retry-After: <seconds to wait>
X-Request-Id: req_01HZX8QD
{
"error": {
"code": "rate_limited",
"message": "Too many requests for this API key.",
"request_id": "req_01HZX8QD"
}
}Webhook'lar, olayları kaydettiğiniz bir HTTPS uç noktasına teslim eder. Her uç nokta ihtiyaç duyduğu olay türlerine abone olur ve kendine ait bir imzalama anahtarına sahiptir; bu anahtar uç nokta oluşturulurken bir kez gösterilir.
POST https://operator.example/webhooks/poocraft
X-Poocraft-Signature: t=1794600000,v1=5d41402abc4b2a76b9719d911017c592
Content-Type: application/json
{
"id": "evt_3c9d10",
"type": "wallet.transaction.posted",
"data": { "transaction_id": "txn_8f2a41", "amount": 2500, "currency": "EUR" }
}Her teslim, t=<timestamp>,v1=<signature> biçiminde bir X-Poocraft-Signature başlığı taşır. İmza, uç nokta anahtarıyla {t}.{payload} dizgesi üzerinden hesaplanan, onaltılık kodlanmış bir HMAC-SHA256 değeridir; payload ham istek gövdesidir.
Bir teslimi doğrulama
t ve v1 olarak ayırın.{t}.{payload} üzerinden HMAC-SHA256 hesaplayın.v1 ile sabit zamanlı bir karşılaştırmayla kıyaslayın.t değeri belirlediğiniz toleranstan eski olan teslimleri reddedin.id değerine göre tekilleştirin.// Verify the signature before trusting a delivery
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(payload: string, header: string, secret: string) {
const [t, v1] = header.split(",").map((part) => part.split("=")[1] ?? "");
const expected = createHmac("sha256", secret).update(`${t}.${payload}`).digest("hex");
return v1.length === expected.length && timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}Olayı sakladığınız anda 2xx durum koduyla yanıt verin ve işi eşzamansız yürütün. Başka her yanıt ya da zaman aşımı başarısızlık sayılır; teslim, artan aralıklarla yeniden denenir.
Teslimler birden fazla kez ve sırasız gelebilir. İşleyicilerinizi idempotent yazın ve tekilleştirme için olay id değerini kullanın.
Kaydedilmiş olaylar bir uç noktaya yeniden gönderilebilir; bu, bir kesintiden sonra ya da yeni bir tüketici devreye girdiğinde işe yarar. Tekrar oynatılan teslim ilk olay id değerini korur, yeni bir zaman damgası ve imza alır; dolayısıyla aynı doğrulama ve tekilleştirme geçerlidir.
Sandbox, API yüzeyini üretilmiş veriyle yansıtır. Gerçek para, gerçek oyuncu ve canlı sağlayıcılara bağlantı yoktur.
Sandbox anahtarları pk_sandbox_ önekini taşır ve yalnızca sandbox ortamında çalışır. Canlı ortam anahtarları entegrasyon sürecinde ayrıca verilir ve sandbox anahtarlarıyla hiçbir zaman aynı öneki taşımaz.
Sandbox'ta neler var
Sandbox erişimini ekibimiz tanımlar. Demo talep edin ve neyi entegre etmeyi planladığınızı bize anlatın.
Sandbox erişimi isteyinSürüm, yolun bir parçasıdır: /api/v1. Bir sürüm içinde yalnızca geriye dönük uyumlu değişiklikler yaparız: yeni uç noktalar, yeni isteğe bağlı parametreler, yanıtlarda yeni alanlar ve yeni olay türleri.
İstemcilerinizi, tanımadıkları alanları ve olay türlerini yok sayacak şekilde yazın. Uyumu bozan değişiklikler yeni bir sürüm yolu altında yayımlanır; sürümler arası geçiş takvimi entegre operatörlerle birlikte belirlenir.
API'nin altı alanı; her biri için örnek bir istek, bir yanıt ve ilgili bir webhook.
Temsili örneklerdir. Uç noktalar ve veri yapıları, canlı ortam erişiminin düzenlendiği entegrasyon sürecinde kesinleşir.
Deftere karşı borç, alacak ve geri alma işlemleri; her yazma işleminde idempotency ile.
POST/api/v1/wallet/debit
POST /api/v1/wallet/debit
Authorization: Bearer pk_sandbox_••••••••
Idempotency-Key: 7c1e9a52-0b7e-4f0e-9a51-2f6f3b1c8d10
Content-Type: application/json
{
"player_id": "pl_9041",
"amount": 2500,
"currency": "EUR",
"reference": "round_58210"
}Oyunları listeleyin, başlatma oturumları oluşturun ve tur sonuçlarını tek adaptör sözleşmesiyle alın.
POST/api/v1/launch/sessions
POST /api/v1/launch/sessions
Authorization: Bearer pk_sandbox_••••••••
Content-Type: application/json
{
"game_id": "gm_ember_vault",
"player_id": "pl_9041",
"currency": "EUR",
"locale": "en",
"return_url": "https://operator.example/lobby"
}Harici sportsbook servislerinden gelen etkinlikler, marketler ve oran güncellemeleri tek modele dönüştürülür.
GET/api/v1/sportsbook/events
GET /api/v1/sportsbook/events?sport=football&state=live
Authorization: Bearer pk_sandbox_••••••••KYC/AML sağlayıcıları, limitler ve sorumlu oyun işlemleri için entegrasyon noktaları.
POST/api/v1/compliance/checks
POST /api/v1/compliance/checks
Authorization: Bearer pk_sandbox_••••••••
Content-Type: application/json
{
"player_id": "pl_9041",
"action": "withdrawal",
"amount": 25000,
"currency": "EUR"
}Yeniden deneme, tekrar oynatma ve uç nokta bazında olay seçimiyle imzalı olay teslimi.
POST/api/v1/webhooks/endpoints
POST /api/v1/webhooks/endpoints
Authorization: Bearer pk_sandbox_••••••••
Content-Type: application/json
{
"url": "https://operator.example/webhooks/poocraft",
"events": ["wallet.transaction.posted", "game.round.settled"]
}Operasyonel olayları sorgulayın; finans, operasyon ve uyum için raporları dışa aktarın.
GET/api/v1/reports/events
GET /api/v1/reports/events?type=wallet.transaction.posted&from=2026-11-01&limit=50
Authorization: Bearer pk_sandbox_••••••••Sandbox erişimi
Neyi entegre etmeyi planladığınızı anlatın. Sandbox erişimini tanımlayalım ve geliştiricilerinize ilk çağrılarda eşlik edelim.