راهنمای اتصال سایت (API)

هر فروشگاه اینترنتی می‌تواند سفارش‌هایش را خودکار برای بسته‌بان بفرستد و کد رهگیری را خودکار پس بگیرد. برای سایت‌های وردپرس / ووکامرس افزونهٔ آماده هست؛ سایت‌های دیگر از API استفاده می‌کنند.

۱. دریافت کلید

پس از عقد قرارداد، برای هر سایت شما یک شناسهٔ سایت، یک کلید API (bbk_…) و یک رمز اطلاع‌رسانی (bbw_…) ساخته می‌شود. هر کلید فقط به سفارش‌های همان سایت دسترسی دارد و هر وقت بخواهید عوض یا باطل می‌شود.

۲. سایت‌های وردپرس / ووکامرس

افزونهٔ «Bastehban Connector» را دریافت و در وردپرس نصب و فعال کنید.
در ووکامرس ← بسته‌بان نشانی API، کلید و رمز اطلاع‌رسانی را بنویسید و «آزمایش اتصال» را بزنید.
نشانی اطلاع‌رسانی‌ای که افزونه نشان می‌دهد را به ما بدهید.

از این پس سفارش‌های «در حال انجام» خودکار فرستاده می‌شوند و کد رهگیری در صفحهٔ سفارش مشتری و ایمیل او نشان داده می‌شود.

۳. سایت‌های دیگر (API)

نشانی پایه:

http://basteban.com/api/bastehban/v1

همهٔ درخواست‌ها با سرآیند Authorization: Bearer bbk_…. مبالغ به ریال است.

درخواست	کار
`GET /ping`	آزمایش کلید
`POST /orders`	ثبت سفارش (`external_id` = شمارهٔ سفارش در سایت شما)
`GET /orders/{external_id}`	وضعیت، کد رهگیری و نشانی رهگیری
`PATCH /orders/{external_id}`	اصلاح گیرنده یا بسته تا پیش از ارسال
`POST /orders/{external_id}/cancel`	لغو تا پیش از ارسال
`POST /callback-test`	پیام آزمایشی به نشانی اطلاع‌رسانی شما

نمونهٔ ثبت سفارش:

curl -X POST http://basteban.com/api/bastehban/v1/orders \
  -H "Authorization: Bearer bbk_..." -H "Content-Type: application/json" \
  -d '{"external_id": "1052", "recipient": {"name": "…", "mobile": "0912…", "province": "اصفهان",
       "city": "اصفهان", "address": "…", "postal_code": "…"},
       "parcel": {"weight_g": 1200, "declared_value": 25000000, "cod_amount": 0}, "carrier": "tipax"}'

تکرار بی‌خطر: فرستادن دوبارهٔ همان external_id سفارش تازه نمی‌سازد (پاسخ ۲۰۰ با "duplicate": true).
خطاها: ۴۰۱ کلید نامعتبر، ۴۰۳ سایت غیرفعال، ۴۲۲ اطلاعات ناقص (با فهرست فیلدها)، ۴۰۹ سفارش دیگر قابل تغییر نیست، ۴۲۹ درخواست زیاد.

۴. دریافت کد رهگیری

بسته‌بان به نشانی اطلاع‌رسانی سایت شما POST می‌فرستد با سرآیندهای X-Bastehban-Event (shipment.tracking، shipment.status، order.rejected)، X-Bastehban-Delivery (شناسهٔ یکتا) و X-Bastehban-Signature به شکل t=زمان,v1=امضا. امضا HMAC-SHA256 رمز اطلاع‌رسانی روی "زمان.بدنه" است؛ آن را بررسی کنید، رویداد تکراری را نادیده بگیرید و با ۲xx پاسخ دهید. اگر سایت در دسترس نباشد، بسته‌بان چند بار دیگر تلاش می‌کند.

پشتیبانی فنی

تلفن 03136624657 و 09137423029، شنبه تا پنج‌شنبه، ۹ تا ۱۸.