سامانه اطلاع‌رسانی تجارت هوشمند

دریافت توکن باید از طریق متد POST و آدرس https://igtgatewayapi.tipax.ir/Token و ارسال JSON زیر انجام شود:

در حال حاضر پارامترهای ثبت زمان جمع‌آوری مرسوله در API وجود دارد اما امکان ثبت آن میسر نیست.

ثبت سفارش به ارزش بیشتر از ۱۰۰,۰۰۰,۰۰۰ تومان نیاز به هماهنگی با اکانت منیجر دارد.

آدرس‌های فرستنده peopleAddressTypeId=1 و آدرس‌های گیرنده peopleAddressTypeId=2 دارند

این پارامتر مشخص می‌کند که آیا جزئیات اطلاعات فرستنده و گیرنده بر روی لیبل چاپ شود (true) یا خیر (false)

هر مشتری می‌تواند از طریق متد POST و اندپوینت https://omapi.tipax.ir/api/OM/v4/ParcelBooks بسته تعریف کند. بسته‌هایی که توسط خود مشتری تعریف شده‌اند را می‌توان با استفاده از متد Get و اندپوینت https://omapi.tipax.ir/api/OM/v3/ParcelBooks دریافت کرد. در ریسپانس این سرویس، برای هر بسته تعریف شده یک id وجود دارد که این مقادیر همان Vlaueهای مجاز برای پارامتر parcelbookId هستند. نکته مهم در مورد این پارامتر این است که زمانی که در جیسون ارسالی، از این پارامتر استفاده می‌کنید، دیگر لازم نیست پارامترهای مرتبط با ابعاد (طول، عرض و ارتفاع) را ارسال کنید. اما اگر این پارامتر را ارسال نکنید، حتما باید پارامترهای ابعاد را با مقادیر مجاز ارسال کنید.

این پارامتر مربوط به نسخه‌های 1 و 2 API تیپاکس است که در نسخه 3 و 4 نیازی به ارسال ان نیست

در نسخه های 3 و 4 ای پی آی تیپاکس، زمانی که جیسون ارسالی با اطلاعات مربوط به origin و destination پر شده باشد، مقادیر مرتبط با آیتم‌های senderAddressAndClient و receiverAddressAndClient بطور خودکار پر خواهند شد، در نتیجه نیازی به ارسال این آیتم‌ها حین ثبت سفارش نیست.

نسخه v4 به‌صورت event پیاده‌سازی شده و سفارشات بر روی صف (queue) قرار می‌گیره، بنابراین حتما باید success call back url و fail call back url در Request ارسالی وجود داشته باشد.

