توثيق API

كل الطلبات عبر HTTPS وبصيغة JSON. المصادقة بترويسة X-API-Key (تولّد مفتاحك من لوحة التحكم ← مفتاح API).

العنوان الأساسي: https://bakchich.ma

نقاط النهاية

إنشاء طلب

الحقل	الوصف
product_key	مطلوب. من /v1/products
buyer_ref	مطلوب. معرّف طلبك لديك (حتى 200 حرف). فريد؛ إعادة إرسال نفس القيمة تعيد نفس الطلب (200) دون خصم مزدوج.
player_id / server_id	بيانات اللاعب حسب نوع المنتج
quantity	1 – 999 (الافتراضي 1)
note / extra	اختياري
test	true = طلب تجريبي بلا خصم

curl -X POST https://YOUR-DOMAIN/v1/orders \
  -H "X-API-Key: mk_live_..." -H "Content-Type: application/json" \
  -d '{"product_key":"topup/free-fire/brazil/100 Diamonds","player_id":"51234567","buyer_ref":"ORDER-1001"}'

الرد 201:

{
  "order_id": "RG-3F9A12BC7D",
  "buyer_ref": "ORDER-1001",
  "status": "pending",
  "product": "100 Diamonds",
  "quantity": 1,
  "price_usdt": "1.04",
  "delivery_note": null,
  "failure_reason": null
}

الحالات: pending ← delivered (الكود أو التأكيد في delivery_note) أو failed (يُرد المبلغ تلقائياً وسببه في failure_reason).

الأخطاء

الشكل: {"error":{"code":"...","message":"..."}}

HTTP	code	المعنى
401	missing_api_key / invalid_api_key	المفتاح مفقود أو غير صالح
402	insufficient_balance	رصيدك لا يكفي
409	out_of_stock	الباقة نفدت
422	unknown_product / invalid_request	منتج غير معروف أو بيانات ناقصة
429	rate_limited	طلبات كثيرة؛ انتظر Retry-After
503	service_unavailable	مؤقت — أعد المحاولة بنفس buyer_ref

Webhooks

عيّن عنوان HTTPS عاماً من لوحة التحكم، فنرسل لك POST عند اكتمال كل طلب بصيغة Standard Webhooks. الأحداث: order.delivered، order.failed، webhook.test. أعد 2xx للتأكيد؛ تُعاد المحاولة بعد 1د، 5د، 30د، 2س، 6س.

الترويسات: webhook-id، webhook-timestamp، webhook-signature (قيمتها v1,<base64>). تحقق من التوقيع بالسر whsec_... الظاهر في صفحة مفتاح API:

// PHP
$raw = file_get_contents('php://input');
$key = base64_decode(substr($secret, 6));                       // بعد whsec_
$msg = $_SERVER['HTTP_WEBHOOK_ID'].'.'.$_SERVER['HTTP_WEBHOOK_TIMESTAMP'].'.'.$raw;
$expected = 'v1,'.base64_encode(hash_hmac('sha256', $msg, $key, true));
$ok = false;
foreach (explode(' ', $_SERVER['HTTP_WEBHOOK_SIGNATURE']) as $sig) $ok = $ok || hash_equals($expected, $sig);
if (!$ok || abs(time() - (int)$_SERVER['HTTP_WEBHOOK_TIMESTAMP']) > 300) { http_response_code(401); exit; }

# Python
import base64, hashlib, hmac
key = base64.b64decode(secret[6:])
msg = f"{webhook_id}.{timestamp}.{raw_body}".encode()
expected = "v1," + base64.b64encode(hmac.new(key, msg, hashlib.sha256).digest()).decode()
ok = any(hmac.compare_digest(expected, s) for s in signature_header.split())

لا تعتمد على الـ Webhook وحده: اجعل لديك استعلاماً دورياً بـ GET /v1/orders?status=pending كاحتياط.