راهنمای پیاده‌سازی وب‌هوک

مستند فنی وب‌هوک دیجی‌اکسپرس

پس از پیاده‌سازی APIهای موردنیاز، مرحله بعدی در فرآیند Integration، پیاده‌سازی Webhook است.

دیجی‌اکسپرس تمامی رویدادهای مهم از جمله نتیجه مسیریابی (موفق یا ناموفق) و همچنین تغییرات وضعیت سفارش‌ها و بسته‌ها در طول فرآیند عملیاتی را از طریق Webhook اطلاع‌رسانی می‌کند.

مکانیزم اطلاع رسانی های دیجی‌اکسپرس

دیجی‌اکسپرس برای اطلاع‌رسانی در خصوص «مسیریابی موفق یا ناموفق» و «هرگونه تغییر وضعیت در چرخه لجستیکی سفارش‌ها و بسته‌ها»، درخواست‌های خود را در قالب متدهای POST یا PUT به آدرس (URL) معرفی‌شده از سمت شما ارسال می‌کند.

توالی و زمان‌بندی ارسال رویدادها (Event Sequencing)

رعایت توالی: ترتیب رویدادهای لجستیکی رخ‌داده برای هر مرسوله همواره رعایت شده و ایونت‌ها به صورت ترتیبی ارسال می‌شوند.

احتمال تاخیر: به هر دلیلی ممکن است سرویس ارسال آپدیت‌ها در بستر وب‌هوک با اختلال موقت مواجه شود و این اطلاع‌رسانی‌ها با تاخیر به سمت شما ارسال گردند.

پاسخ مورد انتظار سرور فرستنده (Consignor Response)

• پاسخ موفق: در صورت دریافت و پردازش موفقیت‌آمیز پیلود وب‌هوک، سرور شما باید کد وضعیت 200 OK برگرداند.
• پاسخ ناموفق: در غیر این صورت (بروز هرگونه خطا)، باید کد خطای متناسب (Error Code) به همراه متن ریسپانس به دیجی‌اکسپرس بازگردانده شود.
• عدم وجود مکانیزم تکرار (No Retry Policy): در حال حاضر هیچ‌گونه مکانیزم (Retry) در سیستم وجود ندارد؛ یعنی در صورتی که آپدیت‌های ارسالی به هر دلیلی توسط سرور فرستنده دریافت نشوند، مجدداً ارسال نخواهند شد.

الزامات و قواعد توسعه در سمت فرستنده (Consignor Development Requirements)

• انعطاف‌پذیری در برابر مقادیر جدید: سیستم پذیرنده شما باید کاملاً منعطف طراحی شود. در صورت مواجهه با فیلدها، پارامترها یا Progress Typeهای ناشناخته و جدید در آینده، سیستم نباید دچار اختلال یا کرش (Crash) شود و صرفاً باید آن‌ها را نادیده (Ignore) بگیرد.
• توسعه‌پذیری پیلودها: این احتمال وجود دارد که در آینده فیلدهای جدیدی به پیلودهای فعلی اضافه شوند یا پیلودهای عملیاتی کاملاً جدیدی توسعه یافته و از طریق وب‌هوک ارسال گردند؛ ساختار سیستم شما باید پذیرای این تغییرات باشد.
• نکته بسیار مهم (عدم وابستگی به لاجیک‌های ترتیبی): به هیچ عنوان نباید فرآیندهای وب‌هوک را به لاجیک‌ها و اعتبارسنجی‌های ترتیبی در دیتابیس یا سیستم خود مشروط کنید. به عنوان مثال، نباید این منطق را قرار دهید که «حتماً اول باید ایونت در حال ارسال (Delivering) دریافت شود تا سیستم اجازه ثبت ایونت تحویل شد (Delivered) را بدهد». به دلایل مختلف عملیاتی در زنجیره تأمین، ممکن است برخی از وضعیت‌های میانی به صورت سیستمی نادیده گرفته شده (Skip) و مستقیم وب‌هوک نهایی (مانند Delivered) ارسال شود؛ در این حالت سیستم شما نباید خطایی صادر کند.

سرویس فید وب‌هوک (Webhook Feed API)