وب‌هوک یک مکانیزم ارتباطی کارآمد بین اپلیکیشن‌ها است که امکان تبادل خودکار و آنی اطلاعات را فراهم می‌کند. برخلاف روش سنتی “پولینگ” (Polling) که در آن یک اپلیکیشن باید به طور مداوم سرویس دیگر را برای دریافت اطلاعات جدید بررسی کند، وب‌هوک به سرویس مبدأ اجازه می‌دهد تا در لحظه وقوع یک رویداد (مانند تغییر وضعیت بسته پستی)، اطلاعات مربوطه را به صورت “پوش” (Push) به یک URL از پیش تعیین‌شده در اپلیکیشن مقصد ارسال کند. این امر باعث افزایش سرعت، کاهش سربار پردازشی و به‌روزرسانی آنی اطلاعات می‌شود. تفاوت اصلی بین نسخه 3 و 4 API ای‌تی‌پاکس در همین نحوه تبادل اطلاعات نهفته است: 1. نسخه 3 (API v3): این نسخه به صورت “همزمان” (Synchronous) عمل می‌کند. بدین معنی که تمامی عملیات مربوط به هر سفارش (ثبت، پردازش، و غیره) به صورت لحظه‌ای انجام شده و نتیجه بلافاصله برگردانده می‌شود. اگرچه در صورت داشتن توکن معتبر، ثبت سفارش دچار مشکل نمی‌شود، اما ماهیت همزمان این نسخه باعث تجمع بار پردازشی در صورت افزایش درخواست‌های همزمان می‌گردد. 2. نسخه 4 (API v4): این نسخه به صورت “مبتنی بر رویداد” (Event-Driven) و با استفاده از “صف‌گذاری” (Queue) پیاده‌سازی شده است. در این نسخه، ارائه URL برای “کال‌بک موفقیت” (Success Callback URL) و “کال‌بک شکست” (Fail Callback URL) الزامی است. این URLها همان اندپوینت‌های وب‌هوک هستند که ای‌تی‌پاکس تغییرات وضعیت بسته‌ها را به آن‌ها ارسال می‌کند. این معماری برای مشتریانی که قابلیت پیاده‌سازی وب‌هوک را دارند و به عملکرد بالا و مکانیزم‌های “تلاش مجدد” (Retry) نیاز دارند، ایده‌آل است. اما چرا استفاده از وب‌هوک در نسخه 4 API ای‌تی‌پاکس ضروری است؟ نسخه 4 ای‌تی‌پاکس به گونه‌ای طراحی شده است که با الگوی ترافیک لحظه‌ای و پرترافیک (مثلاً ۱۰۰۰ درخواست در لحظه) سازگار باشد. وب‌هوک امکان پردازش آنی و کارآمد این حجم از درخواست‌ها را فراهم می‌کند. شما با آماده‌سازی یک URL در سیستم خودتان که قادر به دریافت درخواست‌های HTTP POST از ای‌تی‌پاکس باشد و ثبت آن در تنظیمات، می‌توانید تغییرات وضعیت بسته‌ها را به محض وقوع دریافت و در سیستم خود به‌روزرسانی کنید. این رویکرد ضمن افزایش سرعت دریافت اطلاعات، بار پردازشی را روی سرورهای شما و ای‌تی‌پاکس کاهش می‌دهد و از به‌روز بودن دائمی اطلاعات اطمینان حاصل می‌کند.

این خطا مربوط به محدودیت نرخ درخواست (Rate Limit) در سرویس OmOrder تیپاکس است. بر اساس تنظیمات سرور، حداکثر ۱۰ درخواست در هر ثانیه برای هر کلاینت (بر اساس API Key یا IP) مجاز است. در صورتی که تعداد فراخوانی‌ها از این حد بیشتر شود، سامانه به‌صورت موقت مانع پردازش می‌شود و پیام خطای فوق (معمولاً همراه با وضعیت HTTP 429) برگردانده می‌شود. روش‌های پیشنهادی برای جلوگیری از خطا: 1. بین هر batch از درخواست‌ها وقفه‌ای حدود 100 تا 150 میلی‌ثانیه در نظر بگیرید. 2. در صورت امکان، چند مرسوله را به‌صورت گروهی (Bulk) داخل یک درخواست واحد ارسال کنید تا حجم فراخوانی‌ها کاهش یابد.

سرویس ال.تی.ال فضایی از حامل را طبق شرایط مشخص به مشتریان اختصاص می‌دهد. هر فضای واحد معادل مساحت یک باکس لاین (۱.۲×۱ مترمربع) بوده و حداکثر وزن مجاز آن ۳۰۰ کیلوگرم و ارتفاع مجاز ۲ متر است. در صورت تجاوز ابعاد یا وزن از این محدودیت‌ها، مشتری باید فضای جدیدی خریداری کند. برای هر فضای اختصاص‌یافته تنها یک مبدأ و یک مقصد قابل تعریف است. اگر مرسوله شامل چند بسته است، باید به‌صورت تجمیع‌شده و یکپارچه (در قالب باکس لاین شیرینگ شده، بچ یا گونی) ارسال شود. تخلیه و بارگیری مرسوله بر عهده مشتری است و در صورت تحویل مرسوله در باکس لاین، مسئولیت بازگشت آن با گیرنده خواهد بود. همچنین، محتویات مرسوله باید مجاز و مطابق گروه‌های کالایی مورد تأیید تیپاکس بوده و جزو اقلام ممنوعه ارسالی نباشد.

