روش‌های ارسال ایران

افزونه‌ی روش‌های ارسال ابرک، همان موتور استاندارد حمل‌ونقل نرم‌افزار اودو (Odoo) را برای بازار ایران کامل می‌کند. پست، تیپاکس، اسنپ‌باکس، الوپیک، ماهکس، چاپار، پستکس، پادرو، میاره یا پیک اختصاصی خودتان را به‌عنوان روش ارسال تعریف می‌کنید؛ خریدار هزینه را سر تسویه‌حساب می‌بیند، انبار مرسوله را ثبت می‌کند و کد رهگیری روی همان حواله‌ی اودو می‌نشیند.

نوشته‌شده توسط تیم فنی ابرک — پیاده‌سازی مطابق مستندات عمومی API اسنپ‌باکس و تاپین، پیش‌بینی هوا از Open-Meteo، نقشه بر پایه‌ی Leaflet و کاشی‌های OpenStreetMap. آزموده‌شده روی نصب واقعی Odoo 19 با ۲۸۳ سناریوی خودکار که روی دیتابیس زنده اجرا می‌شوند. آخرین بازبینی: شهریور ۱۴۰۵.

مسئله‌ی واقعی: هزینه‌ی ارسال کجا اشتباه می‌شود؟

فروشگاه‌های ایرانی معمولاً یکی از این دو مسیر را می‌روند و هر دو نشتی دارد. مسیر اول، «هزینه‌ی ارسال را بعداً هماهنگ می‌کنیم»: مشتری سفارش را نهایی می‌کند بدون اینکه بداند چقدر باید بدهد، و بخشی از سفارش‌ها همان‌جا می‌سوزد. مسیر دوم، یک عدد ثابت برای همه‌ی ایران: برای مقصد نزدیک ضرر مشتری است و برای مقصد دور ضرر فروشگاه.

اودو از پایه یک موتور روش ارسال دارد که هر دو مشکل را حل می‌کند — نرخ ثابت، نرخ بر اساس قواعد (وزن، مبلغ، مقصد) و نرخ آنلاین از خود شرکت حمل. چیزی که نداشت، شرکت‌های حمل ایران و قرارداد داده‌ی آن‌ها بود. این افزونه دقیقاً همان شکاف را پر می‌کند و نه یک ذره بیشتر: هیچ مدل سفارش، تعرفه یا پنل موازی ساخته نشده است.

چه چیزی را روی چه چیزی می‌سازد

افزونه مدل‌های استاندارد اودو را گسترش می‌دهد:

• روش تحویل (delivery.carrier): انتخاب سرویس ایرانی، تنظیمات API، و دو نوع نرخ آنلاین تازه.
• سفارش فروش و حواله‌ی انبار: یک شناسه‌ی پایدار برای هر مرسوله، شناسه‌ی سفارش در سرویس، و نشانی رهگیری.
• مخاطب و استان: مختصات جغرافیایی و کدهای مکانی مخصوص سرویس.

در نتیجه، تسویه‌حساب وب‌سایت، پرتال مشتری، برگه‌ی تحویل، دکمه‌ی رهگیری و گفت‌وگوی حواله همگی همان چیزی هستند که اودو دارد — فقط حالا با شرکت‌های حمل ایران کار می‌کنند.

تفاوتی که باید بدانید: نام شرکت حمل ≠ اتصال API

این مهم‌ترین نکته‌ی پیکربندی است و عمداً در خود فرم هم نوشته شده. انتخاب «تیپاکس» یا «ماهکس» به‌عنوان سرویس، فقط برچسب آن روش ارسال است. نرخ در این حالت همان تعرفه‌ای است که خودتان با «قیمت ثابت» یا «بر اساس قواعد» تعیین کرده‌اید، ثبت مرسوله در پنل خود شرکت حمل انجام می‌شود و کد رهگیری را در حواله وارد می‌کنید.

فقط دو روش با سرویس حرف می‌زنند: «اسنپ‌باکس — API» برای پیک درون‌شهری و «پست با تاپین — API» برای پست. این تفکیک عمدی است؛ نوشتن نام ده شرکت روی یک صفحه و اسمش را «اتصال» گذاشتن، چیزی است که این افزونه انجام نمی‌دهد.

نرخ خودکار در تسویه‌حساب: پیش‌نیازهای واقعی

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

۱) مختصات جغرافیایی برای پیک درون‌شهری

