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ý.