تیپاکس سه نوع سرویس برای ارسال مرسولات ارائه می‌دهد تا کاربران بر اساس سرعت مورد نیاز خود انتخاب کنند: در سرویس اکسپرس، بسته از نزدیک‌ترین نمایندگی جمع‌آوری شده و در مدت ۳ روز کاری به گیرنده تحویل می‌شود. در سرویس اکسپرس پلاس، بسته نیز توسط نزدیک‌ترین نمایندگی جمع‌آوری شده ولی با سرعت بالاتر، طی ۲۰ ساعت کاری تحویل داده می‌شود؛ برای استفاده از این سرویس باید بسته را تا ساعت ۱۷:۰۰ همان روز به نمایندگی تحویل دهید، در غیر این صورت ارسال آن به اولین نوبت کاری بعدی موکول خواهد شد. در نهایت، سرویس همان روز (Same Day) سریع‌ترین گزینه است که بسته را ظرف ۱۰ ساعت کاری به مقصد می‌رساند؛ کافی‌ست مرسوله تا ساعت ۱۴:۰۰ به نمایندگی تحویل داده شود تا حداکثر تا ساعت ۲۲:۰۰ همان روز به گیرنده برسد، و در صورت تحویل دیرتر از این زمان، ارسال در نخستین نوبت کاری روز آینده انجام می‌گیرد. لازم به ذکر است که سرویس‌های اکسپرس پلاس و همان روز فعلاً فقط در شهرهای تهران و البرز فعال هستند و سایر شهرها می‌توانند از سرویس اکسپرس استفاده کنند.

اگر برای پارامتر serviceId مقادیر 1 (ارسال زمینی همان روز)، 2 (ارسال زمینی یک روزه)، 3 (ارسال زمینی دو روزه)، 4 (ارسال زمینی سه روزه)، 5 (اکسپرس ویژه بین شهری) و 7 (اکسپرس درون شهری) ارسال شود، نوع قرارداد نهایی اکسپرس خواهد بود.

برای پارامتر paymentType مقادیر 10 (سمت فرستنده-اعتباری)، 20 (سمت گیرنده-پسکرایه)، 30 (سمت گیرنده-پرداخت در محل)، 40 (سمت فرستنده-پرداخت در محل)، 50 (سمت فرستنده-پرداخت از کیف پول) و 80 (سمت فرستنده-نقدی) مجاز هستند. در صورت ارسال مقادیر10 و 40، هزینه خدمات از اعتبار فرستنده (صاحب حساب کاربری در ای تیپاکس) در هر دو حالت کسر خواهد شد، اما در حالت سمت فرستنده-پرداخت در محل (40)، سیستم بصورت اتوماتیک ارزش مرسوله را به‌جای COD جای گذاری می کند، در صورتیکه پارامتر COD ارسال نشود، یا مقدار آن کمتر از ارزش مرسوله نباشد. همچنین در صورت ارسال مقادیر20 (سمت گیرنده-پسکرایه) و 30 (سمت گیرنده-پرداخت در محل) نیز، در هر دو حالت هزینه خدمات از گیرنده دریافت خواهد شد، اما در حالت سمت گیرنده-پرداخت در محل ، سیستم بصورت اتوماتیک ارزش مرسوله را به‌جای COD جای گذاری می کند، در صورتیکه پارامتر COD ارسال نشود، یا مقدار آن کمتر از ارزش مرسوله نباشد. همچنین در صورت ارسال پارامتر 80 (سمت فرستنده-نقدی) نیز نماینده تیپاکس در زمان جمع آوری، بصورت نقد هزینه ارسال را از فرستنده دریافت میکند. بنابراین در صورت ثبت سفارش در این حالت از پرداخت لازم است تا پارامتر cashAmount مقداردهی و ارسال شود.

