بناء تكامل (integration) لمتجر على Kayroo

1. ما هو Kayroo Connect؟

Kayroo هي منصّة تجارة إلكترونية (تشبه في بنيتها Shopify) تتيح للتجّار في الجزائر تشغيل متجر إلكتروني — منتجات، طلبات، توصيل، دفع — دون كتابة أي سطر برمجي. "Kayroo Connect" هو اسم طبقة التكامل العامة للمنصّة: واجهة برمجة تطبيقات (API) REST ونظام webhooks يتيحان لتطبيق خارجي التواصل مع متجر تاجر واحد من الخارج.

هذا هو نفس نموذج الثقة المعتمَد في "تطبيقات" Shopify أو إضافات WooCommerce التي تعمل على خادمها الخاص: تطبيقك يعيش بالكامل على بنيتك التحتية الخاصة، في مستودع الكود الخاص بك. لن يحصل إطلاقاً على نسخة من الكود المصدري لـ Kayroo، ولا على بيانات اعتماد قاعدة البيانات، ولا على وصول SSH أو إلى لوحة الإدارة. يمرّ كل تفاعل عبر القناتين الموضّحتين في هذه الصفحة:

• واجهة REST API مصادَق عليها بواسطة رمز (token) — تطلب البيانات (المنتجات، الطلبات، معلومات المتجر، شرائح العملاء، السلال المتروكة) عبر HTTPS بسيط.
• إشعارات webhooks صادرة — ترسل Kayroo إشعار HTTP صغير إلى خادمك فور وقوع حدث ما (طلب جديد، تغيير في منتج، عميل محتمل جديد، تقييم جديد)، حتى لا تضطر لاستطلاع الواجهة باستمرار.

2. كيف تعمل عملية الربط من البداية إلى النهاية

لا يوجد اليوم متجر تطبيقات، ولا زر تثبيت عبر OAuth، ولا حساب مطوّر يُنشأ لدى Kayroo. بدلاً من ذلك، صاحب المتجر (التاجر) هو من يمنح تطبيقك الوصول، مباشرة من لوحة إدارته الخاصة. تسير العملية كما يلي:

1. يفتح التاجر لوحة إدارة Kayroo، وينتقل إلى الإعدادات ← رموز API (API Tokens)، وينشئ رمزاً جديداً لتكاملك — بإعطائه اسماً واختيار الصلاحيات (scopes) الدقيقة التي يجب أن يملكها.
2. ينسخ التاجر هذا الرمز ويرسله إليك (أو يلصقه مباشرة في شاشة إعداد تطبيقك، إذا كان منتجك مصمَّماً بهذه الطريقة).
3. يخزّن تطبيقك هذا الرمز بشكل آمن ويرسله كرمز Bearer مع كل طلب API يوجَّه إلى متجر ذلك التاجر.
4. اختيارياً، ينتقل التاجر أيضاً إلى الإعدادات ← Webhooks في لوحة إدارته، ويلصق عنوان URL الخاص بخادمك، ويختار الأحداث التي يريد إشعارك بها. من تلك اللحظة، ترسل Kayroo تلك الأحداث تلقائياً إلى عنوانك.

3. بداية سريعة

بمجرد حصولك على رمز من تاجر، يعمل كل طلب بنفس الطريقة: طلب HTTPS من نوع GET يحمل الرمز في ترويسة Authorization، موجَّه إلى نطاق متجر ذلك التاجر، تحت المسار /api/v1.

curl "https://example-store.kayroo.app/api/v1/store" \
  -H "Authorization: Bearer kt_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Accept: application/json"

تبدو الاستجابة الناجحة كما يلي:

{
  "data": {
    "id": "9f2c1a...",
    "name": "Example Store",
    "subdomain": "example-store",
    "custom_domain": null,
    "currency": "DZD",
    "language": "fr",
    "delivery_fee": 400,
    "api_version": "v1"
  }
}

4. المصادقة (Authentication)

يجب أن يتضمّن كل طلب الرمز كـ Bearer token في ترويسة Authorization:

Authorization: Bearer kt_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

