Luồng đặt chuyến
Từ địa chỉ đến báo giá, tạo chuyến, các trạng thái và cách chống tạo trùng.
| Bước | Chiều | Gọi gì | Kết quả |
|---|---|---|---|
| 1 | Bạn → GOCheap | GET /places/search (tuỳ chọn) | place_id của điểm đón, điểm đến |
| 2 | Bạn → GOCheap | POST /quotes | quote_id, price, giữ 10 phút |
| 3 | Bạn → GOCheap | POST /bookings + Idempotency-Key | booking_id, status: searching |
| 4 | GOCheap → tài xế | Phát chuyến cho tài xế gần nhất | Tài xế nhận chuyến |
| 5 | GOCheap → bạn | Webhook booking.driver_assigned | Thông tin tài xế |
| 6 | GOCheap → bạn | Webhook booking.started, booking.completed | Đón khách, hoàn thành, giá cuối |
1. Địa chỉ
Điểm đón và điểm đến gửi theo một trong hai cách:
{ "place_id": "..." }lấy từGET /places/search?q=....{ "lat": 21.0285, "lng": 105.8542, "address": "Hồ Hoàn Kiếm, Hà Nội" }nếu hệ thống của bạn đã có toạ độ.
Địa chỉ nên ghi rõ phường/xã và tỉnh/thành. Không xác định được địa chỉ thì nhận 422 address_not_found.
2. Báo giá
POST /quotes tính giá theo bảng giá GOCheap của dịch vụ, khu vực, quãng đường và khung giờ đón. Bỏ trống pick_up_time nghĩa là đón sau 20 phút.
- Báo giá giữ nguyên trong 10 phút (
expires_at). - Tuyến hoặc khu vực chưa có trong bảng giá thì nhận
422 area_not_supported.
3. Tạo chuyến
POST /bookings với quote_id còn hiệu lực. Giá chốt theo báo giá, không tính lại.
Chống tạo trùng, nên dùng cả hai:
| Cơ chế | Hành vi |
|---|---|
Header Idempotency-Key | Gửi lại cùng key trong 24 giờ nhận lại đúng chuyến đã tạo (header Idempotent-Replayed: true), không tạo chuyến mới. Dùng khi request bị timeout và bạn không chắc chuyến đã tạo chưa. |
partner_reference_id | Mã đơn bên bạn, duy nhất trong tài khoản. Dùng lại mã đã có nhận 409 duplicate_reference. |
Mỗi quote_id chỉ tạo được một chuyến; dùng lại nhận 410 quote_expired.
4. Trạng thái chuyến
status | Ý nghĩa | Webhook |
|---|---|---|
searching | Đang tìm tài xế | booking.created |
driver_assigned | Tài xế đã nhận chuyến, có thông tin driver | booking.driver_assigned |
driver_arriving | Tài xế đang đến điểm đón | booking.driver_arriving |
in_progress | Đã đón khách, đang di chuyển | booking.started |
completed | Hoàn thành; final_price là giá cuối cùng (gồm phụ trội nếu có) | booking.completed |
cancelled | Đã huỷ; xem cancellation.cancelled_by | booking.cancelled |
Tài xế huỷ sau khi nhận: chuyến quay về searching, hệ thống tìm tài xế khác và bạn nhận booking.driver_unassigned.
cancellation.cancelled_by: client (bạn huỷ qua API), driver, gocheap (tổng đài GOCheap), system.
5. Huỷ chuyến
POST /bookings/{booking_id}/cancel khi chuyến đang searching, driver_assigned hoặc driver_arriving. Chuyến đã đón khách hoặc đã kết thúc nhận 422 cannot_cancel.
6. Tra cứu
GET /bookings/{booking_id}: một chuyến.GET /bookings?partner_reference_id=HTL-20261112-0042: tra theo mã đơn của bạn.GET /bookings?status=completed&created_from=...&created_to=...: đối soát theo kỳ.
Nếu buộc phải gọi định kỳ thay vì dùng webhook, tối đa 1 lần mỗi 15 giây cho mỗi chuyến.