راهنمای اتصال API تیپاکس به فروشگاه آنلاین شما

برای دریافت کلید API تیپاکس، به پلتفرم تست این سرویس در آدرس omtest.tipax.ir مراجعه کنید.

سپس از بخش حساب کاربری > تنظیمات سرویس API، روی گزینه «نمایش» در مقابل کلید خصوصی خود کلیک کنید.

در این قسمت، امکان کپی کردن یا تغییر کلید API برای شما فراهم شده است.

برای استفاده از متدهایی که نیاز به احراز هویت (Authentication) دارند، ابتدا روی گزینه «Authorize» کلیک کنید.

در پنجره‌ی بازشده، نام کاربری و رمز عبور خود را که هنگام ثبت‌نام در omtest.tipax.ir ایجاد کرده‌اید، وارد کنید.

پس از تأیید اطلاعات، امکان دسترسی به متدهای محافظت‌شده API برای شما فعال خواهد شد.

برای دریافت Access Token و Refresh Token، مراحل زیر را دنبال کنید:

1. در بخش Account، یک درخواست از طریق متد POST ارسال کنید.
2. در Payload درخواست، اطلاعات زیر را وارد کنید:
   • نام کاربری (Username)
   • رمز عبور (Password)
   • کلید API

پس از ارسال موفقیت‌آمیز درخواست، دو مقدار زیر را دریافت خواهید کرد:

• Access Token: برای احراز هویت از طریق متد Bearer Token و ارسال درخواست به مسیرهایی که نیاز به احراز هویت دارند، استفاده می‌شود.
• Refresh Token: برای تمدید اعتبار Access Token بدون نیاز به ورود مجدد به کار می‌رود.

زمانی که accessToken قبلی منقضی شود، برای دریافت توکن جدید باید از متد Refresh Token استفاده کنید.

پارامترهای مورد نیاز:

• accessToken (توکن قبلی که اعتبار آن به پایان رسیده است)
• refreshToken (که هنگام دریافت accessToken قبلی دریافت کرده‌اید)

مراحل دریافت accessToken جدید:

1. یک درخواست POST با Payload شامل پارامترهای بالا ارسال کنید.
2. پس از موفقیت‌آمیز بودن درخواست، یک accessToken جدید همراه با زمان انقضای به‌روز شده دریافت خواهید کرد.

ویرایش اطلاعات مشتریان حقیقی در API ای‌تیپاکس

در بخش ActualCustomers از API ای‌تیپاکس، امکان ویرایش اطلاعات مشتریان ثبت‌شده وجود دارد.

مراحل ویرایش اطلاعات مشتری:

1. یک درخواست PUT به همراه Payload موردنظر ارسال کنید.
2. در پاسخ درخواست، مقدار True یا False دریافت خواهید کرد که نشان‌دهنده موفقیت یا عدم موفقیت عملیات است.

نحوه افزودن آدرس در دفترچه آدرس

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

مشاهده دفترچه آدرس

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

دریافت لیست شهرهای تحت پوشش تیپاکس

در بخش Cities (شهرها)، با ارسال یک درخواست GET می‌توانید فهرست شهرهایی که تیپاکس در آن‌ها فعال است، به همراه شناسه (ID) هر شهر دریافت کنید. این اطلاعات برای ثبت و پردازش سفارش‌ها مورد استفاده قرار می‌گیرد.

مدیریت مشتریان و استعلام موجودی کیف پول در API تیپاکس

در بخش Customers (مشتریان)، امکان مدیریت اطلاعات مشتریان (چه فرستنده و چه گیرنده) وجود دارد. با ثبت اطلاعات آن‌ها در این بخش، می‌توانید هنگام ثبت سفارش، به‌جای وارد کردن جزئیات کامل، از آیدی مشتری استفاده کنید.

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

دریافت اطلاعات مالی و تراکنش‌ها در API تیپاکس

در بخش Financial (مالی)، با ارسال درخواست GET و بدون نیاز به ارسال پیلود، می‌توانید به اطلاعات مالی و تاریخچه تراکنش‌های خود دسترسی پیدا کنید. این بخش به شما امکان می‌دهد تراکنش‌های انجام‌شده را بررسی کرده و مدیریت بهتری بر امور مالی خود داشته باشید.

مدیریت سفارش‌ها در API تیپاکس

در بخش Orders (سفارش‌ها)، امکان ثبت و مدیریت سفارش‌ها از طریق متدهای مختلف فراهم شده است. در ادامه، به بررسی این متدها و نحوه استفاده از آن‌ها می‌پردازیم.

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

پارامترهای کلیدی برای ایجاد سفارش از طریق API

با استفاده از متدهای زیر می‌توانید آیدی‌های مورد نیاز را به دست آورید:

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

برای شروع می‌توانید از پیلود زیر به‌عنوان نمونه دریافت کنید.

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

می‌توانید با اعمال تغییرات کمی روی پیلود بالا، از آن برای ثبت سفارش با متدهای دیگر استفاده کنید.

پس از ثبت موفقیت‌آمیز سفارش پیلودی، مشابه تصویر زیر، شامل بارکد بسته (trackingCode) و شماره سفارش (orderId) را دریافت می‌کنید.

ثبت سفارش با آدرس مبدا (فرستنده) تعریف شده (ذخیره شده)

برای ثبت سفارش با آدرس مبدا از پیش تعریف‌شده، می‌توانید از این متد API ای تیپاکس استفاده کنید:

/api/OM/v3/Orders/WithPreDefinedOrigin

