Bắt đầu nhanh với HiTechCloud Pay SoundBox API
Bắt đầu nhanh Loa thông báo HiTechCloud Pay: năm bước tạo access token, liên kết thiết bị SoundBox và phát âm thanh thông báo tiền về đầu tiên.
Tài liệu hướng dẫn lập trình viên kết nối thiết bị loa SoundBox vào hệ thống quản lý bán hàng (POS) hoặc website.
Bước 1: Lấy Access Token
Gọi API tạo token bằng phương thức HTTP Basic Authentication với username là client_id và password là client_secret:
cURL tạo Access Token
curl -X POST "https://speaker-api.hitechcloud.vn/devices/v1/token/create" \
-H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)"Phản hồi (201 Created)
{
"code": 201,
"message": "Resource created",
"data": "—",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"ttl": 6000
}Token có thời gian sống (TTL) là 6000 giây (100 phút). Hãy lưu token vào bộ nhớ đệm (cache) và tái sử dụng cho các lệnh phát thanh tiếp theo.
Bước 2: Kiểm tra thiết bị loa
Sử dụng mã số hardwareId in dưới đáy loa (ví dụ: HTC_S5_2508000001) để kiểm tra trạng thái:
cURL kiểm tra thiết bị
curl -X POST "https://speaker-api.hitechcloud.vn/devices/v1/speaker/pair/check" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"hardwareId": "HTC_S5_2508000001"}'Phản hồi (200 OK)
{
"code": 200,
"message": "Thành công",
"data": {
"hardwareId": "HTC_S5_2508000001",
"model": "HiTechCloud SoundBox S5 Plus",
"isPaired": false,
"online": true
}
}Bước 3: Ghép nối thiết bị và Xác thực OTP
- Bật chế độ ghép nối: Nhấn giữ nút nguồn/ghép nối trên thân loa trong 3 giây cho đến khi loa phát âm thanh báo hiệu.
- Yêu cầu ghép nối: Gọi
POST /devices/v1/speaker/pair/requestvớihardwareId. Loa sẽ phát ra giọng nói đọc to 4 chữ số OTP ngẫu nhiên (ví dụ: 'Mã xác thực của bạn là: 8 9 2 1') và trả vềsession_id. - Xác thực OTP: Gọi
POST /devices/v1/speaker/pair/verifygửi kèmhardwareId,session_idvà mãotp. Loa sẽ thông báo 'Ghép nối thành công'.
cURL xác thực OTP ghép nối
curl -X POST "https://speaker-api.hitechcloud.vn/devices/v1/speaker/pair/verify" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"hardwareId": "HTC_S5_2508000001",
"session_id": "8b9f6d2a-3c1b-4f7a-a7d4-123456789abc",
"otp": "8921"
}'Bước 4: Bắn thông báo biến động số dư (Đọc số tiền)
Khi hệ thống ghi nhận khách đã thanh toán, hãy gọi API này để loa ngay lập tức đọc to số tiền:
cURL phát âm thanh đọc tiền
curl -X POST "https://speaker-api.hitechcloud.vn/devices/v1/speaker/transactions/notify" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"hardwareId": "HTC_S5_2508000001",
"amount": 250000,
"requestId": "TXN_20250515_00099"
}'Phản hồi thông báo
{
"code": 200,
"message": "Đã gửi thông báo thành công",
"data": {
"hardwareId": "HTC_S5_2508000001",
"requestId": "TXN_20250515_00099",
"status": "SENT"
}
}Trường
requestId bắt buộc phải là duy nhất cho mỗi giao dịch. Nếu bạn gửi trùng requestId, loa sẽ tự động bỏ qua để tránh phát âm thanh trùng lặp.