مستندات فنی اتصال به سرویس‌های لجستیکی دیجی‌اکسپرس
معرفی کلی سرویس و الزامات یکپارچه‌سازی (Integration)
به مستندات پیاده‌سازی سرویس‌های لجستیکی دیجی‌اکسپرس خوش آمدید. سرویس DigiExpress API به کسب‌وکارهای خارجی (Consignors) امکان می‌دهد ارسال‌های خود را به صورت برنامه‌ریزی‌شده در سیستم ثبت، مدیریت و ردیابی کنند.
مفاهیم پایه و تعاریف لجستیکی
پیش از شروع کدنویسی، آشنایی با اصطلاحات زیر برای درک بهتر ساختار سرویس ضروری است:
| مفهوم | تعریف عملیاتی |
|---|---|
| Consignor | کسب‌وکار یا پلتفرم واسطی که از این API برای ارسال سفارش‌های خود استفاده می‌کند. |
| Shipment | هر سفارش شما که دقیقاً دارای یک مبدأ و یک مقصد مشخص است که میتواند شامل یک یا چند بسته ( پارسل ) باشد |
| Parcel | بسته‌های فیزیکی تشکیل‌دهنده سفارش؛ هر Shipment میتواند شامل حداقل یک و حداکثر 100 پارسل (بسته) باشد. |
پیش‌نیازهای فنی و فرآیندی اینتگریشن (Integration Prerequisites)
اطلاعاتی که کانساینر باید ارسال کند
- لیست IPهای سرور خود: آدرس‌های IP سرورهای محیط Demo و Production خود را جهت اعمال در فایروال دیجی‌اکسپرس (Whitelist) ارسال کنید.
محدودیت فنی: برای هر محیط (Demo / Production) حداکثر امکان ثبت 2 آدرس IP یکتا (Single IP) وجود دارد. لطفاً توجه داشته باشید که سیستم فایروال از ثبت آدرس‌ها به صورت رنج یا ساب‌نت (مانند CIDR Range) پشتیبانی نمی‌کند و آدرس‌ها باید به صورت تکی اعلام شوند.
- شماره تلفن همراه ادمین: شماره همراهی که قصد دارید حساب کاربری شما با آن ایجاد شود را اعلام کنید.
- تنظیمات و اطلاعات وب‌هوک (Webhook): جهت دریافت آنی وضعیت مرسولات، یکی از دو مورد زیر را ارسال کنید:
آدرس وب‌هوک (Webhook URL) به همراه توکن احراز هویت (Authorization token) یا ساختار هدر امنیتی مورد نظرتان در Header Request.
یا یک نمونه دستور CURL آماده و تست‌شده برای دریافت رویدادها (همراه با هدرهای اجباری سرور شما).
اطلاعات محیط‌های فنی دیجی‌اکسپرس (جهت تنظیمات کانساینر)
برای ارسال درخواست‌ها و همچنین Whitelist کردن IPهای دیجی‌اکسپرس روی سرور خود، از اطلاعات زیر استفاده کنید:
| محیط (Environment) | آدرس پایه (Base URL) | آدرس آی‌پي (IP Address) |
|---|---|---|
| محیط تست (Demo) | demo-digiexpress.digikala.com | 93.113.225.84 93.113.225.2 |
| محیط عملیاتی (Production) | digiexpress.digikala.com | 93.113.225.114 |
انتخاب سناریوی ثبت مرسوله (Shipment Registration)
ثبت سفارش در دیجی‌اکسپرس از طریق یک API واحد انجام می‌شود، اما با توجه به مدل پردازش انبار خود، می‌توانید به دو روش مختلف از آن استفاده کنید. لطفاً سناریوی مدنظر خود را انتخاب فرمایید:
روش اول: ثبت با پارسل‌های مشخص (Register with Specified Parcels)
- کاربرد: پرکاربردترین روش ثبت است؛ مخصوص زمان‌هایی که در لحظه ثبت درخواست، تعداد دقیق بسته‌ها (Parcels) و مشخصات فیزیکی آن‌ها کاملاً معلوم است.
- ویژگی کلیدی: مشخصات فیزیکی تمام پارسل‌ها در لایه بدنه (Payload) همان درخواست اول ارسال می‌شود.
- محدودیت: پس از دریافت پاسخ موفق، امکان حذف، اضافه یا ویرایش پارسل‌ها در آن شیپمنت وجود ندارد.
روش دوم: ثبت با ظرفیت تخمینی (Register Estimated)
- کاربرد: مخصوص بیزینس‌هایی که در لحظه ثبت سفارش، تعداد دقیق بسته‌ها را نمی‌دانند (تعداد بسته فیزیکی بعداً در حین فرآیند جمع‌آوری و بسته‌بندی در انبار شما شکل می‌گیرد).
- ویژگی کلیدی: در درخواست اول، مشخصات پارسل فرستاده نمی‌شود؛ بلکه فقط یک تخمین کلی از وزن و حجم کل سفارش ارسال می‌شود تا ظرفیت برای شما رزرو گردد.
- ویژگی کلیدی: پس از ثبت موفق شیپمنت، هرزمان که یک بسته فیزیکی در انبار شما آماده شد، می‌توانید با استفاده از APIهای Add و Remove پارسل، بسته‌ها را به مرور به این مرسوله اضافه یا کم کنید.
بازه‌های زمانی ارسال (Shipping Time Window)
اگر می‌خواهید مانند تجربه خرید از دیجی‌کالا، بازه‌های زمانیِ قابل ارسالِ دیجی‌اکسپرس را به مشتری نهایی خود در سایت یا اپلیکیشن نشان دهید تا خودش زمان تحویل را انتخاب کند، فرآیند شما دو مرحله‌ای خواهد بود:
- ابتدا API اختصاصی Shipping Time Window را کال کرده و بازه‌های مجاز را دریافت و به کاربر نمایش می‌دهید.
- پس از انتخاب زمان توسط مشتری، API اصلی ثبت مرسوله را همراه با زمان انتخابیِ کاربر صدا می‌زنید.
زمان مشخص شدن موفقیت یک درخواست و دریافت لیبل
درک تفاوت فلوهای همزمان (Sync) و غیرهمزمان (Async) برای هندل کردن فرآیند چاپ لیبل در سیستم شما حیاتی است. بعضی از سناریو های رجیستر ما به صورت sync فرآیند ها را پیش میبرند و طبیعاتا پاسخ دهی بسیار سریع تری به کانساینر خواهیم داشت ولی بعضی از سناریو ها Async هستند و دریافت پاسخ از سمت دیجی‌اکسپرس ممکن است زمان بر باشد. در ادامه حالت های مختلف را مشاهده میکنید.
| سناریوی پیاده‌سازی | نوع فرآیند | نحوه نهایی شدن سفارش و امکان دریافت لیبل |
|---|---|---|
| ثبت تک مرحله‌ای (چه Specified و چه Estimated) | Async (غیرهمزمان) | دریافت ریسپانس 200 یعنی درخواست شما دریافت شده و در صف پردازش مسیریابی است. نتیجه قطعی (ثبت موفق یا ریجکت) 2 الی 5 دقیقه بعد از طریق وب‌هوک ارسال می‌شود. بنابراین بلافاصله امکان دریافت لیبل وجود ندارد و باید منتظر مسیریابی موفق در سیستم دیجی‌اکسپرس باشید ( در زمان هایی ممکن است این بازه طولانی تر باشد ) |
| ثبت دو مرحله‌ای (با انتخاب Time Window) | Sync (همزمان) | دریافت ریسپانس 200 به معنی ثبت موفق و قطعی سفارش در همان لحظه است. شما می‌توانید بلافاصله پس از گرفتن پاسخ، API دریافت لیبل را صدا بزنید |
| افزودن پارسل جدید (در حالت Estimated) | Sync (همزمان) | در متد Add کردن پارسل، بعد از مسیریابی موفق شیپمنت ( Async )، هنگام کال کردن API های Add ، دریافت ریسپانس 200 به معنی اضافه شدن قطعی آن بسته است و بلافاصله امکان دریافت و چاپ لیبل آن پارسل وجود دارد. |
نکته درباره وب‌هوک (Webhook): اطلاع‌رسانی وضعیت نهایی و تغییرات وضعیت سفارش‌ها در تمامی حالت‌ها به صورت Real-time از طریق وب‌هوک ارسال می‌شود. در مواقعی که سرویس وب‌هوک به هر دلیلی از دسترس خارج باشد، این اطلاع‌رسانی با تاخیر بیشتری انجام خواهد شد.