API همکاران
ارسال را درون سیستم خودتان بسازید
یک REST API کوچک روی HTTPS با ورودی و خروجی JSON. برای یک مسیر قیمت بگیرید، رزروش کنید و وقتی پیک تحویل میگیرد و میرساند، با وبهوک باخبر شوید.
# 1. What will it cost?curl -u $KEY:$SECRET https://api…/v1/quotes \ -d '{"pickup": {"latitude": 51.508, "longitude": -0.128}, "dropoff": {"latitude": 51.508, "longitude": -0.076}, "vehicle": "bicycle"}'# 2. Book it. Safe to retry: same key, same job.curl -u $KEY:$SECRET https://api…/v1/jobs \ -H "Idempotency-Key: order-1042" \ -d '{"quote_id": "…", "pickup": {…}, "dropoff": {…}}'→ 201 {"reference": "JOB-7F3K2Q", "status": "searching", "tracking_url": "https://track…"}با چه چیزهایی میسازید
قیمت (Quote)
قیمت قطعی برای یک مسیر و یک وسیله، با ریز اقلام، معتبر تا زمان انقضا.
POST /v1/quotesسفارش (Job)
رزرو بر اساس یک قیمت. با Idempotency-Key تکرار درخواست همان سفارش را برمیگرداند، نه سفارش دوم.
POST /v1/jobsردیابی
وضعیت و مقصدهای سفارش، موقعیت زندهٔ پیک، و لینک ردیابی برای مشتری.
GET /v1/jobs/{id}وبهوک
امضاشده با HMAC-SHA256 و ده بار تکرار در حدود یک ساعت و نیم، تا قطعی کوتاه چیزی را از دست ندهد.
POST /v1/webhooksپرداخت
کارت ثبتشده؛ نگهداشت هنگام رزرو و برداشت هنگام تحویل. همهٔ برداشتها از طریق API خواندنی است.
GET /v1/chargesمکان و مسیر
جستجوی نشانی، تبدیل مختصات به نشانی و مسیر بین دو نقطه، برای صفحههای رزرو خودتان.
GET /v1/places
چرخهٔ عمر یک سفارش
هر تغییر وضعیت یک وبهوک است، و همان وضعیت در GET /v1/jobs/{id} هم دیده میشود.
pendingsearchingcourier_assignedpicking_upin_transitdelivered
in_transitreturningreturnedتحویل ممکن نشد و به شما برگردانده شد
cancelledپیش از تحویل گرفتن لغو شد — هزینهای ندارد
failedتا مهلت تعیینشده هیچ پیکی قبولش نکرد
رویدادهای وبهوک
هر ارسال نام رویداد، یک شناسهٔ ارسال برای حذف تکراریها، و امضایی روی زمان و بدنه دارد.
# هدرها
Courier-Event: job.delivered
Courier-Delivery: 7f3c9e2a-…
Courier-Signature: t=1760090000,v1=5f2c…
job.bookedسفارش پذیرفته شدjob.courier_assignedپیکی قبولش کردjob.picked_upاز شما تحویل گرفته شدjob.deliveredبا مدرک تحویل داده شدjob.returnedبه شما برگردانده شدjob.cancelledلغو شدjob.failedپیکی بهموقع قبولش نکردjob.status_changedتغییر دستی توسط تیم عملیاتpayment_method.deadکارت شما از کار افتاد
گرفتن کلید
- ۱
درخواست حساب
حساب فروشگاه و اولین کاربرش را برایتان میسازیم.
- ۲
ساخت کلید آزمایشی
در پنل، بخش Integration. کلیدهایی که با ck_test_ شروع میشوند فقط ارسال آزمایشی رزرو میکنند.
- ۳
بسازید و تست کنید
با کارتهای آزمایشی در محیط sandbox رزرو کنید و رسیدن وبهوکها را ببینید.
- ۴
عملیاتی شوید
کلید ck_live_ را جایگزین کنید. هیچ چیز دیگری در کدتان تغییر نمیکند.
با شروع سریع آغاز کنید
از کلید آزمایشی تا یک ارسال رزروشده در چند دقیقه، با curl.