اسنپ‌باکس بر اساس فاصله قیمت می‌دهد، پس مختصات مبدأ و مقصد را می‌خواهد. اما خریدار در فرم تسویه‌حساب مختصات وارد نمی‌کند، و اودو با هر تغییر نشانی مختصات را به صفر برمی‌گرداند. راه‌حل افزونه: هنگام استعلام نرخ، اگر نشانی ایرانی است و مختصات ندارد، یک‌بار از geocoder استاندارد خود اودو استفاده می‌شود و نتیجه روی همان مخاطب می‌ماند. موتور جدیدی ساخته نشده است.

دو تضمین مهم: این کار هرگز تسویه‌حساب را نمی‌شکند — اگر geocoder تنظیم نشده یا در دسترس نباشد، فقط نرخ آن روش نمایش داده نمی‌شود و پیام روشن می‌گیرید. و اگر نخواهید، با پارامتر سیستمی delivery_abrak.geocode_on_demand خاموشش می‌کنید و مختصات را دستی وارد می‌کنید.

۲) کدهای استان و شهر برای پست

تاپین کد عددی مخصوص خودش را برای استان و شهر می‌خواهد؛ این کد با کد استان اودو و با نام شهر یکی نیست. اگر قرار بود این کد روی تک‌تک مخاطب‌ها وارد شود، عملاً هیچ فروشگاه اینترنتی نمی‌توانست از آن استفاده کند. بنابراین نگاشت روی خود استان نشسته است: یک‌بار برای هر استان پر می‌کنید و تمام. فیلد روی مخاطب هم هست، برای وقتی که یک نشانی خاص استثنا باشد، و بر مقدار استان اولویت دارد.

۳) وزن محصول

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

ثبت مرسوله، کد رهگیری و لینک پیگیری

پس از تأیید حواله، دکمه‌ی استاندارد ارسال اودو مرسوله را در سرویس ثبت می‌کند، هزینه‌ی واقعی روی حواله می‌نشیند و کد رهگیری در فیلد استاندارد ذخیره می‌شود. برای لینک پیگیری، افزونه فیلد «Tracking URL» خودِ اودو را پر می‌کند: نشانی صفحه‌ی رهگیری شرکت حمل را با جای‌گذاری <shipmenttrackingnumber> یک‌بار روی روش ارسال می‌نویسید و دکمه‌ی رهگیری فعال می‌شود. همین کار برای روش‌های دستی هم جواب می‌دهد، پس حتی برای پست و تیپاکس هم مشتری لینک پیگیری دارد.

وقتی سرویس جواب نمی‌دهد — مهم‌ترین بخش

خطرناک‌ترین لحظه در هر اتصال حمل‌ونقل، پاسخ نامعلوم است: درخواست ثبت رفته، ولی جواب نرسیده. اگر نرم‌افزار دوباره تلاش کند، ممکن است دو مرسوله ثبت شود و دو بار هزینه بدهید. رفتار این افزونه صریح است:

• هیچ تلاش مجدد کوری روی ثبت مرسوله انجام نمی‌شود. مهلت زمانی ثابت است و هیچ لایه‌ی retry خودکاری نصب نشده.
• هر حواله یک شناسه‌ی پایدار دارد که همراه درخواست می‌رود. پاسخ نامعلوم یعنی همان شناسه یک‌بار در سرویس جست‌وجو می‌شود تا مرسوله‌ی موجود پیدا و متصل شود.
• اگر آن جست‌وجو هم شکست بخورد، دکمه‌ی «تطبیق با سرویس ارسال» روی حواله همان کار را در هر زمان دیگری انجام می‌دهد و نتیجه را در گفت‌وگوی حواله ثبت می‌کند.
• مبلغ نامعتبر یا پاسخ ناخوانا هرگز به نرخ صفر تبدیل نمی‌شود؛ در مسیر تاپین قیمت پیش از ثبت گرفته می‌شود و اگر به‌دست نیاید، اصلاً مرسوله‌ای ثبت نمی‌شود.

روش جایگزین: اینکه سبد خالی نماند

یک رفتار پیش‌فرض اودو هست که کمتر کسی تا روزِ بد متوجهش می‌شود: روشی که نرخ‌گیری‌اش شکست بخورد، از صفحه‌ی پرداخت حذف می‌شود. یعنی یک قطعی نیم‌ساعته در سرویس شرکت حمل، به‌جای نمایش یک خطا، خریدار را با سبدی روبه‌رو می‌کند که «هیچ روش ارسالی در دسترس نیست». فروشگاه نه نرخ آنلاین را از دست می‌دهد، که کل سفارش را.

در این افزونه هر روش آنلاین می‌تواند یک «روش جایگزین» معرفی کند — معمولاً تعرفه‌ی دستی خود فروشگاه برای همان شرکت حمل. وقتی سرویس جواب ندهد همان نرخ نمایش داده می‌شود و صریحاً به خریدار گفته می‌شود که این تعرفه‌ی فروشگاه است، نه نرخ لحظه‌ای شرکت حمل. پنهان‌کردن این تفاوت، اعتماد را گران‌تر از یک سفارش از دست می‌دهد.

