# 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="https://3142601633-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDGqts6lCk1fULljyG3r6%2Fuploads%2FNDFDTwh8ThAQYXFIeIw5%2F%7BB80825E1-3882-4B5A-91E0-2AC5D3A32FA7%7D.png?alt=media&#x26;token=34fb0173-f777-42ea-bc1b-706598ba5e23" 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="https://3142601633-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDGqts6lCk1fULljyG3r6%2Fuploads%2F6v8yWSwQQgQ8koUoIGl4%2Fimage.png?alt=media&#x26;token=43041e85-7a3d-4088-a267-4bd6be9a206f" 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="https://3142601633-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDGqts6lCk1fULljyG3r6%2Fuploads%2FQCxU0AIpMXrae52wAi5N%2Fimage.png?alt=media&#x26;token=3e5e5908-4804-44ab-a992-ea72b80a4d0a" alt=""><figcaption></figcaption></figure>