رفتن به محتوا
کوریِر

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} هم دیده می‌شود.

  1. pending
  2. searching
  3. courier_assigned
  4. picking_up
  5. in_transit
  6. delivered
  • 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کارت شما از کار افتاد

گرفتن کلید

  1. ۱

    درخواست حساب

    حساب فروشگاه و اولین کاربرش را برایتان می‌سازیم.

  2. ۲

    ساخت کلید آزمایشی

    در پنل، بخش Integration. کلیدهایی که با ck_test_ شروع می‌شوند فقط ارسال آزمایشی رزرو می‌کنند.

  3. ۳

    بسازید و تست کنید

    با کارت‌های آزمایشی در محیط sandbox رزرو کنید و رسیدن وبهوک‌ها را ببینید.

  4. ۴

    عملیاتی شوید

    کلید ck_live_ را جایگزین کنید. هیچ چیز دیگری در کدتان تغییر نمی‌کند.

با شروع سریع آغاز کنید

از کلید آزمایشی تا یک ارسال رزروشده در چند دقیقه، با curl.