دو محدودیت عمدی روی این قابلیت هست: روش جایگزین نمی‌تواند خودِ همان روش باشد، و نمی‌تواند یک روش آنلاین دیگر باشد — چون سرویس دوم هم ممکن است همان لحظه در دسترس نباشد و شما به یک زنجیره‌ی قطعی می‌رسید. اگر روش جایگزین هم نتواند به آن نشانی سرویس بدهد، همان خطای اصلی گزارش می‌شود، نه یک موفقیت ساختگی.

چهار راه قیمت‌گذاری، روی یک موتور

در بازار ایران قیمت‌گذاری ارسال معمولاً با یکی از این چهار منطق انجام می‌شود. هر چهار تا اینجا روی همان موتور قواعد قیمت خود اودو (delivery.price.rule) می‌نشیند؛ موتور دومی ساخته نشده، پس چیزی که در گزارش‌ها و فاکتور می‌بینید همان چیزی است که اودو می‌فهمد.

1. نرخ ثابت — ساده‌ترین حالت. برای «ارسال رایگان بالای فلان مبلغ» هم گزینه‌ی بومی اودو کار می‌کند.
2. بر پایه‌ی قواعد — وزن، حجم، تعداد و مبلغ سبد. افزونه به این‌ها استان، شهر، منطقه، روز هفته و بازه‌ی ساعت را اضافه می‌کند. هر قاعده می‌تواند بازه‌ی تاریخ داشته باشد، پس نرخ‌نامه‌ی امسال و پارسال کنار هم می‌مانند و هر سفارش با تاریخ خودش قیمت می‌خورد — چیزی که هنگام حسابرسی اهمیت پیدا می‌کند.
3. کیلومتر — برای پیک درون‌شهری. «فاصله (کیلومتر)» کنار وزن و حجم یکی از متغیرهای قابل استفاده در قاعده است: می‌توانید بنویسید «تا ۴۰ کیلومتر، پایه ۲۰ هزار تومان به‌علاوه‌ی ۵ هزار تومان هر کیلومتر». فاصله خط مستقیم بین درِ انبار و درِ خریدار است، چون تعرفه‌ی پیک هم با همان توافق می‌شود؛ گذاشتن یک درخواست مسیریابی وسط هر تسویه‌حساب، هزینه و تأخیری اضافه می‌کند که نرخ‌نامه از آن حرفی نزده است.
4. نرخ آنلاین شرکت حمل — اسنپ‌باکس، پست از مسیر تاپین، الوپیک و میاره. هر چهار تا از روی مستندات منتشرشده‌ی خودِ همان سرویس پیاده شده‌اند.

یک نکته‌ی صداقت که در ماشین‌حساب عمومی رعایت شده: ماشین‌حساب سایت فقط استان را می‌داند، نه پلاک را. پس اگر روشی فقط با کیلومتر قیمت می‌خورد، در ماشین‌حساب عمومی نمایش داده نمی‌شود — به‌جای اینکه فاصله را صفر فرض کند و عددی بسازد که سر تسویه‌حساب عوض می‌شود.

محدوده‌ی تحویل: وقتی «شهر» خیلی درشت است

اودو می‌تواند بگوید یک روش ارسال به کدام کشور، استان یا کد پستی سرویس می‌دهد. برای تهران این واحد بسیار درشت است: فروشگاهی که با موتور خودش تا شعاع چند خیابان رایگان می‌برد، نمی‌تواند این را با «استان تهران» بیان کند.

در «پیکربندی ▸ محدوده‌های تحویل» می‌توانید محدوده را با نقطه‌گذاری روی نقشه تعریف کنید — دست‌کم سه نقطه، دور تا دور ناحیه. یک روش ارسال می‌تواند چند محدوده داشته باشد و نشانی‌ای که داخل هیچ‌کدام نباشد، آن روش را در صفحه‌ی پرداخت نمی‌بیند.

یک تصمیم مهم اینجا گرفته شده: خریداری که هنوز موقعیتی روی نقشه ثبت نکرده، «بیرون از محدوده» حساب نمی‌شود. او نامعلوم است، نه دور. رد کردن او یعنی از دست دادن سفارش به خاطر فیلدی که هیچ فروشگاه اینترنتی‌ای اجباری‌اش نمی‌کند.

نقشه‌ای که خودِ اودو دارد

