إذا كانت طلباتك تأتي من أداة لا يرتبط بها Cashod بشكل مباشر (متجر مبني خصيصًا، أو CRM، أو أداة لإنشاء صفحات الهبوط، أو وكيل ذكاء اصطناعي)، فإن واجهة Cashod البرمجية العامة REST تتيح لهذه الأداة إنشاء طلبات الدفع عند الاستلام، وقراءة حالة التوصيل ورقم التتبع، ومزامنة المنتجات والمخزون. تنشئ مفتاحًا لكل متجر من الإعدادات ← المطورون، وترسل POST /v1/orders مع معرّفك الخاص external_id حتى لا تُنشئ إعادة المحاولة طلبًا مكررًا أبدًا، ثم تستعلم عن الطلب لمتابعة توصيله. الأدلة الكاملة والمرجع التفاعلي متوفران في بوابة المطورين.
الواجهة البرمجية أم التكامل المباشر أم الويب هوك أم Google Sheets: أيها تختار؟
يستقبل Cashod الطلبات بأربع طرق. اختر أخفّها بما يناسب حاجتك:
- التكاملات المباشرة: Shopify وYouCan وWooCommerce وLightFunnels وStoreep وxPage. إذا كان متجرك يعمل على إحداها، فاربطه من صفحة التكاملات دون أي برمجة. مثال: تكامل Shopify.
- الويب هوك الوارد: يرسل نموذجك أو أداتك كل طلب جديد إلى رابط ويب هوك خاص بـ Cashod. مناسب عندما تستطيع الأداة إرسال الطلب ولا تحتاج إلى أي رد. التفاصيل في صفحة الويب هوك.
- الاستيراد من Google Sheets: للفرق التي ما زالت تجمع طلباتها في جدول بيانات.
- الواجهة البرمجية العامة REST: عندما تحتاج إلى تواصل في الاتجاهين: إنشاء الطلبات، وقراءة الحالة والتتبع، وإنشاء المنتجات أو تحديثها حسب SKU، وتحديث المخزون. هذا هو الخيار المناسب للمطورين، وللوكالات التي تعمل لعدة تجار، ولوكلاء الذكاء الاصطناعي.
كيف تعمل مفاتيح API والصلاحيات (scopes)؟
يحمل كل طلب الترويسة Authorization: Bearer csk_live_…. تُنشأ المفاتيح لكل متجر على حدة من الإعدادات ← المطورون. يُعرض المفتاح مرة واحدة فقط عند إنشائه، ولا يحتفظ Cashod إلا ببصمة مشفّرة (hash) منه، لذا انسخه مباشرة إلى مكان حفظ الأسرار لديك.
يحصل كل مفتاح على الصلاحيات التي يحتاجها فقط:
- orders:read وorders:write: عرض الطلبات وقراءتها وإنشاؤها.
- products:read وproducts:write: عرض المنتجات وقراءتها وإنشاؤها أو تحديثها.
- stock:write: تحديث مخزون متغيّر (variant).
صلاحية الكتابة تشمل صلاحية القراءة المقابلة لها. صفحة هبوط تنشئ الطلبات فقط تحتاج إلى orders:write لا غير، وسكربت مستودع يرسل المخزون فقط يحتاج إلى stock:write. ويُستحسن أن تنشئ الوكالات مفتاحًا لكل متجر عميل، فإلغاء مفتاح عميل لا يؤثر أبدًا على الآخرين.
كيف تنشئ طلب دفع عند الاستلام دون تكرار؟
أرسل POST /v1/orders مع جسم JSON. الحقول الرئيسية:
- external_id: معرّفك الخاص للطلب (يُنصح به بشدة، انظر أدناه).
- customer: الاسم ورقم الهاتف. يمكن إرسال الرقم بأي صيغة، ويتولى Cashod توحيدها.
- shipping: العنوان والمدينة ورقم هاتف للتوصيل اختياري.
- items: لكل عنصر كمية، وواحد من sku أو product_id أو اسم حر name (مع سعر الوحدة) لمنتج غير موجود في الكتالوج.
- حقول اختيارية: total أو discount، وnotes لوكيل التأكيد، وsource_name لتقاريرك الخاصة، وscheduled_for لتاريخ الاستحقاق، وconfirmed.
افتراضيًا، يدخل الطلب الجديد إلى قائمة التأكيد مثل أي طلب آخر، فيؤكده مركز الاتصال أو وكيل الذكاء الاصطناعي. لا تضع confirmed على true إلا إذا كنت قد أكدت الطلب مع الزبون بنفسك.
إعادة المحاولة بأمان باستخدام external_id
انقطاع الاتصال أمر وارد. من دون حماية من التكرار، قد يتحول طلب أُعيد إرساله إلى طلب حقيقي ثانٍ يُسلَّم لموزّع حقيقي. مع external_id، يعيد الاستدعاء الأول الرمز 201 (تم الإنشاء)، وأي إعادة محاولة بالمعرّف نفسه تعيد 200 مع الطلب الموجود مسبقًا. وبذلك يستطيع كودك إعادة المحاولة بحرية ومعرفة ما حدث من رمز الحالة وحده.
كيف تقرأ حالة التوصيل ورقم التتبع؟
يعيد GET /v1/orders/:id الطلب مع حالة الشحن، وحالة التأكيد، وشركة التوصيل، وtracking_number، والمبالغ (بما فيها الدفعة المسبقة ومبلغ الدفع عند الاستلام المطلوب تحصيله)، وتواريخ مثل الشحن والتسليم. أما GET /v1/orders فيعرض قائمة الطلبات مع فلاتر حسب حالة الشحن وحالة التأكيد وتاريخ الإنشاء، وبها تُعيد الحالات إلى نظام CRM أو تعرضها لزبونك.
لا ترسل الواجهة البرمجية ويب هوك صادرًا، لذا فمزامنة الحالات تتم عبر مهمة استعلام دوري، مثلًا عرض طلبات الفترة التي تهمك كل بضع دقائق وتسجيل التغييرات في نظامك.
كيف تزامن المنتجات والمخزون؟
- POST /v1/products ينشئ أو يحدّث حسب SKU: الاستدعاء نفسه ينشئ المنتج في المرة الأولى ثم يحدّثه بعد ذلك. تُطابَق المتغيّرات أيضًا حسب SKU، والمتغيّر الذي لا ترسله يبقى كما هو ولا يُحذف.
- GET /v1/products وGET /v1/products/:id لقراءة الكتالوج، مع فلاتر حسب SKU والاسم وحالة التفعيل.
- PATCH /v1/products/:id/variants/:variantId/stock يحدد مستوى المخزون. القيمة مطلقة وليست فرقًا، لذلك لا يمكن لاستدعاء مكرر أن يحتسب الكمية مرتين.
التصفح بين الصفحات وحدود الطلبات والأخطاء
- التصفح: تستخدم نقاط العرض مؤشرات (cursors). تعيد كل صفحة data وhas_more وnext_cursor؛ أعد إرسال المؤشر للحصول على الصفحة التالية (حتى 100 عنصر في الصفحة).
- حد الطلبات: 120 طلبًا في الدقيقة لكل مفتاح. بعد ذلك تتلقى HTTP 429؛ انتظر قليلًا ثم أعد المحاولة.
- الأخطاء: بالشكل نفسه دائمًا، كائن error يحتوي على type (مثل invalid_request وauthentication_error وpermission_error وnot_found وrate_limit_exceeded وserver_error) وmessage مقروءة. اجعل منطقك يعتمد على النوع، وسجّل الرسالة.
هل يستخدم وكيل الذكاء الاصطناعي الواجهة البرمجية أم خادم MCP؟
يتوقف ذلك على الجهة التي يعمل الوكيل لصالحها:
- وكيلك الخاص أو أتمتتك (بوت مبيعات في صفحة الهبوط، أو وكيل يستقبل الطلبات داخل CRM) يستخدم واجهة REST بمفتاح محدود الصلاحيات. يعمل لمتجر واحد، بالصلاحيات التي منحتها لهذا المفتاح بالضبط. وتسهّل مواصفة OpenAPI على الرابط https://api.cashod.ma/api/v1/openapi.json تحويل نقاط الواجهة إلى أدوات للوكيل.
- مساعد ذكاء اصطناعي يستخدمه شخص يمر عبر خادم MCP الخاص بـ Cashod على https://mcp.cashod.ma/mcp. يعمل مع مساعدي الذكاء الاصطناعي الذين يدعمون موصلات MCP، مثل Claude وChatGPT. يتم الدخول عبر OAuth: يسجّل المستخدم الدخول بحساب Cashod ويوافق على الوصول، ثم يعمل المساعد بصلاحيات هذا المستخدم المعتادة على متاجره. خطوات الإعداد في الإعدادات ← الدردشة الذكية. اقرأ المزيد عن الذكاء الاصطناعي في Cashod.
هل يستطيع Cashod إرسال الأحداث إلى نظامك؟
ليس عبر الواجهة البرمجية. لإرسال الأحداث إلى الخارج استخدم Workflows: يمكن لسير العمل استدعاء أي رابط عبر إجراء الويب هوك، كما يمكنه النشر في Slack أو Discord، وإرسال بريد إلكتروني أو رسالة SMS أو رسالة WhatsApp. اجمع بين الاثنين: الواجهة البرمجية للإنشاء والقراءة، وسير العمل لإخطار نظامك عند وقوع حدث ما.
قائمة التحقق قبل الإطلاق
- أنشئ مفتاحًا لكل متجر بأقل عدد من الصلاحيات، واحتفظ به على الخادم فقط.
- أرسل external_id مع كل طلب، واعتبر 201 و200 كلاهما نجاحًا.
- استخدم رموز SKU مطابقة لكتالوج Cashod، أو أنشئ المنتجات أولًا.
- اترك confirmed معطّلًا ما لم تكن قد أكدت الطلب فعلًا مع الزبون.
- تعامل مع الرمز 429 بانتظار متدرّج، واقرأ الحقل error.type.
- تابع next_cursor إلى أن تصبح قيمة has_more هي false.
- جدول مهمة استعلام دوري للحالات والتتبع، أو ويب هوك في سير عمل للأحداث.
- اختبر المسار كاملًا بطلب حقيقي واحد: الإنشاء، التأكيد، الشحن، ثم قراءة رقم التتبع.
الأسئلة الشائعة
هل ترسل واجهة Cashod البرمجية ويب هوك؟
لا. اقرأ الحالات بطلبات GET، أو استخدم إجراء الويب هوك في سير عمل لاستدعاء رابطك.
أدير عدة متاجر. هل أحتاج إلى عدة مفاتيح؟
نعم. المفاتيح خاصة بكل متجر، مما يفصل بيانات كل متجر وصلاحيات الوصول إليه.
أين أجد المرجع الكامل؟
في بوابة المطورين، مع الأدلة والمرجع التفاعلي ومواصفة OpenAPI.
ابدأ الآن
افتح توثيق المطورين، وأنشئ مفتاحك الأول من الإعدادات ← المطورون، ثم أرسل طلبًا تجريبيًا. ولاختيار خطة حسب عدد المتاجر والطلبات الشهرية، اطّلع على الأسعار.
