من مفتاح Sandbox إلى مرتجع مكتمل

ابدأ بـ البدء السريع مع API. استخدم مشروع Sandbox مخصصًا واحدًا لهذه الوصفات. تسجّل Alkax تقدّم التوصيل والإرجاع المادي. ويتولى نظام التجارة لديك الأموال المستردة والمخزون والاستبدال ورصيد العميل.

بيانات الاعتماد والبيئات

مضيف API هو https://api.alkax.io. تُختار Sandbox أو Production حسب بيئة بيانات الاعتماد، لا حسب مسار URL. لا تضع مفتاح مطوّر في كود المتصفح أو الهاتف. يختلف رمز وصول حساب Alkax عن بيانات اعتماد X-Alkax-Key.

العملية	النطاق
إنشاء شحنة أو مرتجع مرجعي	delivery:create
قراءة الحالة الخاصة للشحنة أو المرتجع	delivery:read
إرسال أحداث التوصيل والإرجاع؛ تسجيل استلام الإيداع	delivery:events
إرسال الدليل أو أصول دليل الإرجاع	delivery:proof
تأكيد العنوان واعتماد المرتجع المرجعي أو رفضه أو إلغاؤه والوصول للاستلام ومعالجة RTS	delivery:write

يحتاج التكامل الكامل للتوصيل والإرجاع إلى النطاقات التي تتطلبها عملياته. يحافظ التدوير على نطاقات المفتاح السابق، لذا لا يغيّر إصدار مفتاح جديد مجموعة النطاقات المخوّلة. قد يمنع غياب نطاق الدليل نجاح حدث الإكمال المعتمد عليه. انسخ المفتاح الخام فقط. راجع استكشاف المشكلات.

دورة حياة الشحنة الصادرة

بعد تأكيد العنوان، استخدم اللقطة المؤكّدة غير القابلة للتعديل كـ destination في POST /api/v1/deliveries. قدّم Idempotency-Key وactivationEventId ثابتًا. يعيد الإنشاء id وtrackingNumber والحالة. لا تفترض أن مرجع الطلب الخارجي هو رقم تتبّع Alkax.

أرسل POST /api/v1/deliveries/{id}/events مع UUID ثابت في eventId وطابع زمني فعلي occurredAt وأحد الأوامر التالية:

الأمر	النتيجة
MarkInTransit	InTransit
MarkAtLocalDepot	AtLocalDepot
MarkOutForDelivery	OutForDelivery
RecordDeliveryAttempt	DeliveryAttempted
CompleteDelivery	Delivered

أعد الحدث نفسه تمامًا بعد إخفاق النقل. تحتاج 409 إلى فحص الحالة المرجعية؛ لا تخترع معرّفًا جديدًا لتجاوز فحوص التعارض. تُرفض الطوابع الزمنية التي تتجاوز الوقت الحالي بأكثر من خمس دقائق. معرّفات الأحداث منفصلة عن معرّفات الطلبات المستخدمة للتشخيص. لا تعتمد على جمل الأخطاء المترجمة.

لدليل الشحنة الصادرة، أرسل أولًا POST /api/v1/deliveries/{id}/proofs مع proofId ثابت وmethod وoccurredAt وحقول المستلم والمرجع المطلوبة. قدّم proofId هذا إلى CompleteDelivery. أرسل الدليل قبل الحدث المعتمد عليه. يجب أن ينتمي الدليل إلى الشحنة والبيئة نفسيهما؛ ولدليل الإرجاع عقد منفصل.

وصول المستلم

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

يمكن للمستلم المرتبط طلب الإرجاع فقط بعد بلوغ الشحنة Delivered. في «توصيلاتي»، اختر الاستلام أو الإيداع وقدّم سببًا. يبقى الطلب معلّقًا حتى اعتماده أو رفضه. يظل الإيداع المعتمد بحاجة إلى تسجيل الاستلام المادي. يُدعم طلب واحد لكل طرد صادر والقرارات نهائية.

تفويض التاجر للإرجاع

يقبل POST /api/v1/returns الحقول originalShipmentId وeventId وtype وreason وdestination، وorigin والتعليمات، وكلاهما اختياري، ومتطلبات دليل الاستلام والوصول. استخدم type: RecipientReturn وreason: RecipientChangedMind لأبسط مسار عميل. يتطلب إرجاع العميل شحنة صادرة بحالة Delivered. إذا حُذفت نقطة الأصل، تُشتق من لقطة الشحنة الصادرة لا من بحث عنوان قابل للتغيّر.

