مستندات فنی و آموزش کار با API مسیریابی چندگانه (متد دریافت وضعیت)
مدیریت لجستیک و توزیع کالا امروزه بدون ابزارهای هوشمند امکانپذیر نیست. یکی از چالشهای اصلی برنامهنویسان، آگاهی از وضعیت پردازش درخواستهای ارسالی به سرور است. در این مقاله، به بررسی دقیق API مسیریابی چندگانه متد دریافت وضعیت میپردازیم. این متد به شما کمک میکند تا خروجی نهایی برنامهریزی سفر را با دقت بالا دریافت کنید. 📍
بخش اول: معرفی متد دریافت وضعیت در API مسیریابی
پس از ارسال درخواست به وبسرویس برنامهریزی سفر، سیستم شروع به محاسبات پیچیده برای یافتن بهترین مسیر میکند. از آنجایی که این فرآیند ممکن است کمی زمانبر باشد، شما به یک راهکار برای پیگیری وضعیت نیاز دارید. با استفاده از این متد و داشتن job_id اختصاصی، میتوانید در هر لحظه از وضعیت پردازش دادههای خود مطلع شوید.
ساختار درخواست (Request Structure)
برای دریافت جزئیات مسیر، باید از متد GET استفاده کنید. آدرس نهایی درخواست شما به صورت زیر خواهد بود:
https://planner.monhani.ir/api/v1/plan/{{job_id}}
در این ساختار، پارامتر job_id همان شناسهای است که در مرحله قبل (ارسال درخواست اولیه) دریافت کردهاید. 🔍
مزیتهای استفاده از API مسیریابی چندگانه
بهرهگیری از این سرویس در پروژههای نرمافزاری، مزایای متعددی را برای کسبوکارها به همراه دارد. در ادامه به مهمترین آنها اشاره میکنیم:
- ✅ کاهش هزینههای سوخت: با بهینهسازی مسیرها، مسافت طی شده به حداقل میرسد.
- ✅ مدیریت زمان: زمان رسیدن به هر مقصد (Arrival Time) به دقت محاسبه میشود.
- ✅ پاسخگویی سریع: اطلاع لحظهای از وضعیت پردازش درخواستها.
- ✅ دقت بالا: استفاده از الگوریتمهای پیشرفته برای نقشههای داخلی ایران. 🛣️
- ✅ قابلیت اطمینان: تشخیص مسیرهای غیرمجاز یا ناممکن (Infeasible).
کاربردهای اصلی وبسرویس مسیریابی
این API صرفاً یک ابزار نمایش مسیر نیست؛ بلکه کاربردهای گستردهای در صنایع مختلف دارد:
- 📦 لجستیک و توزیع کالا: چیدمان هوشمند توقفگاهها برای ناوگان پخش مویرگی.
- 🚕 تاکسیهای اینترنتی: مدیریت سفرهای چندمقاصده با اولویتبندی زمانی.
- 🚑 خدمات اضطراری: یافتن سریعترین مسیر برای خودروهای امدادی در کلانشهرها.
- 🚚 مدیریت ناوگان: نظارت بر عملکرد رانندگان بر اساس مسافت طی شده (Cumulative distance).
راهنمای گامبهگام ثبتنام و دریافت کلید دسترسی
برای شروع استفاده از این سرویس و تست متدها، ابتدا باید در پنل توسعهدهندگان عضو شوید. فرآیند ثبتنام بسیار ساده است:
- ابتدا به آدرس p.api.ir مراجعه نمایید. 🌐
- اطلاعات کاربری خود را وارد کرده و حساب خود را تایید کنید.
- پس از ورود، کلید دسترسی (Access Token) اختصاصی خود را دریافت کنید.
- توکن دریافتی را در هدر درخواستهای خود (Authorization Bearer) قرار دهید.
تحلیل دقیق پاسخ سیستم (Response Object)
زمانی که درخواستی را به API مسیریابی چندگانه ارسال میکنید، سیستم یک شیء (Object) شامل سه بخش اصلی بازمیگرداند:
۱. وضعیت درخواست (Status)
این پارامتر وضعیت فعلی پردازش را نشان میدهد:
- resolved: درخواست با موفقیت پردازش شده و نتیجه آماده است.
- pending: سیستم هنوز در حال محاسبه بهترین مسیر است. ⏳
- rejected: درخواست رد شده است (مثلاً نقاط خارج از ایران هستند یا جادهای یافت نشد).
۲. شیء نتیجه (Result Object)
در این بخش، جزئیات مسیر شامل اولویتها، زمان رسیدن و مسافت تجمعی قرار دارد. پارامتر مهم feasible نشان میدهد که آیا تمام محدودیتهای مدنظر شما (مثل پنجره زمانی) رعایت شده است یا خیر.
۳. مدیریت خطاها (Error Types)
در صورت بروز مشکل، کدهای وضعیت زیر بازگردانده میشوند:
- ۴۰۱ (Authentication Error): توکن شما منقضی شده یا نامعتبر است. 🔑
- ۴۲۹ (Rate Limited): تعداد درخواستهای شما بیش از حد مجاز (یک درخواست در ثانیه) است.
- ۴۰۰ (Route Planner Error): عدم توانایی در یافتن مسیر بین نقاط مشخص شده.
مشخصات فنی هدرها (Headers)
برای برقراری ارتباط صحیح با سرور، حتماً هدرهای زیر را در درخواست خود تنظیم کنید:
- Authorization:
Bearer {{access_token}} - Content-Type:
application/json
کلام آخر
استفاده از متد دریافت وضعیت در API مسیریابی چندگانه، گامی حیاتی برای خودکارسازی سیستمهای حملونقل است. این ابزار با ارائه دادههای دقیق از مسافت، زمان و اولویتبندی مقاصد، بهرهوری ناوگان شما را به طرز چشمگیری افزایش میدهد. با تکیه بر این تکنولوژی، خطای انسانی در برنامهریزی سفر به حداقل میرسد. 🚀
آیا آمادهاید تا سیستم توزیع خود را هوشمند کنید؟ همین حالا در پنل ما ثبتنام کنید و اولین تست خود را انجام دهید! اگر سوالی در مورد پیادهسازی متدها دارید، در بخش نظرات با ما در میان بگذارید.