اگر سرور کانساینر به هر دلیلی قطع (Down) باشد و وب‌هوک‌های ارسالی را دریافت نکرده یا در سیستم خود ذخیره نکرده باشد، برای بازیابی و دریافت داده‌های مفقودشده از این متد استفاده می‌شود.

نمونه درخواست (Request Body):

{
  "shipment_ids_or_shipment_consignor_reference_ids": [
    "string"
  ]
}

جدول پارامترهای ورودی (Request Parameters)

ساختار پاسخ سرویس فید وب‌هوک (Webhook Feed Response)

این ریسپانس لیستی از سفارش‌ها را به همراه بسته‌ها و تمامی تاریخچه ایونت‌های وب‌هوکی که پیش از این برای آن‌ها رخ داده یا تلاش شده (Try)، به صورت یکجا و ساختاریافته به شما نمایش می‌دهد.

{
  "shipments": [
    {
      "order_id": "string",
      "shipment_id": "string",
      "shipment_consignor_reference_id": "string",
      "parcels": [
        {
          "parcel_id": "string",
          "parcel_code": "string",
          "parcel_reference_id": "string",
          "events": [
            {
              "payload": [
                "string"
              ],
              "tries": [
                {
                  "response_code": "string",
                  "response_body": "string",
                  "called_at": "string"
                }
              ],
              "succeeded": true,
              "webhook_event_id": "string",
              "created_at": "string",
              "progress_type": "string",
              "sequence_number": 0
            }
          ]
        }
      ],
      "other_events": [
        {
          "payload": [
            "string"
          ],
          "tries": [
            {
              "response_code": "string",
              "response_body": "string",
              "called_at": "string"
            }
          ],
          "succeeded": true,
          "webhook_event_id": "string",
          "created_at": "string",
          "progress_type": "string",
          "sequence_number": 0
        }
      ]
    }
  ]
}

جدول اجزای اصلی دیتای پاسخ (Response Object Layers)

جدول جزئیات اطلاعات سطح بسته (parcels)

جدول ساختار رویدادها (events & other_events)

هر آبجکت در آرایه events یا other_events نشان‌دهنده یک ایونت وب‌هوک ارسال‌شده (یا تلاش‌شده) است و فیلدهای زیر را شامل می‌شود:

ساختار فیلدهای پیلود وب‌هوک (Payload Structure)

تمامی اطلاع‌رسانی‌های عملیاتی به صورت مجزا به ازای هر بسته (Per Parcel) ارسال می‌شود.

شناسه‌ها و فیلدهای زمانی اصلی

• occurred_at: زمان دقیق وقوع رویداد یا تغییر وضعیت لجستیکی.
• shipment_id: شناسه یکتا و سیستمی سفارش در دیجی‌اکسپرس.
• reference_id: کد مرجع ارسالی توسط شما در زمان ثبت سفارش (consignor_unique_reference_id).
• parcel_id: شناسه اختصاصی هر بسته در دیجی‌اکسپرس.

occurred_at زمان وقوع رویداد عملیاتی است. created_at در Webhook Feed زمان ثبت یا ایجاد Webhook Event در سیستم دیجی‌اکسپرس را نشان می‌دهد.

فیلدهای وضعیتی و لاگین عملیاتی

• shipment_status: وضعیت کلی و کلان سفارش (مانند Delivering ،Delivered ،Canceled).
• parcel_status: وضعیت اختصاصی بسته فیزیکی.
• progress_type: دقیق‌ترین لایه وضعیتی رویداد (مانند Pickup ،Inbound و...).

اطلاعات موقعیتی و ارتباطی

• point_name: نام هاب یا انبار جاری پذیرش‌کننده بسته (Inbound / Outbound).
• is_final_point: مقدار بولین (True/False)؛ مشخص می‌کند انبار جاری آخرین ایستگاه پیش از توزیع به مشتری است یا خیر.
• pod_code: کد تحویل مرسوله (تولیدشده توسط کلاینت در مرحله ثبت، یا تولید خودکار سیستم در مرحله پیدا شدن مسیر).
• sms_content: متن کامل پیامک ارسال‌شده به مشتری در صورت بروز وضعیت SMSWasSent.

مقادیر، ابعاد و فرآیند رزرو ظرفیت

