Yaliko
ابدأ الآن

المطورون

API وwebhooks

اربط نظام ERP أو مستودعك أو أدوات الأتمتة بمتجرك: اقرأ الطلبات، وحدّث المخزون، واستقبل الأحداث فور وقوعها.

إنشاء مفتاح API https://dber.app/api/v1

المصادقة

أنشئ مفتاحًا من الإعدادات ← المطورون (للمالك فقط). أرسله في ترويسة Authorization: Bearer. مفتاح «قراءة» يقرأ فقط؛ ومفتاح «قراءة وكتابة» يمكنه أيضًا تعديل الطلبات والمنتجات. احتفظ به على الخادم.

Authorization: Bearer yaliko_live_…

الحدود

120 طلبًا في الدقيقة لكل مفتاح. بعد ذلك يرد الـ API بالرمز 429: انتظر قليلًا ثم أعد المحاولة.

التصفح

تُرجع القوائم { data, next_cursor }، الأحدث أولًا. مرّر limit (من 1 إلى 100، و50 افتراضيًا) وcursor=next_cursor للصفحة التالية. تكون قيمة next_cursor هي null في الصفحة الأخيرة.

الأخطاء

يُرجع الخطأ { error: { code, message } } مع رمز حالة HTTP: 400 محتوى غير صالح، 401 مفتاح غائب أو ملغى، 403 مفتاح للقراءة فقط، 404 غير موجود في متجرك، 422 حقل غير صالح، 429 طلبات كثيرة جدًا.

المبالغ أعداد صحيحة بعملة المتجر (currency). التواريخ بصيغة ISO 8601 وبتوقيت UTC.

نقاط الوصول

GET /storeمتجر المفتاح: الاسم والعملة واللغة. مفيد لتجربة مفتاح.قراءة
GET /ordersالطلبات، الأحدث أولًا. عوامل التصفية: status وcreated_after وcreated_before.قراءة
GET /orders/{id}طلب واحد مع منتجاته والعميل والتوصيل.قراءة
PATCH /orders/{id}تغيير status (PENDING وPROCESSING وSHIPPED وDELIVERED وCANCELED) وcarrier وtracking_number وtracking_url. نفس النتائج كما في لوحة التحكم: إرجاع المخزون، وإشعار العميل، ونقاط الولاء.كتابة
GET /productsالمنتجات مع متغيراتها. عامل التصفية: q (في الاسم).قراءة
GET /products/{id}منتج واحد.قراءة
PATCH /products/{id}تحديث price وcompare_at_price وstock وvariants: [{ id, price, stock }]. يُبلَّغ العملاء المنتظرون عند عودة المنتج إلى المخزون.كتابة
GET /customersالعملاء. عوامل التصفية: email وphone.قراءة
GET /customers/{id}عميل واحد.قراءة

مثال: عرض الطلبات المطلوب تجهيزها

curl https://dber.app/api/v1/orders?status=PENDING&limit=2 \
  -H "Authorization: Bearer yaliko_live_…"
{
  "data": [
    {
      "id": "cmuo2k1x40001…",
      "reference": "40001ABC",
      "status": "PENDING",
      "payment": { "mode": "COD", "status": "PENDING", "refunded": 0 },
      "total": 730,
      "currency": "MAD",
      "customer": { "id": "cmung…", "name": "Sara Alaoui", "phone": "212612345678", "email": null },
      "shipping": { "address": "12 rue …", "city": "Casablanca", "carrier": null, "tracking_number": null },
      "items": [{ "product_id": "cmunc…", "name": "Théière", "quantity": 1, "unit_price": 590 }],
      "created_at": "2026-09-30T10:12:00.000Z"
    }
  ],
  "next_cursor": "cmuo2k1x40001…"
}

مثال: وضع علامة «تم الشحن» على طلب

curl -X PATCH https://dber.app/api/v1/orders/cmuo2k1x40001… \
  -H "Authorization: Bearer yaliko_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "status": "SHIPPED", "carrier": "Amana", "tracking_number": "RR123456789MA" }'

Webhooks

أضف رابط https من الإعدادات ← المطورون واختر الأحداث. نرسل طلب POST بصيغة JSON موقّعًا عند كل حدث. أجب برمز 2xx خلال 10 ثوانٍ، ونفّذ العمل الثقيل بعد ذلك.

الأحداث

  • order.createdتم تقديم طلب (من المتجر، أو بعد تأكيد الدفع بالبطاقة، أو من لوحة التحكم).
  • order.updatedتغيّرت حالة طلب.
  • customer.createdأنشأ عميل حسابه.
POST /webhooks/yaliko
Yaliko-Event: order.updated
Yaliko-Delivery: cmup…
Yaliko-Signature: t=1790745600,v1=5f2b…

{
  "id": "evt_…",
  "type": "order.updated",
  "created_at": "2026-09-30T10:20:00.000Z",
  "data": { "id": "cmuo2k1x40001…", "status": "SHIPPED", … }
}

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

تحتوي ترويسة Yaliko-Signature على t (طابع زمني) وv1 (HMAC-SHA256 لـ «t.المحتوى» بسرّ الـ webhook). احسبه على المحتوى الخام، وارفض الطوابع الزمنية الأقدم من 5 دقائق.

import crypto from "node:crypto";

// Express: app.post("/webhooks/yaliko", express.raw({ type: "application/json" }), handler)
function isFromYaliko(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const a = Buffer.from(expected), b = Buffer.from(parts.v1 ?? "");
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

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

إذا لم يرد رابطك برمز 2xx، نعيد المحاولة بعد دقيقة، ثم 5 دقائق، ثم 30 دقيقة، ثم ساعتين، ثم 12 ساعة. سجل الإرسال وزر «إعادة الإرسال» موجودان في الإعدادات. قد يصل الحدث نفسه مرتين: أزل التكرار بالاعتماد على معرّف الحدث.