Định dạng Response (Envelope)
Khung phản hồi chuẩn của HiTechCloud Pay API: mọi endpoint đều trả JSON gồm status, data và meta để bạn xử lý kết quả và phân trang nhất quán.
Mọi phản hồi từ HiTechCloud Pay API đều được gói trong một cấu trúc nhất quán gọi là Envelope. Nhờ đó mã client của bạn chỉ cần viết một lớp xử lý chung cho tất cả endpoint, bất kể là tài khoản ngân hàng, giao dịch hay tài khoản ảo.
Các trường trong Envelope
| Trường | Kiểu | Mô tả |
|---|---|---|
status | string | success khi thành công, error khi có lỗi |
data | object | array | Dữ liệu chính: mảng khi truy vấn danh sách, object khi lấy chi tiết |
meta | object | Siêu dữ liệu, chứa pagination khi phản hồi là danh sách |
code | string | Chỉ xuất hiện khi lỗi: mã lỗi dạng chuỗi (ví dụ UNAUTHORIZED) |
message | string | Chỉ xuất hiện khi lỗi: mô tả lỗi bằng tiếng Việt dễ hiểu |
Phản hồi danh sách (list)
Envelope khi trả về danh sách
{
"status": "success",
"data": [
{ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "amount_in": 1500000 }
],
"meta": {
"pagination": {
"total": 125,
"per_page": 20,
"current_page": 1,
"last_page": 7,
"has_more": true
}
}
}Phản hồi chi tiết (single)
Envelope khi trả về một bản ghi
{
"status": "success",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"amount_in": 1500000,
"transaction_content": "DH100234 chuyen tien mua VPS"
}
}Phản hồi lỗi (error)
Envelope khi có lỗi
{
"status": "error",
"code": "VALIDATION_ERROR",
"message": "Tham số from_date không đúng định dạng ngày."
}Luôn kiểm tra trường
status trước khi đọc data. Khi status là error, trường data sẽ không xuất hiện; thay vào đó hãy đọc code và message.Mọi phản hồi từ HiTechCloud Pay API đều được gói trong một cấu trúc nhất quán gọi là Envelope. Nhờ đó mã client của bạn chỉ cần viết một lớp xử lý chung cho tất cả endpoint, bất kể là tài khoản ngân hàng, giao dịch hay tài khoản ảo.
Các trường trong Envelope
| Trường | Kiểu | Mô tả |
|---|---|---|
status | string | success khi thành công, error khi có lỗi |
data | object | array | Dữ liệu chính: mảng khi truy vấn danh sách, object khi lấy chi tiết |
meta | object | Siêu dữ liệu, chứa pagination khi phản hồi là danh sách |
code | string | Chỉ xuất hiện khi lỗi: mã lỗi dạng chuỗi (ví dụ UNAUTHORIZED) |
message | string | Chỉ xuất hiện khi lỗi: mô tả lỗi bằng tiếng Việt dễ hiểu |
Phản hồi danh sách (list)
Phản hồi chi tiết (single)
Phản hồi lỗi (error)
Luôn kiểm tra trường
status trước khi đọc data. Khi status là error, trường data sẽ không xuất hiện; thay vào đó hãy đọc code và message.Envelope khi trả về danh sách
{
"status": "success",
"data": [
{ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "amount_in": 1500000 }
],
"meta": {
"pagination": {
"total": 125,
"per_page": 20,
"current_page": 1,
"last_page": 7,
"has_more": true
}
}
}Envelope khi trả về một bản ghi
{
"status": "success",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"amount_in": 1500000,
"transaction_content": "DH100234 chuyen tien mua VPS"
}
}Envelope khi có lỗi
{
"status": "error",
"code": "VALIDATION_ERROR",
"message": "Tham số from_date không đúng định dạng ngày."
}