• weight / volume: وزن و حجم بسته.
• estimated / remaining: میزان کل ظرفیت رزرو شده بر اساس فیلدهای تخمین ظرفیت و میزان باقی‌مانده آن پس از معرفی بسته‌های نهایی.
• cod_amount: مبلغ نقدی قابل دریافت در محل از مشتری (Cash on Delivery).

فیلدهای مدیریت عدم موفقیت (Failure Reasons)

• pickup_failure_reason: علت عدم موفقیت در جمع‌آوری بسته از مبدا.
• last_mile_failure_reason: علت عدم موفقیت در تحویل بسته به مشتری نهایی.
• return_failure_reason: علت عدم موفقیت در بازگرداندن بسته به انبار فرستنده.

نگاشت دقیق مقادیر وضعیت‌ها (Shipment Status & Progress Type Map)

لایه ثبت سفارش (Register) و مدیریت ظرفیت

• AwaitingForCandidateRoutesInquiryResult | RequestedRouteForEstimatedCapacity سفارش بدون پارسل ثبت شده و در حال بررسی اولیه ظرفیت است.
• AwaitingForRouteSelectionAmongFoundOnes | FoundCandidateRouteToSelectForEstimatedCapacity مسیرهای پیشنهادی یافت شده و سیستم در انتظار انتخاب مسیر است.
• AwaitingForSelectedRouteToBeStarted | ParcelSelectedInitialRoute بعد از تایید نهایی مسیر پیدا شده (ثبت سفارش موفق).
• SittingIdleDueToRegistrationFailure | RouteRequestFailedForEstimatedCapacity / ParcelRouteRequestFailed عدم امکان ثبت سفارش به دلیل مشکلات سیستم یا تایم‌اوت.
• SittingIdleCauseNoRoutesWereFound | NoRouteWereFoundForEstimatedCapacity / ParcelNoRouteWereFound رد سفارش به دلیل عدم یافتن مسیر یا پر بودن ظرفیت.

لایه اضافه و حذف بسته (Add & Remove Parcel)

• AwaitingForSelectedRouteToBeStarted | ParcelWasAddedToShipment پارسل با موفقیت به سفارش اضافه شد و در انتظار شروع بازه ارسال است.
• AwaitingForSelectedRouteToBeStarted | ParcelWasRemovedFromShipment پارسل از سفارش حذف شد (در صورتی که سفارش همچنان بسته‌های دیگری داشته باشد).
• AwaitingForAddingParcel | ParcelWasRemovedFromShipment پارسل حذف شد و سفارش مجدداً در وضعیت انتظار برای افزودن بسته قرار گرفت.
• SittingIdleCauseNoParcelWasAddedToShipment | NoParcelWasAddedToShipment زمان پیکاپ شروع شده اما هیچ پارسلی به سفارش اضافه نشده؛ فرآیند متوقف گردید.

لایه فرآیند ارسال و توزیع (Delivering & Delivered)

• InTheRoadBeingDelivering | InPersonReceiveFailed: عدم دریافت بسته در مرکز سورت (رسپشن فیل).
• InTheRoadBeingDelivering | PickedUp: جمع‌آوری موفقیت‌آمیز مرسوله از فرستنده.
• InTheRoadBeingDelivering | InPersonReceived: تحویل سفارش در انبار/کانتر توسط خود فرستنده.
• InTheRoadBeingDelivering | PickupEnd: اتمام راید جمع‌آوری (پیکاپ).
• InTheRoadBeingDelivering | DidInboundInPoint: پذیرش فیزیکی بسته در هاب یا شعبه.
• InTheRoadBeingDelivering | DidOutboundFromPoint: خروج فیزیکی بسته از هاب یا شعبه.
• InTheRoadBeingDelivering | MidMileRideStart: شروع سفر میانی بین‌شهری یا بین‌انباری.
• InTheRoadBeingDelivering | MidMileRideEnd: پایان سفر میانی و رسیدن ناوگان به مقصد واسط.
• InTheRoadBeingDelivering | InPersonHandedOver: خروج مرسوله از شعبه جهت تحویل حضوری به مشتری (In-Person).
• InTheRoadBeingDelivering | LastMileRideStart: شروع حرکت سفیر تحویل به سمت مشتری (لست‌مایل).
• InTheRoadBeingDelivering | LastMileRideEnd: پایان راید توزیع نهایی.
• InTheRoadBeingDelivering | FinalRide: شروع آخرین مرحله حرکت ناوگان تحویل.
• InTheRoadBeingDelivering | ParcelWasDeliveredToRecipient: تحویل موفقیت‌آمیز یک بسته از سفارش به مشتری.
• WasDeliveredToRecipient | ParcelWasDeliveredToRecipient: تحویل موفقیت‌آمیز تمامی بسته‌های سفارش و اتمام فرآیند.

