Quy chuẩn chung — Partner API

Tài liệu tham chiếu chung cho toàn bộ Partner API: mã lỗi hệ thống và danh sách trạng thái.

Common Error

Các mã lỗi chung trả về trong trường error của response khi API thất bại.

Mã lỗi	Mô tả
`UNKNOWN_ERROR`	Lỗi không xác định — hệ thống gặp tình trạng ngoài dự kiến.
`NOT_FOUND`	Không tìm thấy tài nguyên yêu cầu.
`API_FAILED`	Gọi API nội bộ hoặc API bên thứ ba thất bại.
`MISSING_AUTHORITY`	Không có quyền thực hiện thao tác này.
`ERROR_START_DATE_AFTER_END_DATE`	Ngày bắt đầu lớn hơn ngày kết thúc trong bộ lọc thời gian.
`INSERT_FAILED`	Thêm mới dữ liệu vào hệ thống thất bại.
`RECORD_NOT_FOUND`	Không tìm thấy bản ghi trong cơ sở dữ liệu.
`UPDATE_FAILED`	Cập nhật dữ liệu thất bại.
`DELETE_FAILED`	Xoá dữ liệu thất bại.

Cấu trúc response lỗi điển hình:

{
  "statusCode": 400,
  "error": "RECORD_NOT_FOUND",
  "message": "Record not found",
  "data": null
}

Danh sách các giá trị hợp lệ của trường paymentStatus cho đơn hàng.

Giá trị	Mô tả
`New`	Đơn hàng mới tạo, chưa thực hiện thanh toán.
`Processing`	Đang xử lý thanh toán (cổng thanh toán đang phản hồi).
`Pending`	Đang chờ xác nhận thanh toán từ đối tác / hệ thống.
`Success`	Thanh toán thành công. Đơn hàng đã được xác nhận.
`Failed`	Thanh toán thất bại. Cần tạo yêu cầu mới nếu muốn thử lại.
`Canceled`	Đơn hàng đã bị hủy, không thể xử lý thêm.

Bảng mã số (errorCode) dùng cho các API Order đối tác. Trường errorCode được trả về cùng với error trong response khi xảy ra lỗi.

errorCode	Mã lỗi (error)	Mô tả
`00`	—	Thành công.
`01`	`UNAUTHORIZED`	Xác thực thất bại – clientId hoặc apiKey không hợp lệ.
`02`	`INVALID_DATA` / `REQUIRED_FIELD_MISSING` / `INVALID_AMOUNT` / `INVALID_BATCH_PAYLOAD`	Thiếu hoặc sai tham số đầu vào.
`03`	`ORDER_NOT_FOUND`	Không tìm thấy đơn hàng.
`04`	`ALREADY_PAID`	Đơn hàng đã thanh toán trước đó (idempotent).
`05`	`AMOUNT_MISMATCH`	Số tiền không khớp với đơn hàng.
`06`	`INVALID_ORDER`	Đơn hàng không hợp lệ để gạch nợ (đã huỷ, hết hạn, ...).
`99`	`SYSTEM_ERROR` / `INTERNAL_ERROR` / `UNKNOWN_ERROR`	Lỗi hệ thống hoặc exception khi xử lý.

Bảng mã lỗi trả về trong trường error khi sử dụng các API thuộc module EAgentTraffic (Đối tác tra cứu thông tin giao thông).

Mã lỗi (error)	Mô tả
`AGENT_QUOTA_EXCEEDED`	Đã vượt quá hạn mức (quota) của đối tác trong chu kỳ hiện tại.
`INCORRECT_PASSWORD`	Mật khẩu hoặc mã Passcode/PIN của tài khoản đối tác không chính xác.
`INCORRECT_OTP`	Mã OTP xác thực không chính xác hoặc đã hết thời gian hiệu lực.
`INVALID_USERNAME`	Tài khoản đối tác (số CCCD/CMND) không hợp lệ hoặc không tồn tại trong hệ thống.
`AGENTETRAFFIC_UNAUTHORIZED`	Không có quyền truy cập, xác thực thiết bị thất bại hoặc tài khoản đối tác chưa được kích hoạt.
`AGENTETRAFFIC_AUTHENTICATION_FAILED`	Xác thực đối tác thất bại trong quy trình đăng nhập 2FA.
`AGENTETRAFFIC_OTP_REQUEST_ERROR`	Gặp sự cố khi gửi yêu cầu nhận mã OTP đến cổng dịch vụ xác thực giao thông.
`AGENTETRAFFIC_CONFIRM_OTP_FAILED`	Gặp lỗi hoặc xác nhận mã OTP thất bại với cổng dịch vụ.
`AGENTETRAFFIC_CONFIRM_PASSCODE_FAILED`	Gặp lỗi hoặc xác nhận mã Passcode/PIN thất bại với cổng dịch vụ.
`UNKNOWN_ERROR`	Lỗi không xác định trong quá trình xử lý.

Tham khảo thêm kịch bản kiểm thử giả lập tại: EAgentTraffic – Mock Data & Test Cases (Google Docs)