Kết nối GHN bằng OTP
Kết nối tài khoản Giao Hàng Nhanh không cần dán token: xác minh bằng OTP gửi tới SĐT chủ shop
Ngoài cách dán Token API + ShopId, shop có thể kết nối GHN bằng OTP: GHN gửi mã OTP tới số điện thoại chủ shop; sau khi nhập đúng OTP, Hubport được GHN cho phép thao tác trên shop GHN đó (shop có sẵn, hoặc GHN tạo shop mới cho chủ shop). Shop không phải cung cấp token.
Workflow & Logic
- Tạo carrier với
api_type=19(GHN). Không cầntoken. - Gọi
POST /v1/shippingcarriers/:id/ghnotpvới SĐT chủ shop (SĐT đăng ký tài khoản GHN). GHN gửi OTP qua SMS. - Gọi
POST /v1/shippingcarriers/:id/ghnconnectvới SĐT + OTP:- Truyền
shop_id(ShopId GHN có sẵn của chủ shop) để gắn vào shop đó. - Không truyền
shop_idthì GHN tạo shop mới; có thể truyềnaddress,district_id,ward_code(mã địa chính của GHN) cho shop mới.
- Truyền
- Thành công: carrier chuyển sang
connect_mode=affiliate,shop_idđược ghi theo shop đã xác minh. Chi tiết carrier có thêmghn_connection.
Tiền COD
GHN đối soát COD trực tiếp với chủ shop. Hubport không giữ tiền COD.
1. Gửi OTP
POST /v1/shippingcarriers/:id/ghnotp
Quyền:
setting.sale
Request Body
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
company_id | int | Có | ID công ty |
phone | string | Có | SĐT chủ shop GHN |
Response (HTTP 200)
| Trường | Kiểu | Mô tả |
|---|---|---|
ttl | int | Thời gian hiệu lực của OTP (giây) do GHN trả về |
Giới hạn gửi OTP: mỗi carrier và mỗi SĐT 1 lần / 60 giây; mỗi công ty tối đa 20 lần / giờ.
2. Xác nhận OTP và kết nối
POST /v1/shippingcarriers/:id/ghnconnect
Quyền:
setting.sale
Request Body
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
company_id | int | Có | ID công ty |
phone | string | Có | SĐT đã nhận OTP |
otp | string | Có | Mã OTP (4–8 chữ số) |
shop_id | int | Không | ShopId GHN có sẵn để gắn. Bỏ trống để GHN tạo shop mới |
address | string | Không | Địa chỉ shop mới (khi không truyền shop_id) |
district_id | int | Không | Mã quận/huyện theo GHN của shop mới |
ward_code | string | Không | Mã phường/xã theo GHN của shop mới |
Response (HTTP 200)
Shipping Carrier Object sau khi kết nối, kèm ghn_connection:
{
"id": 12,
"api_type": 19,
"name": "GHN",
"status": 1,
"api_setting": {
"issandbox": 0,
"connect_mode": "affiliate",
"token": "",
"shop_id": 885123,
"...": "..."
},
"ghn_connection": {
"shop_id": 885123,
"client_id": 2509001,
"is_sandbox": 0,
"phone_masked": "090****000",
"mode": "with_shop",
"date_created": 1760000000
}
}mode: with_shop (gắn shop có sẵn) hoặc create (GHN tạo shop mới).
Error Codes
| Mã lỗi | Mô tả |
|---|---|
error_api_type_invalid | Carrier không phải GHN (HTTP 422) |
error_ghn_phone_invalid | SĐT không hợp lệ (HTTP 422) |
error_ghn_otp_too_frequent | Gửi OTP quá nhiều lần, thử lại sau (HTTP 422) |
error_ghn_otp_failed | GHN không gửi được OTP (HTTP 422) |
error_ghn_otp_invalid | Thiếu hoặc sai định dạng OTP (HTTP 422) |
error_ghn_otp_too_many_attempts | Nhập OTP sai quá nhiều lần (HTTP 422) |
error_ghn_shop_already_connected | Shop GHN này đã được kết nối (HTTP 422) |
error_ghn_affiliate_check_shop_before_retry | GHN lỗi khi tạo shop mới; kiểm tra trên GHN xem shop đã được tạo chưa trước khi thử lại (HTTP 422) |
error_ghn_connect_failed | Kết nối thất bại (HTTP 422) |
error_not_found | Carrier không tồn tại hoặc không thuộc công ty của bạn (HTTP 404) |
error_role_not_available | Không có quyền setting.sale (HTTP 403) |
Ngoài các mã trên, thông báo lỗi do GHN trả về cũng được chuyển tiếp trong mảng error.