لایه عدم موفقیت، لغو، هماهنگی و عودت (Failures, Cancel & Returns)

• PickupFailed | ParcelPickupFailed: عدم موفقیت در جمع‌آوری مرسوله از فرستنده (قبل از پیکاپ).
• ConsignorCanceledBeforeInPersonReceiveOrPickup | ParcelCancelledByConsignorBeforeDeliveringStarted: لغو سفارش به درخواست کلاینت قبل از پیکاپ یا رسید در هاب.
• ConsignorCanceledAfterInPersonReceiveOrPickup | ParcelCancelledByConsignorWhileDelivering: لغو سفارش پس از پیکاپ یا دریافت مرسوله (بسته وارد چرخه عودت می‌شود).
• InTheRoadBeingDelivering | ParcelFailedToBeDelivered: عدم تحویل موفق بسته به مشتری (ورود به فرآیند کال‌سنتر).
• InTheRoadBeingDelivering | ParcelWasCoordinatedToCustomer: ثبت زمان یا آدرس جدید تحویل پس از تماس پشتیبانی با مشتری.
• InTheRoadBeingDelivering | ParcelWasCoordinatedToConsignorLatLngAddress: هماهنگی عودت بار به آدرس/لوکیشن فرستنده.
• InTheRoadBeingDelivering | ParcelWasCoordinatedToConsignorInPersonShippingPoint: هماهنگی جهت تحویل حضوری عودت توسط فرستنده در پوینت.
• InTheRoadBeingDelivering | ParcelWasReturnedToConsignor: بازگشت موفقیت‌آمیز یک بسته مرجوعی به فرستنده.
• Returned | ParcelWasReturnedToConsignor: بازگشت تمامی بسته‌ها به فرستنده و اتمام چرخه عودت سفارش.
• InTheRoadBeingDelivering | CustomerDidNotAnswerToNegotiateCoordination: عدم پاسخگویی مشتری به تماس کال‌سنتر برای تعیین زمان جدید.
• InTheRoadBeingDelivering | SMSWasSent: اطلاع‌رسانی ارسال موفقیت‌آمیز پیامک به مشتری.
• InTheRoadBeingDelivering | LastMilestoneProviderBarcode: بارکد پستی مرسوله.

جداول دلایل عدم موفقیت (Failure Reasons Enums)

دلایل عدم موفقیت در جمع‌آوری (pickup_failure_reason)

دلایل عدم موفقیت در تحویل به مشتری (last_mile_failure_reason)

عودت ناموفق به فرستنده (return_failure_reason)

در صورتی که بسته فیزیکی به انبار شما برسد اما به دلایلی (مانند بسته بودن انبار) نتوانید آن را دریافت کنید، وب‌هوک با این فیلد ارسال شده و چرخه هماهنگی عودت (Coordinated to Consigner) مجدداً تکرار می‌گردد.

لینک مستندات جانبی وب‌هوک دیجی‌اکسپرس

برای دسترسی به دیتای دقیق‌تر، نمونه پیلودها و کدهای وضعیت وب‌هوک که ممکن است در این داک به آن‌ها اشاره نشده باشد، لطفاً از طریق لینک مستندات جانبی وب‌هوک دیجی‌اکسپرس آخرین نسخه جداول فنی را بررسی نمایید.

پیوست اول: جدول رویدادهای وب‌هوک و پیامک‌های اطلاع‌رسانی متناظر

کنساینرهای محترم می‌توانند با استفاده از جدول زیر، ارتباط بین رویدادهای ارسالی در پیلود وب‌هوک (Progress Types) و پیامک‌های سیستم دیجی‌اکسپرس را جهت مپینگ و فرآیندهای کاستومر سرویس خود بررسی نمایند.