اربطوا أدواتكم بالطلبات والمخزون المتاح وتتبع الشحنات باستخدام REST API وTypeScript SDK وwebhooks.
افتحوا بوابة المطوّرين للاطلاع على واجهات API المتاحة لحسابكم وSDK المتوفر في بيئتكم. يلزم تسجيل الدخول وامتلاك صلاحيات الحساب المناسبة.
حزمة TypeScript SDK
مثال TypeScript يعمل على الخادم ويستخدم عميل Ysend لوظائف الأعمال. اضبطوا عنوان API الأساسي المتفق عليه عند الإعداد، واحتفظوا بمفتاح API في متغيرات البيئة على الخادم.
import { Ysend } from "@ysend/sdk";
const ysend = new Ysend({
baseUrl: process.env.YSEND_API_BASE_URL!,
apiKey: process.env.YSEND_API_KEY!,
});
const stock = await ysend.inventory.listBalances({ page: 1, pageSize: 20 });
const orders = await ysend.orders.list({ status: "Open", page: 1, pageSize: 20 });
const shipments = await ysend.shipments.list({ page: 1, pageSize: 20 });يتطلب المثال صلاحيات inventory:read وorders:read وshipments:read. لعمليات الكتابة عبر SDK، قدّموا مفتاح Idempotency-Key ثابتاً للسماح بإعادة المحاولة دون إنشاء عملية ثانية.
استخدموا Node.js 20 أو إصداراً أحدث. إذا كانت البوابة توفر SDK، فسجّلوا إصداره واسم الملف، ثم تحقّقوا من قيمة SHA-256 للملف الذي نزّلتموه. استبدلوا PACKAGE_FILE.tgz أدناه باسم الملف نفسه تماماً.
npm install ./PACKAGE_FILE.tgzيجب أن يتضمن YSEND_API_BASE_URL عنوان أصل API المتفق عليه: بروتوكول HTTPS واسم المضيف، دون /api/v1. يضيف SDK هذا المسار. احتفظوا بـ YSEND_API_KEY على الخادم؛ تستخدم الطلبات X-Api-Key.
يعيد كل استدعاء لقائمة صفحة واحدة. حدّدوا page وpageSize، ثم افحصوا items وtotalCount وpage وpageSize عند توفرها قبل طلب المزيد. الصفحة الأولى ليست تصديراً كاملاً.
يوفر YsendError حالة HTTP وتفاصيل detail ومعرّف traceId المتاحة. ويعني YsendTransportError عدم تلقي استجابة قابلة للاستخدام؛ وقد تكون نتيجة عملية الكتابة عندها غير معروفة.
الإعدادات الافتراضية: ثلاث محاولات إجمالاً، وانتظار ترويسات الاستجابة لمدة 30 ثانية في كل محاولة. يمكن إعادة محاولات GET/HEAD والطلبات التي تتضمن Idempotency-Key بعد خطأ في الشبكة أو حالة HTTP 429 أو 502 أو 503 أو 504. أعيدوا استخدام المفتاح نفسه للعملية نفسها. يستخدم orders.list طلب POST دون هذا المفتاح، ولذلك لا تُعاد محاولته تلقائياً بهذه الآلية.
اشرحوا أدواتكم والبيانات التي ترغبون في تبادلها ضمن استفساركم عن التكامل. يساعدكم فريقنا على تحديد وثائق API وSDK وصلاحيات الوصول المناسبة لمؤسستكم. لا ترفقوا أسراراً أو مفاتيح سرية.
البدء
بعد تفعيل الحساب، ينشئ مسؤول مخوّل مفتاحاً بالصلاحيات التي يحتاجها التكامل.
إذا نُشرت حزمة SDK لبيئتكم، فنزّلوها من بوابة المطوّرين، وتحقّقوا من قيمة SHA-256، ثم ثبّتوا الملف الذي نزّلتموه.
اقرؤوا بيانات المخزون والطلبات والشحنات بالصلاحيات الممنوحة لمفتاحكم.
إشعارات webhooks
أنشئوا الاشتراكات في تطبيق الويب، واختبروها بإرسال ping، وراجعوا محاولات التسليم. يعيد صندوق الصادر محاولة الإخفاقات المؤهلة؛ وتبقى الأحداث التي استنفدت محاولاتها ظاهرة في قائمة الرسائل المتعذّر تسليمها.
نطاق التكامل
استوردوا ملف CSV أو صفوفاً منظّمة؛ وافحصوا الصفوف المرفوضة وصحّحوها وأعيدوا إرسالها.
اربطوا رموز SKU، واقرؤوا كميات المخزون الفعلية والمحجوزة والمتاحة.
جهّزوا خطط الوارد، وأضيفوا البنود، واطلبوا مواعيد التسليم، وتابعوا فروقات الاستلام.
اطّلعوا على الناقل والتتبع وحالة التسليم بعد أن ينشئ سير تجهيز الطلب الشحنة.
افتحوا حالة مرتبطة بطلب وأرفقوا الصور أو المستندات.
اقرؤوا الاشتراكات وسجل التسليم من خلال تكاملكم.
مفاتيح الشركاء
احتفظوا بالمفاتيح على خادمكم. تحدد صلاحيات الحساب والشريك كل عملية؛ ويتولى المسؤولون المخوّلون إنشاء المفاتيح وتدويرها وإعداد webhooks في البوابة المناسبة.
جهّزوا وصف تدفق بياناتكم والعمليات المطلوبة. سنؤكد صلاحيات الحساب ونطاقات الوصول وحزمة SDK المناسبة لتكاملكم.
يساعدكم فريق Ysend على اختيار الخدمات والتكاملات وخطة التنفيذ المناسبة لأعمالكم.