پس از ثبت موفق سفارش، دریافت و چاپ لیبل برای هر بسته الزامی است. ناوگان دیجی‌اکسپرس از تحویل گرفتن بسته‌های فاقد لیبل یا دارای لیبل مخدوش خودداری می‌کند.
الزامات و شرایط الصاق لیبل روی بسته‌ها
- اجبار در الصاق: پس از ثبت موفقیت‌آمیز سفارش (Register) و پیش از مراجعه ناوگان دیجی‌اکسپرس برای پیکاپ (جمع‌آوری)، الصاق لیبل روی بسته‌ها کاملاً الزامی است. تیم عملیات دیجی‌اکسپرس بسته‌های فاقد لیبل را به هیچ‌وجه تحویل نخواهد گرفت.
- یکتا بودن لیبل: هر بسته (Parcel) باید لیبل یکتا و مخصوص به خود را داشته باشد. به عنوان مثال، اگر یک سفارش (Shipment) دارای چند بسته مجزا باشد، باید به ازای تک‌تک آن‌ها لیبل جداگانه دریافت شده و روی جعبه مربوطه چسبانده شود.
- استاندارد چاپ و محل الصاق: اطلاعات، بارکدها و QR کدهای روی لیبل باید کاملاً خوانا و باکیفیت چاپ شوند. لیبل باید روی یک وجهِ صاف و بدون تاخوردگیِ جعبه چسبانده شود. چسباندن لیبل روی کنج‌ها، لبه‌ها یا قسمت‌هایی که باعث تا خوردن بارکد شود ممنوع است و بسته پذیرش نمی‌شود.
- لیبل اختصاصی فرستنده: چاپ لیبل استاندارد دیجی‌اکسپرس اجباری است، اما شما می‌توانید لوگو، لیبل داخلی یا اطلاعات سیستم خودتان را نیز در دیگر وجه‌های جعبه بچسبانید و این کار مانعی ندارد.
نکته بسیار مهم درباره فرمت خروجی (Accept Header)
نحوه دریافت خروجی لیبل بر اساس متد مورد استفاده متفاوت است.
در دریافت لیبل تکی (Single Label)، فایل PDF به صورت مستقیم در پاسخ API بازگردانده می‌شود. برای دریافت صحیح فایل، الزامی است هدر "Accept": "application/pdf" در درخواست ارسال شود.
در دریافت لیبل گروهی (Bulk Label)، در صورتی که بیش از یک Parcel برای تولید لیبل ارسال شود، فرآیند تولید فایل به صورت غیرهمزمان (Async) انجام می‌شود. در این حالت فایل PDF در همان لحظه فراخوانی اولیه بازگردانده نمی‌شود و وضعیت تولید فایل از طریق Response و Webhook قابل پیگیری است.
دریافت لیبل تکی (Single Label)
اگر می‌خواهید برای یک بسته خاص لیبل بگیرید:
https://api-demo.digiexpress.ir/api/v2/parcels/{parcel_id_or_code}/label- Header: Accept: application/pdf
جدول پارامترهای آدرس (Path Variables) جهت دریافت لیبل تکی
- توضیح فنی
- شناسه سیستم (parcel_id) یا بارکد متنی بسته (parcel_code)
- توضیح بیزینسی
- مشخصات بسته‌ای که قصد دارید لیبل آن را جهت چاپ دریافت کنید.
دریافت لیبل گروهی (Bulk Label)
اگر تعداد بسته‌های شما زیاد است، می‌توانید با ارسال لیست شناسه‌های Parcel در یک درخواست، تولید فایل لیبل گروهی را آغاز کنید. فایل نهایی شامل لیبل تمام Parcelهای معتبر است و هر لیبل در یک صفحه مجزای PDF قرار می‌گیرد.
https://api-demo.digiexpress.ir/api/v2/parcels/label-requestدر صورتی که بیش از یک Parcel در parcel_identifiers ارسال می‌شود، تولید فایل باید به صورت Async انجام شود و مقدار sync_generation برابر با false ارسال گردد.
نمونه درخواست (Request Body):
{
"sync_generation": false,
"parcel_identifiers": [
"string",
"string"
],
"exclude_failed_ones": true
}جدول پارامترهای ورودی (Request Body) جهت دریافت لیبل گروهی
- توضیح فنی
- نحوه تولید فایل لیبل را مشخص می‌کند. برای تولید لیبل گروهی شامل بیش از یک Parcel باید مقدار false ارسال شود تا فرآیند Generation به صورت Async انجام شود.
- توضیح بیزینسی
- در درخواست‌های چندبسته‌ای، تولید و Merge شدن PDF ممکن است نیازمند زمان پردازش باشد؛ به همین دلیل فایل در پس‌زمینه تولید می‌شود و کانساینر نیازی به دریافت و Merge کردن تک‌تک لیبل‌ها در سیستم خود ندارد.
- توضیح فنی
- آرایه‌ای از رشته‌ها (strings) که می‌تواند شامل بارکد دیجی‌اکسپرس (مانند WP81018424940707_1) یا شناسه یکتای بسته (Parcel ID/UUID) باشد. حداکثر تعداد مجاز در یک درخواست تابع سقف بالک سیستم است.
- توضیح بیزینسی
- لیست بسته‌های مدنظر شما جهت تولید یک فایل لیبل گروهی و پشت‌سرهم.
- توضیح فنی
- مقدار منطقی (true یا false). • مقدار پیش‌فرض (Default): false است و در صورت عدم ارسال، سیستم رفتار پیش‌فرض را در نظر می‌گیرد.
- توضیح بیزینسی
- اگر این فیلد را false بفرستید، چنانچه حتی یک بسته در لیست شما آماده لیبل نباشد، کل درخواست شکست می‌خورد و هیچ لیبلی صادر نمی‌شود. اگر این فیلد را true بفرستید، سیستم بسته‌های خطادار را نادیده می‌گیرد و فرآیند تولید لیبل برای بسته‌های معتبر ادامه پیدا می‌کند.
رفتار سیستم در حالت Async
پس از ارسال موفق درخواست Bulk Label با مقدار "sync_generation": false، فرآیند تولید و Merge کردن فایل PDF در پس‌زمینه آغاز می‌شود.
در ابتدای فرآیند ممکن است مقدار progress برابر با 0 یا عددی کمتر از 100 باشد. این مقدار نشان‌دهنده میزان پیشرفت فرآیند تولید فایل است.
پس از تکمیل Generation:
- مقدار progress به 100 می‌رسد.
- لینک فایل نهایی PDF در Response در دسترس قرار می‌گیرد.
- آماده شدن فایل از طریق Webhook نیز به کانساینر اطلاع‌رسانی می‌شود.
هدرهای الزامی دریافت لیبل (Request Headers)
| متد | کلید هدر (Key) | مقدار (Value) | توضیح فنی و بیزینسی |
|---|---|---|---|
| Single Label | Authorization | YOUR_JWT_TOKEN | توکن دریافت شده از گام لاگین (بدون پیشوند Bearer). |
| Single Label | Accept | application/pdf | فایل PDF لیبل به صورت مستقیم در Response بازگردانده می‌شود. |
| Bulk Label | Authorization | YOUR_JWT_TOKEN | توکن دریافت شده از گام لاگین (بدون پیشوند Bearer). |
| Bulk Label | Content-Type | application/json | بدنه درخواست Bulk Label به صورت JSON ارسال می‌شود. |