# Cloud Sound Box Push

## 1 -  API GỬI SỐ TIỀN XUỐNG THIẾT BỊ VOICEBOX

### 1.1 TỔNG QUAN

Tài liệu mô tả quy trình và cách thức sử dụng API của VietQR để gửi thông tin số tiền thanh toán xuống thiết bị Voicebox.

Tài liệu bao gồm:

* Các thức lấy token xác thực (GET TOKEN)
* Gọi API chính để truyền dữ liệu (thông tin số tiền thanh toán).

### 1.2 - LUỒNG KẾT NỐI

<figure><img src="/files/yccVHvgMQL1lMphABkYo" alt=""><figcaption><p>Luồng gửi thông báo đọc âm thanh BĐSD</p></figcaption></figure>

## 2 - MÔ TẢ APIs

### 2.1 GET TOKEN

Mục đích: API này dùng để tạo Bearer Token cần thiết cho việc xác thực các yêu cầu API tiếp theo (API gửi số tiền thanh toán 2.2).

Method: POST:&#x20;

URL: <https://api.vietqr.org/vqr/api/token_generate>

Request Header:

<table data-header-hidden><thead><tr><th width="191.99993896484375"></th><th></th></tr></thead><tbody><tr><td>Name</td><td>Value</td></tr><tr><td>Content-Type</td><td>application/json</td></tr><tr><td>Authorization</td><td><p>Basic Authentication: </p><p>Base64[username:password]</p></td></tr></tbody></table>

Lưu ý: username, password sẽ do VietQR cung cấp:

Response Body:

<table data-header-hidden><thead><tr><th width="176"></th><th width="137"></th><th></th></tr></thead><tbody><tr><td>Name</td><td>Type</td><td>Desc</td></tr><tr><td>access_token</td><td>String</td><td>Là Bearer Token được VietQR cung cấp sau khi hoàn thành bước 4. Dùng để truy cập tạo mã thanh toán VietQR.</td></tr><tr><td>token_type</td><td>String</td><td>Là token dạng “Bearer”</td></tr><tr><td>expires_in</td><td>int</td><td>Thời gian hết hạn của token. Mặc định là 300 giây</td></tr></tbody></table>

{% tabs %}
{% tab title="cURL:" %}
curl --location --request POST '<https://api.vietqr.org/vqr/api/token\\_generate>' \\

\--header 'Authorization: Basic Y3VzdG9tZXItdmlldHFydGVzdC11c2VyMjQ2ODpZM1Z6ZEc5dFpYSXRkbWxsZEhGeWRHVnpkQzExYzJWeU1qUTJPQT09'
{% endtab %}

{% tab title="Response" %}
{

&#x20;   "access\_token": "eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGRtbGxkSEZ5ZEdWemRDMTFjMlZ5TWpRMk9BPT0iLCJpYXQiOjE3MjEzNzI2MzQsImV4cCI6MTcyMTM3MjkzNH0.D19qvrpYHUgcGjDCXuXXAv3j6lZr6tfmIB0VzdCzAXMJAElGok04sNLysS6PRLdRb0hSgEX5\_9KpLjB-xErn-A",

&#x20;   "token\_type": "Bearer",

&#x20;   "expires\_in": 300

}
{% endtab %}
{% endtabs %}

### 2.2 GỬI THÔNG TIN SỐ TIỀN XUỐNG THIẾT BỊ

Mục đích: API này dùng để truyền thông tin số tiền cần thanh toán xuống thiết bị Voicebox để thiết bị đọc thông báo bằng giọng nói.

Method: POST <https://api.vietqr.org/vqr/api/tid/callback/event/payment>

Request Header:   Request Body

<table data-header-hidden><thead><tr><th width="175"></th><th width="118"></th><th></th></tr></thead><tbody><tr><td>Name</td><td>Type</td><td>Desc</td></tr><tr><td>amount</td><td>long</td><td>Số tiền</td></tr><tr><td>language</td><td>String</td><td>Ngôn ngữ (Mặc định: VN)</td></tr><tr><td>currency</td><td>String</td><td>Đơn vị tiền tệ (Mặc định: VND)</td></tr><tr><td>serialNumber</td><td>String</td><td>Mã serial Number của máy</td></tr><tr><td>referenceNumber</td><td>String</td><td>Mã giao dịch duy nhất</td></tr><tr><td>checkSum</td><td>String</td><td>mã hóa checkSum MD5(username + amount + referenceNumber + serialNumber)</td></tr></tbody></table>

Response Body:

| Name    | Type   | Desc                                                  |
| ------- | ------ | ----------------------------------------------------- |
| status  | String | <p>“SUCCESS”: Thành công</p><p>“FAILED”: Thất bại</p> |
| message | String | Mã lỗi                                                |

Thông tin cURL:

```json
curl --location 'https://api.vietqr.org/vqr/api/vnpt-epay/callback' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9' \
--header 'Cookie: JSESSIONID=349BED123B39E6FF3D30630E85E46C85' \
--data '{
    "amount": 8000,
    "language": "VN",
    "currency": "VND",
    "referenceNumber": "FT25132940673006",
    "serialNumber": "BT37878837",
    "checkSum": "cee74d89030f6190afea4da84fb41fe5"
}'
```

Response:

{

&#x20;   "status": "SUCCESS",

&#x20;   "message": ""

}

(Link tài liệu [tại đây](https://docs.google.com/document/d/12Ywi81VAaO8-0iy8dtMm2m1QFXDsbHbiD1jEPWtMPU8/edit?tab=t.0))

\---------------------------------------------------

## HƯỚNG DẪN THỰC HÀNH DÙNG POSHMAN PUSH

### Bước 1 : GET TOKEN

<figure><img src="/files/FxbJlosLo3BN66M3skWK" alt=""><figcaption><p>Lấy Token</p></figcaption></figure>

### Bước 2 : PUSH ÂM THANH VÀ SỐ TIỀN THÀNH CÔNG XUỐNG THIẾT BỊ :&#x20;

<figure><img src="/files/nvUZQYyDwO4svgi9cO3r" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api.vietqr.vn/vi/cac-dich-vu-api-khac/cloud-sound-box-push.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.