چگونه از API ای تیپاکس استفاده کنیم؟
استفاده از API یکی از اساسی‌ترین عوامل موفقیت در دنیای تجارت الکترونیک است. طبق گزارش MuleSoft نزدیک به 90% کسب‌وکارهایی که از API استفاده می‌کنند، رشد درآمد قابل توجهی را تجربه کرده‌اند که مستقیما به استقرار API برای این شرکت‌ها نسبت داده می‌شود.
API به توسعه‌دهندگان این اجازه را می‌دهد تا با استفاده از زیرساخت‌های موجود، برنامه‌های جدیدی را ایجاد کنند، API علاوه بر صرفه‌جویی در زمان و منابع برای توسعه‌دهندگان، به کسب‌وکارها هم این امکان را می‌دهد تا با گسترش دامنه‌ی دسترسی‌های خود، به بازارهای جدیدی دست پیدا کنند.
با استفاده از API ای‌تیپاکس میتوانید فرآیند ارسال بسته‌های پستی را خودکار، بدون اشتباه و به‌سرعت انجام دهید.در این مقاله، به شما آموزش می‌دهیم که چگونه از این API استفاده کنید.
آنچه در این مقاله می‌خوانید
ابتدا به یک حساب کاربری در پلتفرم ای‌تیپاکس (etipaxco.com) نیاز دارید. برای یادگیری از نحوه ایجاد حساب، میتوانید به آموزش ETipax مراجعه کنید. پس از ایجاد حساب، با مراجعه به پروفایل خود میتوانید کلید اختصاصی API را دریافت کنید.
برای دسترسی به مستندات Swagger، ابتدا باید به آدرس زیر مراجعه کنید.
API ای تیپاکس > حساب کاربری (Account)
در قسمت Account، همانند تصویر زیر، با ارسال پیلود (Payload) درخواستی، با توجه به توضیحات در مستندات (documents)، توکن دسترسی ثابت (Access Token) و توکن به‌روزرسانی (Refresh Token) را که در ادامه به آن نیاز پیدا می‌کنیم، به‌دست آورید.
با ارسال درخواست (Request) به همراه پیلود درخواستی به مسیری که در تصویر زیر مشاهده می کنید، میتوانید توکن به‌روزرسانی خود را هم دریافت کنید.
توجه داشته باشید که این توکن، هر شش ماه یکبار منقضی خواهد شد.
API ای تیپاکس > مشتری حقیقی (ActualCustomer)
در قسمت ActualCustomer، با ارسال درخواست PUT و پیلود درخواستی، میتوانید مشتریانی که در گذشته ثبت کرده‌اید را ویرایش کنید. در قسمت پاسخ هم با تایپ Boolean و پاسخ (True/Fales) میتوانید از انجام شدن عملیات مطلع شوید.
API ای تیپاکس > آدرس‌ها (Addresees)
در قسمت Addresses، میتوانید با ارسال پیلود درخواستی و ثبت آدرس‌های ثابت خود، در آینده به جای وارد کردن آدرس کامل، از آیدی (ID) آدرس در پیلود برای ثبت سفارش استفاده کنید.
API ای تیپاکس > شهرها (Cities)
در قسمت Cities (شهرها)، با ارسال درخواست GET، میتوانید لیست و آیدی شهرهایی که تیپاکس در آن‌ها فعالیت دارد را دریافت کرده و برای ثبت سفارش از آن‌ها استفاده کنید.
API ای تیپاکس > مشتریان (Customers)
در قسمت Customers، علاوه بر مدیریت مشتریان (گیرنده یا فرستنده)، با ثبت اطلاعات آن‌ها، میتوانید از آیدی‌شان به جای اطلاعات کامل آن‌ها استفاده کنید.
همچنین در همین قسمت میتوانید استعلام موجودی کیف پول خود را دریافت کنید.
API ای تیپاکس > مالی (Financial )
در قسمت Financial، میتوانید اطلاعات مالی و تاریخچه تراکنش‌ها را با ارسال درخواستGET، بدون نیاز به پیلود مشاهده کنید.
API ای تیپاکس > سفارش‌ها (Orders)
در قسمت Orders، میتوانید با متدهای مختلف سفارش خود را به ثبت برسانید که به بررسی هرکدام از این متدها می‌پردازیم:
در اولین متد، باید پیلود درخواستی در مستندات را با استفاده از متد POST به آدرسی که در تصویر زیر مشاهده می‌کنید، ارسال کنید. توضیحات مربوط به کارایی هر کدام از آیتم‌ها در مستندات موجود است.
با استفاده از متدهای زیر میتوانید آیدی‌های مورد نیاز را به دست آورید:
| متد (Method) | آیدی (ID) |
|---|---|
| packagingPrices | PackagingId |
| packContentRate | PackagContentId |
| parcelType | ParcelTypeId |
| parcelBooks | ParcelBookId |
پس از به دست آوردن آیدی‌ها، پیلودی مشابه تصویر زیر خواهید داشت که با ارسال آن میتوانید بارکد سفارش را دریافت و پرینت کنید.
در زیر نمونه یک پیلود واقعی قرار داده شده است که میتوانید از آن استفاده کنید.
{
"packages": [
{
"cod": 0,
"origin": {
"cityId": 1262,
"fullAddress": "تهران، خیابان مطهری، نرسیده به سهروردی، پلاک ۱۰۰",
"floor": "0",
"unit": "100",
"postalCode": "158754575",
"latitude": "35.724332",
"longitude": "51.434650",
"no": "127",
"description": "",
"beneficiary": {
"phone": "09121111111",
"fullName": "تست ",
"mobile": "09121111111"
}
},
"destination": {
"cityId": 1870,
"fullAddress": "بل احمد نیا",
"floor": "2",
"unit": "12",
"postalCode": "158754575",
"latitude": "35.724332",
"longitude": "51.434650",
"no": "10",
"description": "",
"beneficiary": {
"phone": "09121111111",
"fullName": "محمد",
"mobile": "09121111111"
}
},
"weight": 1,
"packageValue": 10000,
"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
}
]
}
همانطور که در تصویر شماره 9 مشاهده کردید، برای ثبت سفارش با متدهای دیگر میتوانید با اعمال تغییرات کمی روی پیلود بالا، از آن استفاده کنید.
به عنوان مثال، میتوانید از متد زیر برای ثبت سفارش گیرنده‌ای که آدرس آن را از پیش تعریف کرده‌اید (نحوه انجام آن در بالا ذکر شده است)، استفاده کنید:
همانطور که در تصویر بالا مشخص است، در هر متد ساختار ارسال پیلود و پاسخی که دریافت می‌کنید نمایش داده می‌شود. از این مثال، میتوانید جهت پیاده سازی استفاده کنید.
API ای تیپاکس > بسته‌ها (Parcels)
در قسمت Parcels میتوانید تمام امور مربوط به مرسوله‌های خود را انجام دهید.
همچنین در این قسمت میتوانید با ارسال درخواست PUT، نسبت به ابطال بارکد مرسوله‌هایی که به اشتباه به ثبت رسیده اند اقدام کنید.
ابطال مرسوله‌ها تا زمانی که در حالت (State) جمع‌آوری قرار دارند، امکان‌پذیر است.
API ای تیپاکس > قیمت گذاری (Pricing)
در قسمت Pricing قبل از ثبت سفارش میتوانید با ارسال درخواست POST به شیوه‌های مختلف، هزینه خدمات سفارش را استعلام بگیرید.
رهگیری بسته‌ها (Tracking)
در قسمت Tracking میتوانید برای پیگیری وضعیت بسته‌ها و سفارش‌های خود استفاده کنید.
در این قسمت TraceCode، کد اختصاصی‌ای است که در هنگام ثبت سفارش به صورت یکتا (Unique) میتوانید ثبت کنید.
وضعیت‌های (State) مختلفی که در پاسخ به API مشاهده می‌کنید، به شرح زیر است:
| وضعیت (State) |
|---|
| 30 در درست جمع‌آوری |
| 34 ابطال شد |
| 38 جمع‌آوری شد |
| 50 تحویل به گیرنده |
| 51 عودت شد |
| 52 برگشت خورد |
| 58 در حال پردازش |
| 59 ثبت اولیه |
ارتباط با پشتیبانی ای تیپاکس
در هنگام بروز خطا، علاوه برکد وضعیت HTTP یا همان HTTP Status Code میتوانید از معادل فارسی خطاهای API استفاده کنید.
معادل‌های فارسی این خطاها، به شما کمک می‌کنند تا به‌راحتی مشکل را شناسایی کرده و با پشتیبان فنی در میان بگذارید.
بهره‌گیری از API ای تیپاکس می‌تواند به طرز چشمگیری فرآِیندهای لجستیکی شما را بهینه‌سازی کند. تیپاکس با ارائه مجموعه‌ای کامل از خدمات پستی و لجستیکی، این امکان را به شما می‌دهد تا عملیات ارسال، رهگیری و مدیریت اطلاعات مشتریان را به شکلی ساده و کارآمد انجام دهید و با ترکیبی از کارایی و دقت، کسب‌وکارتان را به سوی موفقیت‌های بزرگتر هدایت کنید.