خریدار می‌تواند محل دقیق تحویل را روی نقشه بگذارد. نقشه Leaflet است — همان کتابخانه‌ای که اودو از قبل برای نمای نقشه‌ی خودش همراه دارد — و کاشی‌ها از OpenStreetMap می‌آید. هیچ کتابخانه‌ی نقشه‌ی دومی وارد صفحه نمی‌شود و هیچ SDK ایرانی‌ای که کلیدش را نداریم استفاده نشده.

توکن MapBox که نمای نقشه‌ی اودو می‌تواند از آن استفاده کند، در این صفحه عمداً به کار نرفته است: صفحه‌ی پرداخت عمومی است و توکنی که به هر بازدیدکننده‌ی ناشناس تحویل داده شود، توکنی است که داده‌اید. دکمه‌ی «موقعیت من» هم سر جایش مانده، چون وقتی خریدار همان‌جا ایستاده سریع‌تر از نقشه است. هر دو مسیر مختصات را از یک راه ذخیره می‌کنند.

روز و ساعت تحویل را خریدار انتخاب می‌کند

بازه‌های تحویل از تقویم کاری همان روش ارسال خوانده می‌شود — یعنی resource.calendar خود اودو. نتیجه‌ی عملی‌اش این است که تعطیل رسمی همان «مرخصی» روی همان تقویم است و جدول تعطیلات دومی نگه داشته نمی‌شود. «مهلت آماده‌سازی» هم لحاظ می‌شود، پس بازه‌ای که هنوز نمی‌توانید به آن برسید اصلاً پیشنهاد نمی‌شود.

انتخاب خریدار روی «تاریخ تعهدشده» (commitment_date) خودِ اودو نوشته می‌شود، نه یک فیلد موازی. اهمیتش این است که حواله‌ی انبار، صفحه‌ی پرتال مشتری و برگه‌ی چاپی سفارش همگی این تاریخ را می‌خوانند بدون اینکه چیزی درباره‌ی «بازه‌ی ارسال» بدانند. فقط پایان بازه فیلد ماست، چون اودو جایی برایش ندارد.

بازه‌ای که روش ارسال پیشنهاد نداده باشد پذیرفته نمی‌شود؛ وگرنه کسی با ویرایش صفحه می‌توانست تحویل نیمه‌شب برای خودش ثبت کند. تاریخ‌ها هم از همان مسیری می‌گذرند که نمایش تاریخ کل سامانه — روی نصب فارسی، شمسی دیده می‌شود.

یک سبد، دو شرکت حمل

یخچال با باربری می‌رود و کتری با پست. اودو برای هر سفارش یک روش ارسال می‌گذارد، پس فروشگاهی که هر دو را می‌فروشد یا سفارش را دستی تکه می‌کند، یا کل سبد را مثل سنگین‌ترین قلمش قیمت می‌زند.

«روش ارسال ترکیبی» جمع اجزا را حساب می‌کند. اجزا روش‌های معمولی خود اودو هستند و اینکه کدام کالا با کدام جزء می‌رود را برچسب محصول — همان فیلد بومی زبانه‌ی دسترس‌پذیری — تعیین می‌کند. یعنی برای توصیف «یخچال» و «کتری» مفهوم تازه‌ای ساخته نشده. هر جزء با قواعد و نرخ‌نامه‌ی خودش قیمت می‌خورد، دقیقاً مثل وقتی که تنها باشد، و جمع با تفکیک به خریدار نشان داده می‌شود.

کالایی که هیچ جزئی برنمی‌دارد با پیام صریح و نام همان کالا رد می‌شود — نه اینکه بقیه قیمت بخورد و آن یکی خاموش رایگان برود. همان شکاف خاموش، دلیل وجود این قابلیت است. حواله‌ی انبار هم تفکیک را می‌نویسد تا انباردار بداند کدام بسته را به کدام شرکت بدهد.

مسیر امروز پیک

«پیک» در این افزونه مفهوم تازه‌ای نیست: همان «مسئول» حواله در اودو است. ساختن مفهوم دوم یعنی روی هر مرسوله دو جواب داشته باشید و به هیچ‌کدام اعتماد نکنید.

پیک از نشانی /my/round فهرست مرسوله‌های خودش را می‌بیند — روی همان پرتال اودو، پس برای پیمانکاری که حساب پرتال دارد هم کار می‌کند و اپ جداگانه‌ای لازم ندارد. ترتیب فهرست نزدیک‌ترین‌به‌نزدیک‌ترین از درِ انبار است: نزدیک‌ترین مقصد، بعد نزدیک‌ترین به آن، و همین‌طور تا آخر.

