Trong trang này

Xác thực (API Token)

Mọi request tới API cần xác thực (trừ vài endpoint công khai như danh sách ngân hàng và sinh mã QR) đều phải gửi kèm API Token qua header Authorization theo chuẩn Bearer.

Authorization: Bearer {api_token}

#Tạo API Token

Đây là bước bắt buộc trước khi gọi bất kỳ endpoint cần xác thực nào.

Đăng nhập dashboard QHTech.
Vào menu Tích hợp → API Access (/api-access).
Bấm Tạo API Token, đặt tên gợi nhớ (ví dụ server-production), rồi sao chép token ngay.

Token gốc chỉ hiển thị một lần duy nhất khi tạo. Nếu làm mất, hãy thu hồi token cũ và tạo token mới. Bạn có thể tạo nhiều token và thu hồi bất kỳ token nào bất cứ lúc nào trong trang API Access.

#Phạm vi truy cập

Mỗi token gắn với một tài khoản chủ sở hữu. Token chỉ truy cập được dữ liệu (giao dịch, tài khoản ngân hàng) thuộc về chủ token đó.
Nếu bạn truyền tham số trỏ tới tài nguyên không thuộc về mình (ví dụ bank_account_id của người khác), API sẽ không trả về dữ liệu.

#Sử dụng token

Gửi token trong header Authorization ở mọi request:

curl -G "https://app.qh2pay.com/api/transactions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

const res = await fetch("https://app.qh2pay.com/api/transactions", {
  headers: {
    Authorization: `Bearer ${API_TOKEN}`,
    Accept: "application/json",
  },
});
const data = await res.json();

$response = Http::withToken('YOUR_TOKEN')
    ->acceptJson()
    ->get('https://app.qh2pay.com/api/transactions');

$data = $response->json();

#Lỗi xác thực

Tình huống	HTTP	Body
Thiếu / sai định dạng header `Authorization`	`401`	`{ "message": "Thiếu API Token. Vui lòng gửi header Authorization: Bearer {token}." }`
Token không tồn tại hoặc đã bị thu hồi	`401`	`{ "message": "API Token không hợp lệ." }`

#Ghi chú bảo mật

Token được lưu dưới dạng băm SHA-256; hệ thống không lưu token gốc. Vì vậy token gốc chỉ có thể xem một lần khi tạo.
Mỗi request hợp lệ sẽ cập nhật thời điểm dùng gần nhất (last_used_at) của token — giúp bạn theo dõi token nào đang hoạt động.
Không đưa token vào mã nguồn phía client (trình duyệt, app di động) hay commit lên Git. Chỉ dùng token ở phía máy chủ.
Thu hồi token bị lộ ngay lập tức tại trang API Access; token bị thu hồi sẽ trả 401 ngay từ request kế tiếp.