توثيق API

المصادقة

أرسل مفتاحك في الترويسة التالية. المفتاح يظهر مرة وحدة عند إنشائه من لوحة التاجر. الحساب الموقوف يترفض.

Authorization: Bearer YOUR_KEY

المسارات

• GET/api/public/v1/balance
  رصيد المحفظة بالدولار
• GET/api/public/v1/products?category=&q=&limit=&offset=
  قائمة المنتجات بالأسعار
• GET/api/public/v1/products/:id
  تفاصيل منتج والخانات المطلوبة
• POST/api/public/v1/orders
  إنشاء طلب
• GET/api/public/v1/orders/:id
  حالة طلب
• GET/api/public/v1/orders?reference=
  البحث بالمرجع

منع التكرار

كل طلب شراء يحتاج ترويسة Idempotency-Key فريدة، حتى ما ينخصم الطلب مرتين لو أعدت الإرسال.

مثال طلب

curl -X POST https://file-led-task-friend.lovable.app/api/public/v1/orders \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Idempotency-Key: my-order-1001" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"PRODUCT_ID","quantity":1,"fields":{},"reference":"1001"}'

الحالة تكون pending ثم submitted ثم completed (فيها codes) أو failed (يرجعلك المبلغ). تابعها بـ GET /orders/:id.

جرّب توا

حط مفتاحك وجرّب طلبات القراية بس (الرصيد والمنتجات). ما فيش شراء من هنا، والمفتاح ما يتحفظش.

رموز الأخطاء

• unauthorizedالمفتاح غلط أو ملغى
• ip_not_allowedعنوان IP مش مسموح للمفتاح
• key_inactiveالمفتاح موقوف أو انتهت صلاحيته
• daily_cap_reachedوصلت حد الصرف اليومي للمفتاح (429)
• merchant_suspendedالحساب موقوف
• subscription_requiredيلزم اشتراك نشط
• insufficient_balanceالرصيد ما يكفيش
• package_not_sellableالمنتج مش متاح للبيع
• quantity_out_of_rangeالكمية مش مسموحة
• missing_fieldخانة مطلوبة ناقصة (شوف fields)
• price_changedالسعر تغيّر، أعد المحاولة
• ordering_disabledالبيع مقفول مؤقتًا
• bad_requestالطلب ناقص أو Idempotency-Key أقل من 8 حروف

حط رابط https في لوحة التحكم. لما يكمل طلب أو يفشل نبعتولك POST فيه order.completed أو order.failed. الأكواد ما تنبعتش في الإشعار — اقراها بـ GET /orders/:id. لو متجرك ما ردش بـ 2xx نعاودو بعد 1، 5، 15، 60، 240 دقيقة.

تأكد من التوقيع:

// Node.js
const sig = req.headers["x-1api-signature"]; // "sha256=<hex>"
const expected = "sha256=" + crypto.createHmac("sha256", WEBHOOK_SECRET).update(rawBody).digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) return res.status(401).end();
// body: { id, event, created_at, data: { order_id, status, total, currency, reference, ... } }