در صورتی که سفارش‌های شما از آدرس مبدا (فرستنده) یکسان ارسال می‌شوند، می‌توانید با استفاده از این متد و ارسال ID آدرسی که قبلاً در دفترچه آدرس خود ثبت کرده‌اید، بدون نیاز به وارد کردن مجدد آدرس مبدا، سفارش خود را ثبت کنید.

• originalId آدرس تعریف‌شده در لیست آدرس‌های کاربر

برای دریافت این مقدار می‌توانید از API زیر استفاده کنید:

/api/OM/v3/Addresses/Book

بقیه موارد مشابه یک سفارش معمولی (order) می‌باشد.

ثبت سفارش با آدرس مقصد (گیرنده) تعریف شده (ذخیره شده)

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

ثبت سفارش با فرستنده و گیرنده ذخیره شده

/api/OM/v3/Orders/WithPreDefinedOriginAndDestination

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

در این متد:

originalId: آدرس مبدا (فرستنده) که قبلاً در دفترچه آدرس شما ثبت شده است.

destinationId: آدرس مقصد که قبلاً در دفترچه آدرس شما ثبت شده است.

بقیه موارد مشابه یک سفارش معمولی (order) است.

ثبت سفارش از طریق بسته (parcel) ذخیره‌شده

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

ابتدا باید با ارسال درخواست POST به آدرس /api/OM/v3/ParcelBooks اطلاعات مربوط به بسته خود را ثبت کنید.

درصورتی‌که از قبل بسته خود را ثبت کرده‌اید، کافی است id بسته موردنظر را از آدرس /api/OM/v3/ParcelBooks  دریافت کنید.

دقت کنید که مقادیر packageContentId باید با مقدار packType هنگام ثبت سفارش متناسب باشد.

سپس هنگام ثبت سفارش، فقط کافی است ID بسته را در پارامتر “parcelBookId” ارسال کنید.

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

ابطال سفارش با API

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

/api/OM/v3/Orders/CancelOrder/{orderId}

با ارسال درخواست POST و پارامتر orderId به‌عنوان کد سفارش، می‌توانید سفارش موردنظر خود را ابطال کنید.

API ای تیپاکس  لیست محتوا (PackContentRates)

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

برای مثال اگر از packType = 20 (نوع بسته) برای ثبت سفارش استفاده کنید، packageContentId فقط می‌تواند یکی از مقادیر 1 و 9 باشد. (همانند تصویر زیر)

API ای تیپاکس  انواع بسته‌بندی (PackingPrices)

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

API ای تیپاکس بسته‌های ذخیره‌شده (ParcelBooks)

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

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

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

API ای تیپاکس بسته‌ها (Parcels)

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

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

ابطال بسته­‌ها تا زمانی که در حالت (State) جمع­‌آوری قرار دارند، امکان­‌پذیر است.

همچنین می‌توانید جزئیات مربوط به هزینه بسته را دریافت کنید.

API ای تیپاکس انواع بسته (ParcelType)

از طریق این متد می‌توانید با ارسال پیلود خالی مقادیر مختلف انواع بسته (parcelType) (گونی، پاکت و بسته) را دریافت کنید.

سپس هنگام ثبت سفارش، از طریق پارامتر parcelTypeId مقدار موردنظر را برای بسته ثبت کنید.

API ای تیپاکس روش‌های پرداخت (PaymentType)

می‌توانید با استفاده از این متد و ارسال پیلود خالی، انواع روش‌های پرداخت هزینه ارسال (paymentType) را دریافت کنید. هنگام ثبت سفارش، مقدار موردنظر را از طریق پارامتر paymentType برای بسته‌ی ارسالی ثبت کنید.

API ای تیپاکس برآورد هزینه (Pricing)

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

برای دریافت حداقل هزینه ارسال تنها با توجه به شهر مبدا و مقصد (بدون نیاز به مشخصات بسته و آدرس دقیق)، از این متد استفاده کنید

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

API ای تیپاکس تیکت پشتیبانی (Ticketing)

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

API ای تیپاکس رهگیری بسته‌ها (Tracking)

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

• رهگیری بسته از طریق بارکد

با استفاده از این متد API ای تیپاکس، می‌توانید با ارسال درخواست GET همراه با پارامتر trackingInput، که همان بارکد بسته است، اطلاعات مربوط به بسته و وضعیت فعلی آن را در پیلود پاسخ، با عنوان contractStatusName دریافت کنید.

وضعیت‌های (State) مختلفی که در پاسخ به API مشاهده می‌کنید، به شرح زیر است:

• رهگیری بسته از طریق شماره قرارداد

با استفاده از این متد و ارسال درخواست GET همراه با پارامتر contractCode، شماره قرارداد بسته، می‌توانید اطلاعات مربوط به بسته را با جزئیات بیشتر و همچنین وضعیت فعلی آن دریافت کنید.

• رهگیری بسته از طریق شماره سفارش

با استفاده از این متد و ارسال درخواست GET همراه با پارامتر orderId، شماره سفارش بسته، می‌توانید اطلاعات مربوط به بسته و وضعیت فعلی آن دریافت کنید.

• رهگیری چندین بسته به صورت همزمان از طریق بارکد

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

• رهگیری بسته از طریق کد رهگیری اختصاصی (traceCode)

با استفاده از این متد و ارسال درخواست POST همراه با پارامتر traceCode، که کد سفارش اختصاصی تعریف شده برای بسته است، می‌توانید بسته مورد نظر را رهگیری کنید.

ارتباط با پشتیبانی ای تیپاکس

در هنگام بروز خطا، علاوه برکد وضعیت HTTP یا همان HTTP Status Code می‌توانید از معادل فارسی خطاهای API استفاده کنید.

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

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