Hướng dẫn
Bắt đầu nhanh
Gọi API đầu tiên trên môi trường sandbox.
Môi trường
| Môi trường | Base URL | Key |
|---|---|---|
| Sandbox | https://api-stag.gocheap.vn/open-api/v1 | gc_test_... |
| Production | Cấp khi nghiệm thu | gc_live_... |
Sandbox dùng dữ liệu thử nghiệm, chuyến không phát cho tài xế thật. Key sandbox không dùng được trên production và ngược lại.
1. Nhận API key
Liên hệ GOCheap để được tạo tài khoản đối tác và cấp API key sandbox. Key chỉ hiện một lần lúc cấp; hãy lưu ngay vào nơi an toàn trên máy chủ của bạn.
2. Gọi thử
curl https://api-stag.gocheap.vn/open-api/v1/services \
-H "Authorization: ApiKey gc_test_your_api_key"{
"success": true,
"data": [
{ "id": "thue-tai-xe", "name": "Lái hộ ô tô", "description": "Tài xế lái xe ô tô của khách" }
]
}Nhận 401 invalid_api_key thì kiểm tra lại key, tiền tố ApiKey và môi trường.
3. Báo giá
curl https://api-stag.gocheap.vn/open-api/v1/quotes \
-H "Authorization: ApiKey gc_test_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"service": "thue-tai-xe",
"pick_up": { "lat": 21.0285, "lng": 105.8542, "address": "Hồ Hoàn Kiếm, Hà Nội" },
"destination": { "lat": 21.0368, "lng": 105.8347, "address": "Lăng Chủ tịch Hồ Chí Minh, Ba Đình" }
}'Response có quote_id và price (đồng). Báo giá giữ nguyên trong 10 phút.
4. Tạo chuyến
curl https://api-stag.gocheap.vn/open-api/v1/bookings \
-H "Authorization: ApiKey gc_test_your_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2a8e-3b7d-4c55-9a0e-2d4b7f1e9c33" \
-d '{
"quote_id": "qt_a7ed7ee95bacc5c9",
"partner_reference_id": "HTL-20261112-0042",
"customer": { "name": "Nguyễn Văn An", "phone": "0912345678" },
"vehicle": { "model": "Toyota Vios", "license_plate": "30A-123.45" },
"note": "Khách đợi ở sảnh A"
}'Response trả về booking_id (ví dụ LX261113HUU) và status: "searching". Từ đây hãy đăng ký webhook để nhận trạng thái thay vì gọi API liên tục.
Tiếp theo
- Xác thực: cách giữ key an toàn, giới hạn request.
- Luồng đặt chuyến: các trạng thái và chống tạo trùng.
- API Reference: toàn bộ endpoint, trường dữ liệu và mã lỗi.