این یک اکتشاف است، نه کوتاه‌ترین مسیر ریاضی، و عمداً محاسبه‌ی حسابی است نه فراخوانی یک سرویس مسیریابی: پیکی که باید منتظر پاسخ شبکه بماند تا راه بیفتد، بدتر سرویس گرفته تا پیکی که ترتیب «خوبِ کافی» دارد. مرسوله‌ای که موقعیت ندارد آخر فهرست می‌آید و از فهرست نمی‌افتد — گم‌شدن یک مرسوله خطای بدتری است از رفتن به آن با ترتیب نامناسب. ثبت تحویل از همان مسیر کد تحویل کارتابل می‌گذرد.

پیگیری مرسوله، بدون حساب کاربری

خریدار ایرانی انتظار دارد کد رهگیری روی رسید را وارد کند و ببیند مرسوله کجاست. پرتال اودو برای این کار توکن اختصاصی سفارش یا ورود به حساب می‌خواهد، و خریداری که مهمان تسویه کرده هیچ‌کدام را ندارد — نتیجه‌اش صف پشتیبانی است.

نشانی /shipping/track این را جواب می‌دهد و فقط درباره‌ی مرسوله حرف می‌زند: نه نام، نه نشانی، نه اقلام سبد. دلیلش یک اصل امنیتی ساده است — کد رهگیری روی جعبه‌ای چاپ می‌شود که از دست‌های زیادی می‌گذرد؛ آن کد یک مرسوله را مشخص می‌کند، هویت کسی را تأیید نمی‌کند. کد خالی هم هیچ چیزی را match نمی‌کند، وگرنه اولین مرسوله‌ی بدون کد رهگیری به هر غریبه‌ای که فرم خالی می‌فرستاد جواب می‌داد.

ارقام فارسی و انگلیسی هر دو یک مرسوله را پیدا می‌کنند، و صفحه قالب خود فروشگاه شما را می‌گیرد.

افزایش نرخ در هوای بد

پیک در روز بارانی گران‌تر کار می‌کند. افزونه‌های رقیب در این بازار همین را می‌فروشند، ولی مبلغ را داخل قیمت پنهان می‌کنند. اینجا آستانه‌ی باران (میلی‌متر) و برف (سانتی‌متر) را خودتان تعیین می‌کنید و مبلغ اضافه با ذکر دلیل روی همان نرخ نوشته می‌شود — خریدار حق دارد بداند چرا عدد جابه‌جا شد.

پیش‌بینی از Open-Meteo خوانده می‌شود که رایگان است و کلید API نمی‌خواهد؛ پس فروشگاه لازم نیست نزد کسی حساب باز کند. پیش‌بینی برای روز تعهدشده‌ی تحویل و مقصد گرفته می‌شود، نه برای امروز و نه برای انبار.

دو رفتار محافظه‌کارانه: اگر پیش‌بینی به هر دلیلی خوانده نشود هیچ مبلغی اضافه نمی‌شود — گرفتن پول از خریدار روی حدس، بدتر از نگرفتن است. و اگر افزایش نرخ را صفر بگذارید، افزونه اصلاً به آسمان نگاه نمی‌کند. پاسخ‌ها برای هر نقطه و هر روز یک‌بار کش می‌شوند، وگرنه فروشگاه پرترافیک خیلی زود محدود می‌شد.

پرداخت در محل، فقط با پیک خودمان

پرداخت در محل واقعیتی درباره‌ی شرکت حمل است: کسی باید دم در باشد که پول را بگیرد. اودو روش‌های ارسال و درگاه‌های پرداخت را جدا نگه می‌دارد و هیچ‌وقت از یکی درباره‌ی دیگری نمی‌پرسد؛ نتیجه‌اش این است که فروشگاه بعد از ثبت سفارش باید به خریدار زنگ بزند و بگوید این ترکیب ممکن نیست.

هر روش ارسال می‌تواند فهرست درگاه‌هایی را که می‌پذیرد نام ببرد. روشی که هیچ درگاهی نام نبرد، مثل قبل همه را می‌پذیرد — پس هیچ پیکربندی موجودی با نصب این نسخه عوض نمی‌شود.

خطاهای رایج و معنای دقیقشان

• «برای فلان کالا وزن تعیین کنید» — همان محصول را باز کنید و وزن واقعی بگذارید. وزن صفر برای شرکت حمل قابل قیمت‌گذاری نیست.
• «مختصات معتبر گیرنده را وارد کنید» — geocoder اودو نتوانسته نشانی را حل کند یا اصلاً تنظیم نشده. یک provider در تنظیمات عمومی فعال کنید، یا مختصات را دستی روی مخاطب بگذارید.
• «کد استان تاپین را روی نشانی گیرنده وارد کنید» — استان آن نشانی هنوز نگاشت نشده. کد را روی خود استان بگذارید تا برای همه‌ی نشانی‌های آن استان حل شود.
• «کلید API این محیط را وارد کنید» — روش از نوع API است ولی کلید ندارد. توجه کنید کلید محیط آزمایش و محیط عملیاتی یکی نیست.
• «ارز سرویس ارسال را انتخاب و تأیید کنید» — افزونه واحد پول قرارداد را حدس نمی‌زند؛ باید صریح تعیین شود تا تبدیل به ارز شرکت درست انجام گیرد.
• «مبلغ سرویس دریافت نشد، پس هیچ مرسوله‌ای ثبت نشد» — دوباره تلاش کنید یا مرسوله را در پنل شرکت حمل ثبت و هزینه را دستی وارد کنید. هیچ چیز نیمه‌کاره ثبت نشده است.