التفويض منفصل عن اللوجستيات. تحتاج مرتجعات العملاء المطلوبة إلى POST /api/v1/returns/{id}/approve?eventId={uuid}. يستخدم الرفض والإلغاء قاعدة معرّف الاستعلام نفسها. يقتصر الإلغاء على ما قبل التسليم المادي. يبدأ المرتجع المعتمد عند AwaitingHandover؛ ولا تحدّد الموافقة وحدها موعدًا لمندوب.

أكّد الاستلام وأرسل دليل الإرجاع

1. استدعِ POST /api/v1/returns/{id}/pickup-confirmation بالنطاق delivery:write.
2. سلّم رابط المستلم المُعاد بأمان. يلغي إصدار بديل الرابط السابق غير المكتمل. لا تسجّل رمزه ولا تكشفه في التتبّع العام.
3. يراجع المستلم موقع الاستلام أو يصحّحه عبر مسار الرمز العام. تبقى اللقطة المؤكّدة منفصلة عن وجهة الشحنة الصادرة الأصلية.
4. إذا لزم دليل، التقط توقيعًا أو صورة PNG فعلية. ارفعها باستخدام PUT /api/v1/returns/{id}/proof-assets/{proofId}/signature (أو /photo) مع { "dataUrl": "data:image/png;base64,..." }. الحد الأقصى 2 ميغابايت و2048 × 2048 بكسل.
5. استخدم reference المُعاد في POST /api/v1/returns/{id}/proofs مع proofId نفسه وpurpose: Pickup أو Receipt والطريقة والطابع الزمني. تتطلب طرق التوقيع معلومات المستلم. لا تُعد النصوص العشوائية أو عناوين URL للتاجر بدائل صالحة لأصول المرتجع المرفوعة.
6. أرفق معرّف الدليل في حدث التسليم أو الإكمال المقابل.

يجب أن تستخدم إعادة رفع الأصل البايتات نفسها تمامًا. لا يفي دليل استلام المرتجع من العميل بمتطلبات وصوله، ولا يمكن لأي منهما إعادة استخدام دليل الشحنة الصادرة. تتطلب الأصول الخاصة delivery:proof ومطابقة المشروع والبيئة عند القراءة والكتابة معًا.

اللوجستيات العكسية والإرجاع إلى المرسل بعد فشل التوصيل

أرسل أحداث المرتجع بمعرّفات ثابتة إلى /api/v1/returns/{id}/events: وهي SchedulePickup وMarkPickedUp وMarkAtReturnHub وMarkInTransit وComplete. ينتج Complete الحالة DeliveredToMerchant لإرجاع العميل وReturnedToSender لفشل التوصيل. يسجّل RecordException استثناءً لوجستيًا؛ ولا يمنح إذنًا لإعادة كتابة التاريخ.

لشحنة بحالة DeliveryAttempted، استدعِ POST /api/v1/deliveries/{id}/resolution مع evaluationId ثابت وfailureReason موحّد وattemptCount موجب وreturnDestination مؤكّدة عندما يكون RTS ممكنًا. تختار السياسة الموثّقة RTS عند الرفض أو عدم توفر المستلم بعد ثلاث محاولات أو مشكلة دفع بعد محاولتين. تحتاج مشكلات العنوان إلى تصحيح، وتُحال الإخفاقات غير المعروفة إلى مراجعة يدوية. تُزال تكرارات الأدلة الموحّدة. لا تمرّر نص إخفاق شركة النقل الخام كسبب مرجعي.

تستخدم قراءات المرتجعات الخاصة /api/v1/returns/{id} أو /by-tracking/{trackingNumber}. ويحذف المسار المجهول /api/public/returns/{trackingNumber} بيانات الاتصال والموقع الدقيق والتعليمات والأدلة.

حدود المسؤولية والثقة

Merchant server -- scoped environment key --> Alkax API
Recipient      -- expiring capability ----> Confirm address / pickup
Recipient      -- verified account -------> Linked delivery / return request
Public viewer  -- tracking number --------> Coarse progress only
Alkax webhook  -- signed raw body --------> Merchant webhook receiver
Merchant system -- own business policy ---> Refund / inventory system

لـ Sandbox وProduction بيانات اعتماد وموارد واشتراكات خطافات ويب منفصلة. لا ينقل خطاف ويب الإذن إلى بيئة أخرى. راجع وصفات خطافات الويب وقائمة تحقّق الإطلاق.

استخدم مصفوفة اختبارات Sandbox لحالات التصحيح وانتهاء الصلاحية والرفض والنطاق الخاطئ وإعادة التشغيل.