چگونه از API ای تیپاکس استفاده کنیم؟
API ای تیپاکس به‌عنوان یک رابط کاربری قدرتمند، این امکان را برای توسعه‌دهندگان فراهم می‌آورد تا خدمات تیپاکس را به‌سادگی در سیستم‌های خود ادغام کرده و از قابلیت‌های آن بهره‌مند شوند.
گزارش MuleSoft 2023 نشان می‌دهد که استفاده از API به میزان قابل توجهی به تولید درآمد کسب‌وکارها کمک می‌کنند، به‌طوری که تا سال 2025، 40 درصد از درآمد سازمانی از پیاده‌سازی‌های مرتبط با API به‌دست آمده است.
در این مقاله، به‌صورت گام‌به‌گام نحوه استفاده از API ای تیپاکس را بررسی خواهیم کرد تا با اتصال مستقیم به سیستم سفارش‌گذاری تیپاکس، از امکانات آن برای بهینه‌سازی مدیریت ارسال‌های خود استفاده کنید.
آنچه در این مقاله می‌خوانید
ابتدا یک حساب کاربری در پلتفرم تست API ای تیپاکس به آدرس omtest.tipax.ir ایجاد کنید. برای یادگیری از نحوه ایجاد حساب، می‌توانید به آموزش ETipax مراجعه کنید.
پس از ثبت‌نام، می‌توانید با مراجعه به پروفایل خود، کلید اختصاصی API ای تیپاکس را دریافت کنید.
پارامترهای API تیپاکس
دریافت کلید API تیپاکس
- وارد پلتفرم تست ای تیپاکس، به آدرس omtest.tipax.ir شوید.
- در بخش حساب کاربری > تنظمیات سرویس API، روی گزینه نمایش، روبه‌روی کلید خصوصی شما کلیک کنید
- در این بخش می‌توانید کلید API خود را کپی کرده و یا آن را تغییر دهید.
دریافت مستندات API ای تیپاکس
مراحل استفاده از متدهایی که نیاز به احراز هویت (Authentication) دارند.
- روی گزینه Authorize، همانند تصویر زیر، کلیک کنید.
- در پنجره بازشده، نام کاربری و رمز عبوری را که هنگام ثبت‌نام در omtest.tipax.ir ایجاد کرده‌اید، وارد کنید.
- پس از تایید اطلاعات، می‌توانید به متدهای محافظت‌شده API دسترسی داشته باشید.
API ای تیپاکس > حساب کاربری (Account)
توکن به‌روز رسانی
/api/OM/v3/Account/RefreshToken
توکن احراز هویت
/api/OM/v3/Account/token
مراحل دریافت Access Token و Refresh Token
1- در بخش Account، یک درخواست از طریق متد POST ارسال کنید.
2- در Payload درخواست، اطلاعات زیر را قرار دهید:
- نام کاربری (Username)
- رمز عبور (Password)
- کلید API
3- پس از ارسال موفقیت‌آمیز درخواست، دو مقدار زیر را دریافت خواهید کرد:
- accessToken: برای احراز هویت از طریق متد Bearer Token برای ارسال درخواست به آدرس‌هایی (route) که نیاز به احراز هویت دارند، استفاده می‌شود.
- refreshToken: برای تمدید اعتبار accessToken بدون نیاز به ورود مجدد استفاده می‌شود.
دریافت accessToken جدید با استفاده از refreshToken
برای دریافت accessToken جدید زمانی که accessToken قبلی منقضی شده است، از متد مخصوص Refresh Token استفاده می‌کنیم.
پارامترهای مورد نیاز برای دریافت Access Token جدید:
- accessToken (قدیمی که منقضی شده است)
- refreshToken (که هنگام دریافت accessToken قبلی دریافت کرده بودید)
مراحل دریافت accessToken جدید:
- یک درخواست POST با Payload درخواست شامل پارامترهای بالا ارسال کنید.
- در صورت ارسال موفقیت‌آمیز درخواست، یک accessToken جدید به همراه زمان انقضای جدید دریافت می‌کنید.
API ای تیپاکس > مشتری حقیقی (ActualCustomers)
در قسمت ActualCustomer، با ارسال درخواست PUT و پیلود درخواستی، می‌توانید مشتریانی را که در گذشته ثبت کرده‌اید، ویرایش کنید. پس از ارسال درخواست، با توجه به پاسخ (True/False)، می‌توانید از موفقیت‌آمیز بودن عملیات مطلع شوید.
API ای تیپاکس > آدرس‌ها (Addresees)
افزودن آدرس به دفترچه آدرس
/api/OM/v3/Addresses/Book
مراحل افزودن آدرس
می‌توانید با ثبت آدرس‌های پراستفاده خود در دفترچه آدرس، از ID این آدرس‌ها، به‌جای وارد کردن آن‌ها به‌صورت کامل استفاده کنید.
دریافت دفترچه آدرس
/api/OM/v3/Addresses/Book
دریافت دفترچه آدرس
برای مشاهده آدرس‌های ذخیره‌شده قبلی، می‌توانید از این متد استفاده کنید. آدرس‌های ثبت‌شده به شرح زیر قابل تشخیص هستند:
| peopleAddressTypeId | 1 | آدرس فرستنده |
| peopleAddressTypeId | 2 | آدرس گیرنده |
| peopleAddressTypeId | 3 | آدرس عمومی |
API ای تیپاکس > شهرها (Cities)
در قسمت Cities (شهرها)، با ارسال درخواست GET، می‌توانید لیست و آیدی شهرهایی که تیپاکس در آن‌ها فعالیت دارد را دریافت کرده و برای ثبت سفارش از آن‌ها استفاده کنید.
API ای تیپاکس > مشتریان (Customers)
در قسمت Customers، علاوه بر مدیریت مشتریان (گیرنده یا فرستنده)، با ثبت اطلاعات آن‌ها، می‌توانید از آیدی به جای اطلاعات کامل مشتریان هنگام ثبت سفارش استفاده کنید.
همچنین در همین قسمت می‌توانید استعلام موجودی کیف پول خود را دریافت کنید.
API ای تیپاکس > مالی (Financial )
در قسمت Financial، می‌توانید اطلاعات مالی و تاریخچه تراکنش‌ها را با ارسال درخواستGET، بدون نیاز به پیلود مشاهده کنید.
API ای تیپاکس > سفارش‌ها (Orders)
ثبت سفارش
/api/OM/v3/Orders
در این بخش می‌توانید با متدهای مختلف سفارش خود را ثبت کنید که به بررسی این متدها می‌پردازیم:
برای ثبت سفارش از طریق این متد، باید اطلاعات مختلفی از جمله مشخصات فرستنده و گیرنده، نوع بسته و نوع پرداخت، و سایر جزئیات سفارش وارد شوند.
پارامترهای مهم برای ثبت سفارش با API
| Parameter | Description | Possible Values |
|---|---|---|
| PackType | نوع بسته‌بندی | 10: پاکت |
| 20: بسته | ||
| 50: مینی پک | ||
| PaymentType | نوع پرداخت | 10: سمت فرستنده - اعتباری |
| 20: سمت گیرنده - پسکرایه | ||
| 30: سمت گیرنده - پرداخت در محل | ||
| 40: سمت فرستنده - پرداخت در محل | ||
| 50: سمت فرستنده - پرداخت از کیف پول | ||
| 80: سمت فرستنده - نقدی | ||
| PickupType | نوع جمع‌آوری | 10: جمع‌آوری در محل مشتری |
| 20: جمع‌آوری در نمایندگی | ||
| DistributionType | نوع تحویل | 10: تحویل در محل مشتری |
| 20: تحویل در نمایندگی | ||
| ServiceId | نوع سرویس | 1: ارسال زمینی همان روز |
| 2: ارسال زمینی یک روزه | ||
| 3: ارسال زمینی دو روزه | ||
| 5: اکسپرس ویژه بین‌شهری | ||
| 6: بین‌الملل | ||
| 7: اکسپرس درون شهری | ||
| EnableLabelPrivacy | جزئیات اطلاعات فرستنده و گیرنده بر روی لیبل چاپ نشود | true / false |
| customerSubstationCode | کد شعبه | [کد شعبه] |
| PackingId (packagingPrices) | نوع بسته‌بندی (مثال: کارتن سایز 1 با آیدی 3) | [ID بسته‌بندی] |
| packageContentId (packContentRate) | محتویات (مثل: عمومی، شکستنی) | [ID محتویات] |
| parcelTypeId | آیدی نوع مرسوله | [ID نوع مرسوله] |
| parcelbookId | آیدی بسته تعریف‌شده مشتری | [ID بسته مشتری] |
| traceCode | کد سفارشی برای رهگیری مرسوله (اختیاری) | [کد سفارشی] |
traceCode: اگر می‌خواهید سفارش‌های ثبت شده خود را با استفاده از کد شخصی رهگیری کنید، این پارامتر را هنگام ثبت سفارش ارسال کنید، درغیر این‌صورت این مقدار خالی بگذارید.
شما می‌توانید از این مقدار در متد tracking هنگام رهگیری بسته استفاده کنید.
packageContentId: این مقدار برای ثبت سفارش الزامی (required) بوده و مقدار آن باید با پارامتر packType متناسب باشد. برای توضیحات بیشتر اطلاعات مربوط به PackContentRates را در همین مقاله را مطالعه کنید.
با استفاده از متدهای زیر می‌توانید آیدی‌های مورد نیاز را به دست آورید:
| متد (Method) | آیدی (ID) |
|---|---|
| packagingPrices | PackagingId |
| packContentRate | PackagContentId |
| parcelType | ParcelTypeId |
| parcelBooks | ParcelBookId |
پس از به دست آوردن آیدی‌ها، پیلودی مشابه تصویر زیر خواهید داشت که با ارسال آن می‌توانید بارکد سفارش را دریافت و پرینت کنید.
برای شروع می‌توانید از پیلود زیر به‌عنوان نمونه دریافت کنید.
با تغییر پارامترهای مربوط به سفارش که در بالا توضیح داده شد، می‌توانید سفارش خود را شخصی‌سازی کنید.
برای مشاهده نمونه یک پیلود روی علامت "+" کلیک کنید، همچنین برای استفاده از این پیلود می‌توانید با کلیک روی "Copy" آن را کپی کنید.
{
"packages": [
{
"cod": 0,
"origin": {
"cityId": 1262,
"fullAddress": "تهران، خیابان مطهری، نرسیده به سهروردی، پلاک ۱۰۰",
"floor": "0",
"unit": "100",
"postalCode": "1587545758",
"latitude": "35.724332",
"longitude": "51.434650",
"no": "127",
"description": "",
"beneficiary": {
"phone": "09121111111",
"fullName": "تست ",
"mobile": "09121111111"
}
},
"destination": {
"cityId": 1870,
"fullAddress": "بل احمد نیا",
"floor": "2",
"unit": "12",
"postalCode": "1587545756",
"latitude": "35.724332",
"longitude": "51.434650",
"no": "10",
"description": "",
"beneficiary": {
"phone": "09121111111",
"fullName": "محمد",
"mobile": "09121111111"
}
},
"weight": 1,
"packageValue": 400000,
"length": 10,
"width": 10,
"height": 10,
"packingId": 0,
"packageContentId": 1,
"packType": 20,
"parcelTypeId": 0,
"parcelBookId": 0,
"serviceId": 1,
"enableLabelPrivacy": false,
"paymentType": 20,
"pickupType": 10,
"distributionType": 10,
"cashAmount": 0
}
]
}
می‌توانید با اعمال تغییرات کمی روی پیلود بالا، از آن برای ثبت سفارش با متدهای دیگر استفاده کنید.
پس از ثبت موفقیت‌آمیز سفارش پیلودی، مشابه تصویر زیر، شامل بارکد بسته (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” ارسال کنید.
هنگام ثبت سفارش از طریق بسته ذخیره‌شده، دیگر نیازی به ارسال اطلاعات مربوط به بسته مانند وزن، طول، ارتفاع و… نیست. به‌جای آن، می‌توانید این موارد را با مقدار “صفر” ارسال کنید.
پیلود نمونه ثبت سفارش از طریق بسته ذخیره شده
“weight”: 0,
“packageValue”: 0,
“length”: 0,
“width”: 0,
“height”: 0,
“packingId”: 0,
“packageContentId”: 0,
“cod”: 0,
“packType”: 0,
“parcelTypeId”: 0,
ابطال سفارش با API
برای ابطال سفارش، می‌توانید از این متد استفاده کنید:
/api/OM/v3/Orders/CancelOrder/{orderId}
با ارسال درخواست POST و پارامتر orderId به‌عنوان کد سفارش، می‌توانید سفارش موردنظر خود را ابطال کنید.
API ای تیپاکس > لیست محتوا (PackContentRates)
/api/OM/v3/PackContentRates
از طریق این متد می‌توانید لیست مقادیر مختلف محتویات بسته را دریافت کنید. این مقادیر هنگام ثبت سفارش، از طریق پارامتر packageContentId ارسال می‌شوند.
برای مثال اگر از packType = 20 (نوع بسته) برای ثبت سفارش استفاده کنید، packageContentId فقط می‌تواند یکی از مقادیر 1 و 9 باشد. (همانند تصویر زیر)
API ای تیپاکس > انواع بسته‌بندی (PackingPrices)
/api/OM/v3/PackingPrices
از طریق این متد می‌توانید لیست مقادیر مختلف انواع بسته‌بندی را از طریق API ای تیپاکس دریافت کنید. این مقادیر هنگام ثبت سفارش، از طریق پارامتر PackingId ارسال می‌شوند.
API ای تیپاکس > بسته‌های ذخیره‌شده (ParcelBooks)
/api/OM/v3/ParcelBooks
با استفاده از این متد، می‌توانید اطلاعات بسته‌هایی (parcel) را که از قبل تعریف کرده‌اید، مشاهده کنید. هنگام ثبت سفارش، به جای وارد کردن تمام مشخصات بسته، می‌توانید parcelbookId (آیدی بسته) را ارسال کنید.
افزودن بسته جدید به لیست بسته‌های مشتری
/api/OM/v3/ParcelBooks
می‌توانید با ذخیره کردن مشخصات بسته‌های پرتکرار، هنگام ثبت سفارش به‌جای وارد کردن اطلاعات تکراری از ID آن استفاده کنید.
| packType | نوع بسته | 10: پاکت 20: بسته 50: مینی پک |
| packageContentId | محتوای بسته | API: /api/OM/v3/PackContentRate |
| packingId | نوع بسته‌بندی | API: /api/OM/v3/PackingPrices |
” isUnusual “: آیا محتویات بسته نامتعارف است (true/false)
API ای تیپاکس > بسته‌ها (Parcels)
از طریق متدهای موجود در این بخش می‌توانید اطلاعات بسته‌های مربوط به یک سفارش را دریافت کنید
/api/OM/v3/Parcels/GetByOrderId/{orderId}
همچنین، می‌توانید با استفاده از بارکد بسته‌ها، آن‌هایی را که به اشتباه ثبت شده‌اند، ابطال کنید.
/api/OM/v3/Parcels/Cancel/{trackingCode}
ابطال بسته‌ها تا زمانی که در حالت (State) جمع‌آوری قرار دارند، امکان‌پذیر است.
همچنین می‌توانید جزئیات مربوط به هزینه بسته را دریافت کنید.
/api/OM/v3/Parcels/GetPriceDetailByTrackingCode/{trackingCode}
API ای تیپاکس > انواع بسته (ParcelType)
/api/OM/v3/ParcelType/Search
از طریق این متد می‌توانید با ارسال پیلود خالی مقادیر مختلف انواع بسته (parcelType) (گونی، پاکت و بسته) را دریافت کنید.
سپس هنگام ثبت سفارش، از طریق پارامتر parcelTypeId مقدار موردنظر را برای بسته ثبت کنید.
API ای تیپاکس > روش‌های پرداخت (PaymentType)
/api/OM/v3/PaymentType/Search
می‌توانید با استفاده از این متد و ارسال پیلود خالی، انواع روش‌های پرداخت هزینه ارسال (paymentType) را دریافت کنید. هنگام ثبت سفارش، مقدار موردنظر را از طریق پارامتر paymentType برای بسته‌ی ارسالی ثبت کنید.
API ای تیپاکس > برآورد هزینه (Pricing)
/api/OM/v3/Pricing
با استفاده از متدهای موجود در این بخش، می‌توانید پیش از ثبت سفارش، برآورد هزینه ارسال را با توجه به مشخصات بسته و شهر مبدا و مقصد انجام دهید.
برای دریافت حداقل هزینه ارسال تنها با توجه به شهر مبدا و مقصد (بدون نیاز به مشخصات بسته و آدرس دقیق)، از این متد استفاده کنید
/api/OM/v3/Pricing/Min
می‌توانید از متد زیر برای برآورد هزینه ارسال با استفاده از مشخصات بسته و آیدی آدرس‌هایی که از قبل تعریف کرده‌اید، استفاده کنید.
/api/OM/v3/Pricing/WithAddressId
API ای تیپاکس > تیکت پشتیبانی (Ticketing)
می‌توانید با استفاده از متدهای موجود در این بخش، تمام امور مربوط به تیکت‌های حساب کاربری ای تیپاکس خود را مدیریت کنید.
API ای تیپاکس > رهگیری بسته‌ها (Tracking)
در این بخش، با روش‌های مختلفی می‌توانید بسته‌های خود را رهگیری کنید.
• رهگیری بسته از طریق بارکد
/api/OM/v3/Tracking/BriefTracking/{trackingInput}
با استفاده از این متد API ای تیپاکس، می‌توانید با ارسال درخواست GET همراه با پارامتر trackingInput، که همان بارکد بسته است، اطلاعات مربوط به بسته و وضعیت فعلی آن را در پیلود پاسخ، با عنوان contractStatusName دریافت کنید.
وضعیت‌های (State) مختلفی که در پاسخ به API مشاهده می‌کنید، به شرح زیر است:
| کد | وضعیت |
|---|---|
| 30 | در دست جمع‌آوری |
| 34 | ابطال شد |
| 38 | جمع‌آوری شد |
| 50 | تحویل به گیرنده |
| 51 | عودت شد |
| 52 | برگشت خورد |
| 58 | در حال پردازش |
| 59 | ثبت اولیه |
• رهگیری بسته از طریق شماره قرارداد
/api/OM/v3/Tracking/ByContractCode/{contractCode}
با استفاده از این متد و ارسال درخواست GET همراه با پارامتر contractCode، شماره قرارداد بسته، می‌توانید اطلاعات مربوط به بسته را با جزئیات بیشتر و همچنین وضعیت فعلی آن دریافت کنید.
• رهگیری بسته از طریق شماره سفارش
/api/OM/v3/Tracking/{orderId}
با استفاده از این متد و ارسال درخواست GET همراه با پارامتر orderId، شماره سفارش بسته، می‌توانید اطلاعات مربوط به بسته و وضعیت فعلی آن دریافت کنید.
• رهگیری چندین بسته به صورت همزمان از طریق بارکد
/api/OM/v3/Tracking/ByTrackingCode
با استفاده از این متد و ارسال درخواست به‌صورت POST همراه با پیلود شامل بارکدهای مورد نظر، می‌توانید چندین بسته را به صورت همزمان رهگیری کنید.
• رهگیری بسته از طریق کد رهگیری اختصاصی (traceCode)
/api/OM/v3/Tracking/{traceCode}
با استفاده از این متد و ارسال درخواست POST همراه با پارامتر traceCode، که کد سفارش اختصاصی تعریف شده برای بسته است، می‌توانید بسته مورد نظر را رهگیری کنید.
ارتباط با پشتیبانی ای تیپاکس
در هنگام بروز خطا، علاوه برکد وضعیت HTTP یا همان HTTP Status Code می‌توانید از معادل فارسی خطاهای API استفاده کنید.
معادل‌های فارسی این خطاها، به شما کمک می‌کنند تا به‌راحتی مشکل را شناسایی کرده و با پشتیبان فنی در میان بگذارید.
بهره‌گیری از API ای تیپاکس می‌تواند به طرز چشمگیری فرآِیندهای لجستیکی شما را بهینه‌سازی کند. تیپاکس با ارائه مجموعه‌ای کامل از خدمات پستی و لجستیکی، این امکان را به شما می‌دهد تا عملیات ارسال، رهگیری و مدیریت اطلاعات مشتریان را به شکلی ساده و کارآمد انجام دهید و با ترکیبی از کارایی و دقت، کسب‌وکارتان را به سوی موفقیت‌های بزرگتر هدایت کنید.