در این حالت، سفارش پس از گذشت ۳۰ روز (مدت زمان Expire) به‌صورت خودکار منقضی شده و ابطال می‌گردد.

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

در نسخه 4 API تیپاکس، معماری به صورت «مبتنی بر رویداد» (Event‑Driven) و «غیرهمزمان» (Async) طراحی شده است. به همین دلیل، نتیجه پردازش هر سفارش بلافاصله در پاسخ Request برگردانده نمی‌شود. به‌جای آن، شما باید دو آدرس (URL) در اختیار تیپاکس قرار دهید تا نتیجه پردازش را در زمان مناسب برای شما ارسال کند: 1. کال‌بک موفقیت (Success Callback URL): این URL آدرسی در سیستم شماست که تیپاکس پس از پردازش موفق درخواست (مثلاً ثبت موفق سفارش یا هر مرحله‌ای که در صف پردازش بدون خطا کامل شود) به آن یک درخواست HTTP POST ارسال می‌کند. 2. کال‌بک شکست (Fail Callback URL): این URL برای زمانی است که پردازش درخواست با خطا مواجه شود. در چنین حالتی تیپاکس به‌جای پاسخ موفق، اطلاعات خطا را به Fail Callback URL ارسال می‌کند. در نتیجه وجود این دو آدرس باعث می‌شود بتوانید بدون انتظار، درخواست‌ها را با سرعت بالا ارسال کنید، عملیات پشت‌صحنه را صف‌بندی و پردازش کنید، سیستم شما نتیجه را دقیق و آنی دریافت کند و همچنین سازوکار «Retry» و پایداری بالاتر برای شما فراهم شود.

اگر در جیسون ارسالی شما به تیپاکس، پارامتر packingid وجود نداشته باشد، سیستم به‌صورت اتومات نوع بسته شما را (نیاز به بسته بندی ندارد) در نظر خواهد گرفت

مبلغ نهایی قرارداد برابر است با مجموع هزینه خدمات، هزینه بسته‌بندی، مالیات بر ارزش افزوده و هزینه جبران خسارت (پوشش ارزش کالا). این مبلغ در پاسخ API با پارامتر finalPrice بازگردانده می‌شود.

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

توجه: در صورت ارسال مقادیر فراتر از این محدودیت‌ها، سیستم با خطای اعتبارسنجی (Validation Error) مواجه خواهد شد.

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

برای دریافت (Get) شناسه‌های محصولات جدید (Product IDs)، لطفاً endpoint زیر را فراخوانی (Call) نمایید:

URL: https://integrationapi.tipax.ir/api/OM/v3/Customers/myproducts

با فراخوانی این آدرس، لیستی از Product IDها در پاسخ دریافت خواهد شد.

● بسته بندی اکو پک تخفیف ندارد.

● جمع اوری در محل نمایندگی می باشد.

● نوع بسته بندی فقط فلایر A4 به ابعاد 21.5*30*5 می باشد.

● وزن مرسوله تا 1 کیلوگرم است.

● ارزش مرسوله 15000000 ریال می باشد.

با توجه به معماری سامانه ای‌تیپاکس، پیش از Call کردن سرویس Pricing لازم است تا ابتدا یک سفارش ثبت و بارکد دریافت کنید و سپس مجدد سرویس Pricing را Call کنید و Response Time را بررسی کنید.

