Webhook & Luồng callback

Đối tác cần cung cấp một webhook URL để nhận các cập nhật trạng thái từ Ahamove. Ahamove sẽ callback đến URL này mỗi lần trạng thái của đơn hàng thay đổi.

Cách để test callback và Webhook

1. Thiết lập webhook url để nhận thông tin order_id & status, sau đó gửi URL để Ahamove cài đặt vào hệ thống
2. Tải về ứng dụng tài xế trên môi truờng test AhaDriver STG trên thiết bị có hệ điều hành Android
3. Đăng ký tài khoản, sau đó liên hệ với Ahamove để được xác thực tài khoản
4. Đăng nhập và bật trực tuyến
5. Sử dụng API Create Order để tạo đơn hàng trong vòng bán kính 1km kể từ địa chỉ của tài xế
6. App của tài xế sẽ nhận một thông báo, nhấn vào thông báo để chấp nhận đơn hàng
7. Hệ thống Ahamove sẽ bắn trạng thái ACCEPTED đến webhook URL
8. Cập nhật các trạng thái đơn hàng trên app tài xế, hệ thống Ahamove sẽ bắn những trạng thái tương ứng đến webhook URL

Phương pháp Authentication

Ahamove hỗ trợ 3 loại authorization header (API-KEY, BEARER-TOKEN, BASIC-AUTH)

API Key

Đối tác đặt API key vào Authorization header

 Header: { apikey: "auth_token" }

Ex: { "apikey": "KJhb4seu82dHe3hkDgyU7mQoh5AB1o" }

Bearer Token

Đối tác gửi token vào Authorization header khi tạo requests

 Header: { Authorization: "Bearer + auth_token" }

Ex: { "Authorization": "Bearer KJhb4seu82dHe3hkDgyU7mQoh5AB1o"}

Basic Auth

Với phương thức này, Đối tác để một username: password vài trong request header. Username and password được encoded với Base64

 Header: { Authorization: "Basic {b64.StdEncoding.EncodeToString([]byte({username}:{password}))}" }

Ex: { "Authorization": "Basic KJhb4seu82dHe3hkDgyU7mQoh5AB1o"}

Luồng Callback

Mẫu Callback

{
  "_id": "22VMV54W",
  "accept_time": 0,
  "board_time": 0,
  "cancel_by_user": false,
  "cancel_comment": "",
  "cancel_image_url": "",
  "cancel_time": 0,
  "city_id": "SGN",
  "complete_time": 0,
  "create_time": 1665742305.9305305,
  "currency": "VND",
  "order_time": 1665742305.9305305,
  "partner": "",
  "path": [
    {
      "address": "725 Hẻm số 7 Thành Thái, Phường 14, Quận 10, Hồ Chí Minh, Việt Nam",
      "cod": 0,
      "por_info": "",
      "short_address": "Quận 10",
      "formatted_address": "",
      "mobile": "09xxxxxxxx",
      "status": "",
      "complete_lat": 0,
      "complete_lng": 0,
      "fail_lat": 0,
      "fail_lng": 0,
      "complete_time": 0,
      "fail_time": 0,
      "return_time": 0,
      "pod_info": "",
      "fail_comment": "",
      "name": "Anh",
      "remarks": "call me"
    },
    {
      "address": "Chợ Bến Thành, Bến Thành, Quận 01, Hồ Chí Minh, Việt Nam",
      "cod": 0,
      "por_info": "",
      "short_address": null,
      "formatted_address": "",
      "mobile": "09xxxxxxxx",
      "status": "",
      "complete_lat": 0,
      "complete_lng": 0,
      "fail_lat": 0,
      "fail_lng": 0,
      "complete_time": 0,
      "fail_time": 0,
      "return_time": 0,
      "pod_info": "",
      "fail_comment": "",
      "name": "Bao"
    }
  ],
  "payment_method": "CASH",
  "pickup_time": 0,
  "service_id": "SGN-BIKE",
  "status": "ASSIGNING",
  "sub_status": "",
  "supplier_id": "",
  "supplier_name": "",
  "surcharge": 1.1,
  "user_id": "",
  "user_name": "",
  "total_pay": 33000,
  "promo_code": "",
  "stoppoint_price": 0,
  "special_request_price": 1000,
  "vat": 0,
  "distance_price": 32000,
  "voucher_discount": 0,
  "subtotal_price": 33000,
  "total_price": 33000,
  "surge_rate": 1.1,
  "api_key": "<API_KEY_STG>",
  "shared_link": "https://cloudstg.ahamove.com/share-order/22VMV54W/84911434061",
  "insurance_portal_url": "https://claim-dev.globalcare.vn/claim/ahamove/intransit?platform=app&code=22VMV54W&phone=84xxxxxxxxx",
  "app": "Ahamove",
  "store_id": 0,
  "distance": 4.68
}

Callback _id cho đơn hàng 1 điểm lấy – N điểm giao

Đối với đơn hàng có một điểm lấy hàng và nhiều điểm giao (đơn 1-N), field _id trong dữ liệu callback sẽ có sự khác biệt tùy theo điểm nào đang được cập nhật.

• Callback đơn hàng (ví dụ: IDLE, ASSIGNING, ACCEPTED, COMPLETED, CANCELLED): _id là mã đơn hàng gốc, không có suffix.
• Callback điểm giao (khi tài xế cập nhật trạng thái của một điểm giao cụ thể, trạng thái đơn hàng là IN PROCESS): _id sẽ có thêm suffix số để xác định điểm giao nào vừa kích hoạt sự kiện.

Định dạng:

{mã_đơn_hàng}-{index_điểm_giao}

Trong đó index_điểm_giao bắt đầu từ 1 cho điểm giao đầu tiên, 2 cho điểm thứ hai, và tiếp tục theo thứ tự.

Ví dụ:

Với đơn hàng có mã 26ABCDEF gồm 3 điểm giao:

Hành động của tài xế	_id trong callback
Cập nhật trạng thái điểm giao 1	26ABCDEF-1
Cập nhật trạng thái điểm giao 2	26ABCDEF-2
Cập nhật trạng thái điểm giao 3	26ABCDEF-3