دليل المطوّرين

المصادقة

من لوحة التحكم ← الربط (API)، طلّع مفتاح لكل فرع. المفتاح يرتبط بالفرع، فكل التذاكر تنسوّى بنفس الفرع. أرسله بهيدر Authorization:

Authorization: Bearer 12|xYz…

الصلاحيات: tickets:read للقراءة، و tickets:write للإنشاء والتحديث. الـ API متوفرة بباقة «بهويتك» أو أعلى.

الـ Endpoints

كل الأوامر تشتغل هم برقم طلب الكاشير: /tickets/by-external/{external_id}/ready

سوّي تذكرة

الرد يرجّع token ورابط صفحة الزبون ورابط صورة QR. اطبع الـ QR على الوصل، أو اعرضه على شاشة الكاشير. وإذا ترسل customer_phone (رقم عراقي) والمحل مشغّل الـ SMS، نرسل للزبون رسالة وحدة أول ما يجهز.

curl -X POST https://dorak.g4t.io/api/v1/tickets \
  -H "Authorization: Bearer $DORAK_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10452" \
  -d '{"external_id": "10452", "customer_name": "Ali", "customer_phone": "07701234567"}'

$response = Http::withToken(env('DORAK_TOKEN'))
    ->withHeaders(['Idempotency-Key' => 'order-'.$order->id])
    ->post('https://dorak.g4t.io/api/v1/tickets', [
        'external_id' => (string) $order->id,
        'customer_name' => $order->customer_name,
    ]);

$qrUrl = $response->json('qr_url'); // print it on the receipt

// Later, when the kitchen finishes:
Http::withToken(env('DORAK_TOKEN'))->post("https://dorak.g4t.io/api/v1/tickets/by-external/{$order->id}/ready");

const res = await fetch('https://dorak.g4t.io/api/v1/tickets', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DORAK_TOKEN}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `order-${order.id}`,
  },
  body: JSON.stringify({ external_id: String(order.id) }),
});
const { number, qr_url } = await res.json();

{
  "message": "Ticket created successfully",
  "id": 981,
  "number": "27",
  "token": "q1W9…32 chars…",
  "qr_url": "https://dorak.iq/t/q1W9…/qr.svg",
  "public_url": "https://dorak.iq/t/q1W9…"
}

curl -X POST https://dorak.g4t.io/api/v1/tickets/by-external/10452/ready \
  -H "Authorization: Bearer $DORAK_TOKEN"

تكرار الطلبات (Idempotency)

إذا الكاشير ممكن يعيد الطلب بعد انقطاع، أرسل هيدر Idempotency-Key فريد لكل طلب. نفس المفتاح بنفس البيانات يرجّع نفس الرد بدون ما يسوّي تذكرة ثانية.

Webhooks

أضف رابط HTTPS من لوحة التحكم واختار الأحداث. نرسل POST بـ JSON، ونعيد المحاولة لحد 5 مرات إذا ما رجع ردكم 2xx.

الأحداث: ticket.created، ticket.linked (الزبون مسح الكود)، ticket.ready، ticket.collected، ticket.cancelled، feedback.submitted.

تحقق من التوقيع

كل طلب بيه X-Dorak-Timestamp و X-Dorak-Signature. التوقيع HMAC-SHA256 لـ «timestamp.body» بالمفتاح السري مال الرابط. ارفض الطلب إذا التوقيع ما يطابق أو الوقت أقدم من 5 دقايق.

$timestamp = (int) $request->header('X-Dorak-Timestamp');
$expected = 'sha256='.hash_hmac('sha256', $timestamp.'.'.$request->getContent(), $secret);

abort_unless(hash_equals($expected, (string) $request->header('X-Dorak-Signature')), 401);
abort_if(abs(time() - $timestamp) > 300, 401);

$event = $request->json('event');        // e.g. "ticket.ready"
$ticket = $request->json('data.ticket'); // same shape as GET /tickets/{id}

الأخطاء والحدود

كل الأخطاء JSON بيها message. 401 مفتاح غلط، 403 صلاحية ناقصة، 402 الباقة ما تشمل الـ API، 404 تذكرة مو موجودة، 422 بيانات غلط أو انتقال حالة مو مسموح، 429 تجاوزت الحد (120 طلب بالدقيقة لكل مفتاح) أو رنّيت قبل 30 ثانية.