سرویس لجستیک معکوس برای جمع‌آوری و بازگرداندن مرسولات از گیرنده به فرستنده طراحی شده است. این سرویس در سامانه مشابه ثبت سفارش عادی انجام می‌شود، با این تفاوت که تمامی هزینه‌های حمل تنها توسط فرستنده پرداخت می‌شود و امکان پرداخت هزینه توسط گیرنده وجود ندارد. پس از ثبت سفارش، یک پیامک حاوی بارکد مرسوله و لینک مربوط به رهگیری سفارش برای گیرنده ارسال می‌شود. گیرنده هنگام تحویل مرسوله به نماینده تیپاکس، کافی است بارکد دریافتی را ارائه دهد. نمونه پیامک ارسالی:* مشتری محترم تیپاکس، سلام بسته مرجوعی شما توسط [نام ثبت‌کننده] با بارکد [بارکد مرسوله] در سامانه ثبت شد. لطفاً هنگام تحویل، بارکد را ارائه دهید. لینک: [لینک سفارش] تیپاکس - 0218457 این سرویس مناسب کسب‌وکارهایی است که نیاز به دریافت کالاهای مرجوعی، جمع‌آوری اسناد، نمونه کالا یا سایر مرسولات از مشتریان خود دارند.

برای مشاهده تمامی دست‌رشته‌ها و جزئیات کامل وضعیت مرسوله، از متد POST استفاده کنید و درخواست را به آدرس زیر ارسال نمایید. مقدار trackingInput را با شماره قرارداد مرسوله جایگزین کرده و در Body درخواست یک آبجکت خالی ({}) ارسال کنید. POST https://omapi.tipax.ir/api/v2/Tracking/GetJetTrackingDetail?trackingInput=3616202582144234437
Body:{}
نکته: به جای 3616202582144234437، شماره قرارداد موردنظر خود را قرار دهید.

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

آدرس API: https://omapi.tipax.ir/api/v2/client

نمونه JSON (پیلود) مورد نیاز:

متدد : PUT

{
    "fullName": "string",
    "mobile": "string",
    "nationalId": "string",
    "telephonNumber": "string",
    "id": "string"
}
        

تمامی فیلدها به صورت رشته (string) ارسال می‌شوند و فیلد id برای شناسایی مشتری الزامی است.

ثبت سفارش سرویس همان روز (Same Day) در ای‌تیپاکس دارای شرایط و محدودیت‌های زیر است:

1. محدوده ثبت سفارش: ثبت سفارش سرویس Same Day فقط برای مبدا و مقصد تهران به تهران امکان‌پذیر است.

2. وزن مرسوله: وزن بسته باید حداکثر 12 کیلوگرم باشد.

3. ابعاد بسته: حداکثر ابعاد بسته‌بندی باید 37 × 37 × 15 سانتی‌متر باشد تا مرسوله امکان قرارگیری در لاکر را داشته باشد.

4. تأیید آدرس مشتری: مشتری باید پیش از ثبت سفارش، آدرس خود را از طریق لینک مربوطه تأیید کرده باشد. پس از انتخاب شماره مشتری، در بخش آدرس‌ها می‌توانید لیست آدرس‌های پیشنهادی را مشاهده کرده و آدرس تأییدشده مشتری را انتخاب نمایید.

5. نوع بسته‌بندی: ثبت سفارش Same Day فقط برای بسته (کارتن) و پاکت امکان‌پذیر است و استفاده از اکوپک برای این سرویس امکان‌پذیر نیست.

6. نحوه عملکرد سرویس: در این نوع ثبت سفارش، مرسوله در ابتدا برای ارسال به آدرس مشتری در نظر گرفته می‌شود؛ هم‌زمان با ثبت سفارش، یک لاکر نیز برای مشتری رزرو می‌شود. در صورتی که مشتری در زمان مراجعه مأمور توزیع در آدرس حضور نداشته باشد، بسته به لاکر رزروشده منتقل شده و در آنجا قرار می‌گیرد تا مشتری بتواند برای دریافت مرسوله به لاکر مراجعه کند. هزینه رزرو لاکر تا 48 ساعت رایگان می‌باشد.

با مختومه شدن سفارش، رزرو مربوط به لاکر نیز به‌صورت خودکار مختومه خواهد شد.

خلاصه شرایط: تهران به تهران، حداکثر وزن 12 کیلوگرم، حداکثر ابعاد 37 × 37 × 15 سانتی‌متر، آدرس تأییدشده مشتری و فقط بسته یا پاکت.