يمكن أن يكون للرمز تاريخ انتهاء اختياري، يحدّده التاجر عند إنشائه. بمجرد انتهاء صلاحيته أو إلغائه أو حذفه، يتوقّف الرمز عن العمل فوراً في كل طلب لاحق — لا توجد فترة سماح.

يحصل أي رمز مفقود أو غير صحيح الصياغة أو منتهي الصلاحية أو ملغى على نفس الاستجابة:

HTTP/1.1 401 Unauthorized
{ "error": "Invalid or expired token." }

5. الصلاحيات (Scopes)

قوة الرمز محدودة دائماً بالصلاحيات التي حدّدها التاجر عند إنشائه. يتطلّب كل مسار (endpoint) في الواجهة صلاحية واحدة بالتحديد — اطلب فقط ما يحتاجه تكاملك فعلياً؛ التاجر أكثر ميلاً للثقة بتكامل لا يطلب كل شيء والموافقة عليه.

إذا استُخدم رمز لاستدعاء مسار لا يملك صلاحيته، تستجيب الواجهة بما يلي:

HTTP/1.1 403 Forbidden
{
  "error": "insufficient_scope",
  "message": "This token is not authorized for the \"products.read\" scope.",
  "required_ability": "products.read"
}

6. مرجع الواجهة (API Reference)

جميع المسارات للقراءة فقط (GET) وتقع تحت /api/v1. جميع الاستجابات بصيغة JSON. جميع المبالغ أرقام بالدينار الجزائري (DZD)، دون أي تحويل عملة.

معلومات أساسية عن المتجر: الاسم، النطاق الفرعي، النطاق المخصّص (إن وُجد)، العملة، لغة واجهة المتجر، ورسوم التوصيل الثابتة.

curl "https://example-store.kayroo.app/api/v1/store" \
  -H "Authorization: Bearer kt_live_XXXX"

قائمة مقسّمة إلى صفحات لمنتجات المتجر. معاملات الطلب (كلّها اختيارية):