امنیت و جداسازی

کلید API و شناسه‌ی فروشگاه فقط برای گروه «مدیر سیستم» قابل مشاهده‌اند، هنگام کپی‌کردن روش ارسال منتقل نمی‌شوند و در لاگ یا پیام خطا نوشته نمی‌شوند. لینک رهگیری‌ای که سرویس برمی‌گرداند تنها در صورتی پذیرفته می‌شود که https باشد و به دامنه‌ی همان سرویس تعلق داشته باشد؛ تغییر مسیر (redirect) دنبال نمی‌شود. روش ارسال از نوع API باید به یک شرکت مشخص تعلق داشته باشد و مرسوله‌ی شرکت دیگر با آن ثبت نمی‌شود.

فارسی، راست‌به‌چپ و تاریخ

همه‌ی برچسب‌ها، راهنماها، مقادیر انتخابی و پیام‌های خطا فارسی‌اند و روی نصب واقعی با زبان fa_IR در جهت راست‌به‌چپ آزموده شده‌اند. شماره‌ی موبایل و کد پستی با ارقام فارسی هم پذیرفته و پیش از ارسال به سرویس به ارقام لاتین تبدیل می‌شوند. هیچ فیلد تاریخ تازه‌ای ساخته نشده؛ تاریخ سفارش و حواله همان فیلدهای استاندارد اودو هستند و نمایش شمسی را جلالی پرو بر عهده دارد.

چه چیزی هنوز پشتیبانی نمی‌شود

صادقانه بگوییم تا انتظار اشتباه ساخته نشود:

• اتصال زنده هنوز روی حساب واقعی تأیید نشده است. چهار اتصال — اسنپ‌باکس، پست از مسیر تاپین، الوپیک و میاره — مطابق مستندات منتشرشده‌ی خودِ همان سرویس‌ها پیاده و آزمون خودکار شده‌اند، اما تأیید نهایی نیازمند کلید یا توکن معتبر از هر کدام است. این تفاوت را جدی بگیرید: «مطابق مستندات پیاده شده» یعنی قرارداد را خوانده‌ایم، نه اینکه یک مرسوله‌ی واقعی را تا مقصد برده‌ایم.
• تیپاکس API دارد ولی قراردادش عمومی نیست. پلتفرم «ای‌تیپاکس» وب‌سرویس و افزونهٔ ووکامرس ارائه می‌کند، اما مستندات فنی‌اش پشت ثبت‌نام است. تا وقتی قرارداد را ندیده باشیم پیاده‌سازی نمی‌کنیم — کد نوشتن روی قراردادی که ندیده‌ایم، همان حدس‌زدنی است که این افزونه از آن پرهیز می‌کند. اگر حساب ای‌تیپاکس دارید و مستندات را در اختیار بگذارید، اتصالش مثل بقیه انجام می‌شود.
• ماهکس، چاپار، پستکس و پادرو قرارداد عمومی منتشرشده‌ای ندارند — دست‌کم در جست‌وجوی ما. این‌ها به‌صورت روش دستی با نرخ ثابت، قواعد ایرانی یا قیمت کیلومتری پشتیبانی می‌شوند، که برای اکثر فروشگاه‌ها همان چیزی است که قرارداد واقعی‌شان می‌گوید.
• نرخ‌نامه‌ی رسمی پست به‌صورت داده‌ی آماده همراه افزونه نمی‌آید — و دلیلش فنی است. شرکت ملی پست نرخ‌نامه را در صفحه‌ی نرخنامه‌ی خودش منتشر می‌کند، ولی فایل سال ۱۴۰۵ یک PDF اسکن‌شده بدون لایه‌ی متنی است — بررسی کردیم: پنج صفحه‌ی تصویری، بدون یک کاراکتر قابل استخراج. بیرون کشیدن عدد از تصویر با OCR ممکن است، ولی یک رقم اشتباه در جدول تعرفه یعنی پول واقعیِ اشتباه روی هر سفارشی که با آن قیمت می‌خورد. ضمناً تعرفه‌ی واقعی اکثر فروشگاه‌ها تعرفه‌ی قرارداد خودشان است، نه نرخ‌نامه‌ی عمومی. به‌جایش قالب CSV و راهنمای وارد کردن یک‌جای تعرفه همراه افزونه می‌آید، روی import استاندارد خود اودو.
• لغو مرسوله در تاپین از راه API انجام نمی‌شود. افزونه عمداً خطا می‌دهد تا اودو مرسوله‌ی زنده را «لغوشده» علامت نزند، و شماره‌ی مرسوله را در پیام می‌آورد تا در پنل تاپین لغو کنید.
• مرجوعی از حواله‌ی بومی اودو انجام می‌شود. مبدأ و مقصد برگشت برای شرکت حمل جابه‌جا می‌شوند؛ برچسب برگشت فقط با پشتیبانی تأییدشده‌ی سرویس در دسترس است. چندبسته‌ای و برچسب اختصاصی هر شرکت را پیش از استفاده با قرارداد همان سرویس بررسی کنید.

