تاجر الفريج للمطورين

البداية

1. صاحب المتجر يفتح الإعدادات ← للمطورين في لوحة التحكم (باقة الأعمال).
2. للـ API: يسوي مفتاح، يختار وش يقدر يسوي، ويعطيك إياه. يطلع مرة وحدة بس.
3. للـ Webhooks: يضيف عنوانك https والأحداث، ويعطيك رمز التوقيع السري.

API

أرسل المفتاح في كل طلب في ترويسة Authorization بالشكل اللي في المثال تحت. الردود بصيغة JSON.

https://tajeralfareej.com/api/v1/open

المبالغ أرقام صحيحة بأصغر وحدة لعملة الطلب: 1.250 دينار = 1250، و12.50 ريال = 1250.

401: ما في مفتاح أو ملغي. 403 missing_scope: المفتاح ما يقدر يسوي هذا. 403 business_only: المتجر طلع من باقة الأعمال. 404: مو في هالمتجر.

curl https://tajeralfareej.com/api/v1/open/orders?limit=10 \
  -H "Authorization: Bearer tjr_live_…"

curl -X PATCH https://tajeralfareej.com/api/v1/open/products/<id>/stock \
  -H "Authorization: Bearer tjr_live_…" \
  -H "Content-Type: application/json" \
  -d '{"stock": 4}'

شكل الطلب

{
  "id": "6f1c…", "number": 12,
  "status": "new | confirmed | ready | delivered | cancelled",
  "payment_status": "unpaid | claimed | paid",
  "payment_method": "benefitpay", "fulfillment": "delivery | pickup",
  "customer": { "name": "Maha", "phone": "97339001122" },
  "address": "Villa 4, Road 12, Riffa", "note": null, "table_number": null,
  "scheduled_for": null, "created_at": "2026-10-16T10:00:00.000Z",
  "currency": "BHD",
  "amounts": { "subtotal": 7000, "delivery_fee": 1000, "discount": 0, "tip": 0, "vat": 0, "total": 8000 },
  "items": [{ "name": "Saffron luqaimat", "quantity": 2, "unit_price": 3500, "options": [] }]
}

Webhooks

الأحداث: order.created، order.status_changed، order.paid، وping من زر أرسل تجربة. كل حدث ينرسل POST بصيغة JSON للعنوان اللي أضافه المتجر.

POST <your address>
X-Tajer-Event: order.paid
X-Tajer-Delivery: 2b7e…
X-Tajer-Timestamp: 1792090000
X-Tajer-Signature: sha256=5d41…

{ "id": "2b7e…", "type": "order.paid", "created_at": "…", "data": { "order": { … } } }

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

الترويسة X-Tajer-Signature فيها sha256= متبوعة بـ HMAC-SHA256 (hex) للنص "الوقت.الجسم" بالرمز السري، مثل الكود تحت.

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

const signed = `${req.headers['x-tajer-timestamp']}.${rawBody}`;
const expected = 'sha256=' + createHmac('sha256', SECRET).update(signed).digest('hex');
const ok = expected.length === req.headers['x-tajer-signature'].length
  && timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-tajer-signature']));
// Also refuse timestamps older than 5 minutes, and ignore a X-Tajer-Delivery you already handled.

الردود وإعادة المحاولة

رد بأي 2xx خلال 5 ثواني. غير كذا ينعاد الإرسال بعد 1، 5، 30، 120، 360، 720 و1440 دقيقة، وبعدها ينلغى. بعد 15 فشل ورا بعض يتوقف الـ Webhook لين المتجر يشغله. ما نتبع التحويلات، ولازم العنوان اسم https عام.