{
  "data": [
    {
      "id": 41,
      "name": "Classic Leather Wallet",
      "slug": "classic-leather-wallet",
      "sku": "WAL-041",
      "description": "Full-grain leather, hand-stitched.",
      "price": 3500,
      "compare_price": 4200,
      "current_price": 3500,
      "on_sale": false,
      "currency": "DZD",
      "stock": 18,
      "in_stock": true,
      "is_visible": true,
      "is_featured": true,
      "category": "Accessories",
      "image_url": "https://example-store.kayroo.app/storage/products/41.jpg",
      "variants": [
        { "id": 101, "options": { "Color": "Brown" }, "price": null, "stock": 10 },
        { "id": 102, "options": { "Color": "Black" }, "price": null, "stock": 8 }
      ],
      "created_at": "2026-02-11T09:12:00+00:00",
      "updated_at": "2026-05-03T14:40:00+00:00"
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "last_page": 4, "per_page": 25, "total": 87 }
}

يعيد GET /api/v1/products/{id} نفس الشكل لمنتج واحد (كائن بسيط تحت "data")، أو محتوى JSON بحالة 404 إذا لم يكن المعرّف موجوداً في هذا المتجر.

قائمة مقسّمة إلى صفحات للطلبات. معاملات الطلب (كلّها اختيارية):

{
  "data": [
    {
      "id": 1032,
      "status": "confirmed",
      "customer": {
        "name": "Amine K.",
        "phone": "0555xxxxxx",
        "email": null,
        "address": "Cité 100 logements, Bt 4"
      },
      "items": [
        { "product_id": 41, "variant_id": 101, "name": "Classic Leather Wallet", "qty": 2, "line_total": 7000 }
      ],
      "subtotal": 7000,
      "discount_amount": 0,
      "coupon_code": null,
      "delivery_price": 400,
      "total": 7400,
      "currency": "DZD",
      "wilaya": "Alger",
      "commune": "Bab Ezzouar",
      "tracking_number": "YAL-88213",
      "landing_page_id": null,
      "created_at": "2026-06-30T10:02:00+00:00",
      "updated_at": "2026-07-01T08:15:00+00:00"
    }
  ],
  "links": { "...": "..." },
  "meta": { "...": "..." }
}

أعداد إجمالية للعملاء مقسَّمة إلى شرائح سلوكية — جدد، متكرّرون، أبطال (متكرّرون وذوو قيمة عالية)، ومعرَّضون للخطر (كانوا يشترون ولم يفعلوا مؤخراً). معامل طلب اختياري: lookback_days (90 افتراضياً، بين 7 و365).

{
  "data": {
    "new": 128,
    "repeat": 54,
    "champions": 12,
    "at_risk": 31
  },
  "meta": { "lookback_days": 90 }
}

قائمة مقسّمة إلى صفحات لعمليات الدفع التي بدأها عملاء دون إتمامها — مفيدة لحملات استرجاع السلة. معاملات الطلب (كلّها اختيارية):

{
  "data": [
    {
      "id": 77,
      "customer_name": "Yasmine B.",
      "customer_phone": "0661xxxxxx",
      "customer_email": null,
      "cart": { "items": [ { "product_id": 41, "qty": 1 } ] },
      "recovered": false,
      "created_at": "2026-07-02T19:40:00+00:00"
    }
  ]
}

7. تقسيم الصفحات (Pagination)

مسارات القوائم (المنتجات، الطلبات، السلال المتروكة) مقسَّمة إلى صفحات. تحتوي كل استجابة قائمة على ثلاثة مفاتيح رئيسية: data (مصفوفة السجلّات لهذه الصفحة)، links (روابط first/last/prev/next)، و meta (current_page، last_page، per_page، total). أرسل ?page=2 للانتقال إلى الصفحة التالية، أو ?per_page=100 لطلب أقصى حجم للصفحة.

8. حدود معدّل الطلبات (Rate Limits)

يقتصر كل رمز افتراضياً على 120 طلباً في الدقيقة. عند تجاوز هذا الحد، ستحصل على استجابة HTTP 429 — تمهّل وأعد المحاولة بعد فترة قصيرة. اعتمد منطق إعادة المحاولة مع تأخير تدريجي (backoff) بدلاً من قصف الواجهة في حلقة ضيقة؛ هذا يحمي تكاملك أيضاً من أن يُعتبر حركة مرور مسيئة.

9. الأخطاء

الأخطاء دائماً بصيغة JSON بسيطة تحتوي مفتاح "error"، وأحياناً "message" مقروء. رموز الحالة التي قد تواجهها:

10. Webhooks

بدلاً من استطلاع الواجهة باستمرار للتحقّق "هل تغيّر شيء؟"، يمكنك أن تطلب من Kayroo إشعار خادمك فور وقوع الحدث. يسجّل التاجر عنوان URL الخاص بمسارك من الإعدادات ← Webhooks في لوحة إدارته، ويختار أياً من الأحداث التالية يريد إرسالها إليك:

كل webhook هو طلب HTTP من نوع POST موجَّه إلى العنوان الذي سجّله التاجر، بالشكل التالي من JSON:

{
  "event": "order.created",
  "data": {
    "id": 1032,
    "status": "pending",
    "total": 7400,
    "customer_name": "Amine K.",
    "customer_phone": "0555xxxxxx",
    "created_at": "2026-06-30T10:02:00+00:00"
  },
  "timestamp": "2026-06-30T10:02:01+00:00"
}

يحمل الطلب أيضاً ترويستين يمكنك الاعتماد عليهما:

11. التحقّق من أنّ webhook قادم فعلاً من Kayroo

قبل الوثوق بأي محتوى webhook، تحقّق من توقيعه. لكل اشتراك webhook سرّ خاص به، تولّده Kayroo عند تسجيل التاجر لمسارك، ويُعرض للتاجر مرّة واحدة ليُرسله إليك بأمان. للتحقّق من طلب:

1. خذ البايتات الخام الدقيقة لمحتوى الطلب (لا تُعد تسلسل أو تنسيق JSON).
2. احسب HMAC-SHA256 لتلك البايتات باستخدام السرّ المشترك كمفتاح.
3. قارن النتيجة، كسلسلة سداسية عشرية بأحرف صغيرة، بترويسة X-Webhook-Signature، باستخدام مقارنة بزمن ثابت.
4. إذا لم تتطابقا، ارفض الطلب (استجب بـ 401 وتجاهله) — المحتوى لم يأتِ من Kayroo، أو جرى تعديله أثناء النقل.

مثال تحقّق بلغة PHP:

$rawBody   = file_get_contents('php://input');
$expected  = hash_hmac('sha256', $rawBody, $sharedSecret);
$received  = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

if (! hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

// تم التحقّق من التوقيع — يمكن الآن معالجة $rawBody بأمان.

مثال تحقّق بلغة Node.js:

const crypto = require('crypto');

function isValidSignature(rawBody, signatureHeader, sharedSecret) {
  const expected = crypto
    .createHmac('sha256', sharedSecret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader || '')
  );
}

12. الأمان وتوقّعات التعامل مع البيانات

• اطلب فقط الصلاحيات التي تحتاجها فعلياً. لا تطلب من التاجر منحك كل الصلاحيات "احتياطاً" — فهذا يجعل تكاملك يبدو غير موثوق، وسيرفضه معظم التجّار.
• خزّن الرموز وأسرار webhook مشفَّرة أثناء التخزين، ولا تضعها إطلاقاً في سجلّات نصّية واضحة، ولا تكشفها أبداً في كود جانب العميل.
• تحقّق من توقيع كل webhook قبل التصرّف بناءً عليه — لا تثق أبداً بمحتوى غير موثَّق.
• التزم بالإلغاء فوراً. إذا حذف التاجر رمزك أو أزال اشتراك webhook الخاص بك، يتوقّف كل وصول فوراً من جانب Kayroo — تأكّد من أنّ تطبيقك يتعامل مع ذلك بسلاسة (مثل تمييز الاتصال كمنقطع) بدلاً من معاملة كل طلب فاشل كخطأ عابر.
• استخدم البيانات المستخرَجة من متجر فقط لصالح ذلك التاجر نفسه. لا تجمّع بيانات تاجر مع آخر أو تعيد بيعها أو تشاركها أبداً، ولا تستخدمها لأي غرض لم يوافق عليه التاجر.
• حدّد فترة احتفاظ بأي بيانات تخزّنها مؤقتاً من الواجهة، واحذفها عندما يفصل التاجر تكاملك أو يطلب منك ذلك.

13. النطاق الحالي والقيود المعروفة

• للقراءة فقط حالياً. لا توجد بعد مسارات لإنشاء أو تعديل أي شيء في متجر (لا إنشاء طلب، لا تحديث مخزون، إلخ) — كل ما سبق هو GET فقط.
• لا يوجد حساب مطوّر ذاتي الخدمة ولا متجر تطبيقات. يُنشئ كل تاجر الرمز يدوياً من لوحة إدارته الخاصة؛ لا يوجد بعد مكان مركزي لتسجيل نفسك كـ"تطبيق Kayroo".
• يستمر الرمز في العمل حتى لو تغيّرت باقة اشتراك التاجر، إلى أن يلغيه التاجر أو تنتهي صلاحيته — يتم التحقّق من الباقة حالياً فقط عند إنشاء الرمز لأول مرّة.
• إعادة محاولات تسليم webhook محدودة: لا تعيد Kayroo حالياً محاولة تسليم فاشل بتأخير تدريجي؛ يُعطَّل اشتراك webhook ببساطة بعد 10 محاولات فاشلة متتالية، ويُتوقَّع من التاجر إعادة تفعيله بمجرد أن يصبح مسارك سليماً مجدداً.

الوصول إلى الواجهة و webhooks متاحان للتجّار على باقة Scale من Kayroo وباقة الدفع حسب الاستخدام (Pay-As-You-Go). إذا لم يجد التاجر الذي تتكامل معه الإعدادات ← رموز API في لوحة إدارته، فهذا عادة هو السبب — اطلب منه التحقّق من باقته الحالية.

14. أسئلة أو شيء ناقص؟

ستستمر هذه الواجهة في التطوّر. إذا احتاج تكاملك إلى بيانات أو حدث غير مغطّى هنا، لا تبحث عن حلّ بديل عبر وصول مباشر — اطلب من التاجر إبلاغ فريق Kayroo بطلبك، أو تواصل معنا مباشرة عبر [email protected].