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

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

نوشته‌شده توسط تیم فنی ابرک — پیاده‌سازی مطابق مستندات عمومی API اسنپ‌باکس و تاپین، آزموده‌شده روی نصب واقعی Odoo 19 با ۳۰ سناریوی خودکار.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

۳) وزن محصول

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

چطور شروع کنیم؟

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

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