آموزش گام‌به‌گام: از نصب تا اولین مرسوله

این مسیر را با یک روش دستی شروع می‌کنیم و بعد سراغ نرخ آنلاین می‌رویم. دلیلش تجربی است: اگر از روز اول با کلید API شروع کنید، هر خطایی می‌تواند هم از تنظیمات شما باشد هم از سرویس، و جدا کردنشان وقت می‌برد.

گام ۱ — نصب و اولین نگاه

پس از فعال‌سازی اپ، منوی «ارسال ابرک» اضافه می‌شود. «کارتابل» صفحه‌ی اول است: کاشی‌هایی که می‌گویند چند مرسوله منتظر اقدام است، کدام نشانی‌ها ایراد دارند و کدام شهرها هنوز کد شرکت حمل ندارند. هر کاشی یک فیلتر است و با کلیک باز می‌شود — چیزی جداگانه ذخیره نمی‌کند.

گام ۲ — اولین روش ارسال (بدون کلید API)

از «ارسال ابرک ▸ پیکربندی ▸ روش‌های ارسال» یک روش بسازید:

1. نام را همان چیزی بگذارید که خریدار باید ببیند، مثلاً «پست پیشتاز».
2. نوع ارائه‌دهنده را روی «نرخ ثابت» یا «بر پایه‌ی قواعد» بگذارید.
3. محصول هزینه‌ی ارسال را انتخاب کنید. توصیه: برای هر روش یک محصول خدماتی جدا بسازید — اودو قیمت ثابت را روی همان محصول نگه می‌دارد، پس دو روشی که یک محصول مشترک داشته باشند یک قیمت مشترک هم خواهند داشت.
4. در زبانه‌ی «دسترس‌پذیری» کشور و استان مجاز، سقف وزن و برچسب محصول را تعیین کنید.
5. در زبانه‌ی «راهنمای ارسال ابرک»، «سرویس ارسال ابرک» را انتخاب کنید (پست، تیپاکس، اسنپ‌باکس و…). این فقط نام شرکت حمل است.

گام ۳ — قواعد قیمت ایرانی

اگر «بر پایه‌ی قواعد» را انتخاب کرده‌اید، در زبانه‌ی «قیمت‌گذاری» قاعده بسازید. علاوه بر وزن و مبلغ سبد که اودو دارد، می‌توانید استان، شهر، منطقه، روزهای هفته و بازه‌ی ساعت بگذارید. برای نرخ‌نامه، «از تاریخ / تا تاریخ» را پر کنید تا وقتی تعرفه عوض شد، قاعده‌ی قدیمی را حذف نکنید — سفارش‌های قدیمی باید با نرخ روز خودشان قابل توضیح بمانند.

قاعده‌ای که هیچ شرطی نداشته باشد، دقیقاً مثل قبل رفتار می‌کند. پس افزودن این افزونه به یک نصب موجود، قیمت هیچ روشی را تغییر نمی‌دهد.

گام ۴ — پیش‌نیازهای نرخ آنلاین

سه چیز باید سر جایش باشد وگرنه خطا می‌گیرید و علت را نمی‌دانید:

• وزن محصول — وزن صفر برای شرکت حمل قابل قیمت‌گذاری نیست.
• کد استان و شهر برای مسیر پست: این‌ها را یک‌بار روی خود استان پر کنید، نه روی تک‌تک مشتری‌ها.
• مختصات برای پیک درون‌شهری: یا geocoder اودو را در تنظیمات عمومی فعال کنید، یا اجازه بدهید خریدار سر تسویه‌حساب روی نقشه پین بگذارد.

گام ۵ — وارد کردن کلید API

کلید روی خودِ روش ارسال می‌نشیند، چون یک فروشگاه می‌تواند دو قرارداد با یک شرکت حمل داشته باشد و هر کدام کلید خودش را دارد. دو مسیر برای رسیدن به آن هست:

• «ارسال ابرک ▸ پیکربندی ▸ اتصال‌های API» — فهرستی از همه‌ی روش‌های API‌دار که کلید در همان سطر قابل ویرایش است. برای دیدن وضعیت همه‌ی اتصال‌ها در یک نگاه، همین‌جا بهترین جاست.
• یا روی خود روش: «نوع ارائه‌دهنده» را روی «اسنپ‌باکس — API» یا «پست با تاپین — API» بگذارید؛ آن‌وقت گروه «اتصال API» در زبانه‌ی راهنمای ارسال ابرک ظاهر می‌شود.

نکته‌ای که بیشترین سؤال را ساخته است: انتخاب «اسنپ‌باکس» در فیلد «سرویس ارسال ابرک» به‌تنهایی کادر کلید را نمی‌آورد. آن فیلد می‌گوید چه کسی مرسوله را می‌برد؛ «نوع ارائه‌دهنده» می‌گوید آیا اودو با او حرف می‌زند. تا وقتی نوع ارائه‌دهنده «نرخ ثابت» است، این روش تعرفه‌ی خود فروشگاه است و کلیدی لازم ندارد — و خود فرم هم همین را به شما می‌گوید.

کلید فقط برای مدیر سیستم دیده می‌شود، کپی نمی‌شود و در لاگ ثبت نمی‌شود. پیش از روشن‌کردن «محیط عملیاتی»، ارز قرارداد و واحد وزن را با شرکت حمل تأیید کنید.

گام ۶ — اولین سفارش واقعی

یک سفارش کم‌ارزش ثبت کنید و تا تحویل ببرید. مسیر کامل این است: سفارش تأیید می‌شود ← حواله‌ی خروج ساخته می‌شود ← در حواله دکمه‌ی ثبت مرسوله ← کد رهگیری روی همان حواله می‌نشیند ← وضعیت از سرویس خوانده و روی حواله به‌روز می‌شود.

گام ۷ — چیزهایی که بعداً روشن می‌کنید

این‌ها هیچ‌کدام برای شروع لازم نیستند و همه پیش‌فرض خاموش‌اند:

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

یادداشت کوتاه برای شروع سریع

پس از فعال‌سازی اپ، از «ارسال ابرک ▸ کارتابل» وضعیت مرسوله‌ها و موارد نیازمند اقدام را ببینید. مدیر انبار از «ارسال ابرک ▸ پیکربندی ▸ روش‌های ارسال» یا دکمه‌ی پیکربندی کارتابل به فرم استاندارد روش تحویل می‌رسد. همین تنظیمات از منوی موجودی هم در دسترس است؛ تنظیم جداگانه‌ای برای شرکت حمل ساخته نمی‌شود.

برای شروع، یک روش «قیمت ثابت» بسازید و محدودیت مقصد را تعیین کنید؛ سپس سراغ نرخ آنلاین بروید. پیش از فعال‌کردن محیط عملیاتی، ارز قرارداد و واحد وزن را با شرکت حمل تأیید کنید و یک سفارش کم‌ارزش را تا تحویل آزمایش کنید.

فروشنده و خریدار ارسال را کجا پیگیری می‌کنند؟

فروشنده در کارتابل ارسال به حواله‌ها و تنظیمات بومی اودو دسترسی دارد. خریدار از «حساب من ▸ سفارش‌ها» سفارش خود را باز می‌کند؛ روش ارسال، بازه‌ی انتخابی، حواله، وضعیت تحویل و رهگیری همان‌جا نمایش داده می‌شود. وضعیت شرکت حمل، در صورت دریافت از سرویس، به همین صفحه افزوده می‌شود. این مسیر از دسترسی‌های پرتال اودو استفاده می‌کند.

فاکتور نیز روش ارسال و گزینه‌های سفارش‌های مرتبط را نشان می‌دهد. پس‌کرایه‌ی برآوردی سفارش با برچسب جداگانه و خارج از جمع فاکتور نمایش داده می‌شود؛ مبلغی که شرکت حمل از گیرنده می‌گیرد، فروش فروشگاه محسوب نمی‌شود.

اگر فروشگاه شما روی ووکامرس است یا محصولاتتان را روی ترب نمایش می‌دهید، این افزونه در کنار همان اتصال‌ها کار می‌کند. برای شروع از همین‌جا اقدام کنید، قیمت‌گذاری را ببینید، یا اپ‌های مرتبط انبار و فروش را مرور کنید.