# Thông tin chung

## **Các thông tin cơ bản**

* Domain: Là chuỗi ký tự đại diện cho một tài khoản doanh nghiệp mà khách hàng sử dụng trên nền tảng CareSoft.  Ví dụ sau khi ký hợp đồng và triển khai nghiệp vụ caresoft bàn giao cho khách hàng địa chỉ đăng nhập là `https://caresoft.vn/`**`khachhang01`**  thì chuỗi "**khachhang01**" sẽ được gọi là domain trên hệ thống CareSoft.  Trong các API sẽ định nghĩa phần này bằng biến <mark style="color:green;background-color:purple;">`{{domain}}`</mark>. Domain này do CareSoft cung cấp cho mỗi khách hàng.
* Api token: Là chuỗi mã bảo mật được cấu hình trên hệ thống CareSoft. Token chỉ thay đổi khi người quản trị bấm nút reset trên màn hình cấu hình. Trong các API sẽ định nghĩa phần này bằng biến <mark style="color:green;">`{{apiToken}}`</mark>.&#x20;
* Host: Là địa chỉ gốc để truy cập các api. CareSoft sử dụng địa chỉ

  * `https://api.caresoft.vn/` làm địa chỉ gốc, dự phòng là&#x20;
  * `https://api2.caresoft.vn/`

  Các mô tả dưới đây sẽ mặc định kèm tiền tố host ở đầu mỗi truy xuất \
  **Ví dụ**: Tài liệu mô tả lấy danh sách agent sẽ ghi `GET {domain}/api/v1/agents.` Khi truy xuất sẽ nối chuỗi thành `https://api.caresoft.vn/{domain}/api/v1/agents`

## Cách lấy Api Token trên giao diện CareSoft

Để lấy API Token. Cần tài khoản Admin để đăng nhập vào tài khoản trên hệ thống CareSoft, Truy cập vào phần <mark style="color:green;">`Admin-->Api -->Api token`</mark>

{% hint style="info" %}
Bạn có thể khởi tạo và cập nhật bất cứ lúc nào. Lưu ý nếu thay đổi API KEY này các chương trình đang tích hợp sẽ bị mất kết nối.&#x20;
{% endhint %}

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FFIrQi1MV6pJmOJmZpziH%2FTaoAPI.png?alt=media&#x26;token=6e7c4122-5462-4fb8-86c7-36dac8128785" alt=""><figcaption><p>Màn hình cấu hình tạo và nhận kết quả API token trên hệ thống Caresoft</p></figcaption></figure>

## Phương thức xác thực

Xác thực qua access token, mỗi domain (account) sẽ được cấp 1 access token, yêu cầu tất cả các request gọi lên đều phải thêm "Authorization" header, kiểu dữ liệu yêu cầu là Json.&#x20;

Các API được mô tả trong tài liệu này ngầm hiểu đã được đính kèm\
&#x20;<mark style="color:green;background-color:green;">`Authorization`</mark> và <mark style="color:green;">`Content-Type`</mark> trong header &#x20;

Ví dụ về set header vào request lấy danh sách chuyên viên

```bash
curl 
--location 'https://api.caresoft.vn/{{domain}}/api/v1/agents' \
--header 'Authorization: Bearer {{apiToken}}' \
--header 'Content-Type: application/json'

```

## Tạo request đầu tiên

Thử nghiệm với API danh sách khách hàng để hiểu cơ chế hoạt động của hệ thống&#x20;

## Lấy danh sách Agents

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/agents`

Lấy danh sách các agent của 1 domain trên hệ thống CareSoft

#### Headers

| Name                                            | Type                | Description                       |
| ----------------------------------------------- | ------------------- | --------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | Bearer {{apiToken}} | Mã API token từ hệ thống CareSoft |
| Content-Type<mark style="color:red;">\*</mark>  | application/json    | Kiểu dữ liệu                      |

{% tabs %}
{% tab title="200: OK Thành công" %}
{% tabs %}
{% tab title="Ví dụ điển hình" %}

```json
{
    "code": "ok",
    "agents": [
        {
            "id": 142928097,
            "username": "Sample",
            "email": "DiegoS@50pdp0.onmicrosoft.com",
            "phone_no": "0336842288",
            "agent_id": "50007",
            "created_at": "2022-07-08 09:48:41",
            "updated_at": "2022-08-08 17:42:08",
            "group_id": 12153,
            "group_name": "Default Group",
            "role_id": 1,
            "login_status": "AVAILABLE",
            "call_status": "AVAILABLE"
        }
        ]
}
```

{% endtab %}

{% tab title="Cấu trúc kết quả" %}

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401: Unauthorized Sai API Token hoặc không cung cấp API Token" %}
{% tabs %}
{% tab title="Cấu trúc kết quả" %}

<table><thead><tr><th width="117" data-type="number">STT</th><th>Tên trường</th><th>Ghi chú</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái: <br>- errors: Lỗi</td></tr><tr><td>2</td><td>message</td><td><pre><code>Authorization header is either missing or incorrect
</code></pre></td></tr></tbody></table>
{% endtab %}

{% tab title="Ví dụ điển hình" %}

```json
{
    "code": "errors",
    "message": "Authorization header is either missing or incorrect"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500: Internal Server Error Lỗi chung " %}

{% endtab %}

{% tab title="422: Unprocessable Entity Thiếu thông tin đầu vào (một số trường hợp)" %}

{% endtab %}

{% tab title="404: Not Found Không tìm thấy tài nguyên, Lỗi này kiểm tra lại API Url xem chính xác hay chưa" %}

{% endtab %}
{% endtabs %}

Ví dụ điển hình khi triệu gọi API CareSoft qua `curl`: Bạn cũng có thể áp dụng  để tạo Api call trên ứng dụng của bạn hoặc trên ứng dụng  Postman&#x20;

{% tabs %}
{% tab title="curl" %}
{% code title="Cấu hình curl với thông tin xác thực" overflow="wrap" %}

```sh

curl 
--location 'https://api.caresoft.vn/{{domain}}/api/v1/agents' \
--header 'Authorization: Bearer {{apiToken}}' \
--header 'Content-Type: application/json'

```

{% endcode %}
{% endtab %}

{% tab title="postman" %}

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2F1LGQqiIyQRszKuN0Oh5P%2FCauhinhPostman.png?alt=media&#x26;token=bd95012c-ec40-4a69-8d11-34cd86250d61" alt=""><figcaption><p>Cấu hình chèn thông tin xác thực trên postman</p></figcaption></figure>
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Lưu ý:** Trong một số trường hợp thông tin yêu cầu bắt buộc được trả về trong body response. Cần kiểm tra thêm dữ liệu trả về để xử lý lỗi. Các trường hợp như vậy CareSoft sẽ mô tả rõ trong từng API chi tiết
{% endhint %}

## **THAM KHẢO**&#x20;

* **POSTMAN**\
  \
  Postman là một loại công cụ cho phép người dùng có thể thao tác với API, mà trong đó phổ biến nhất là REST. Với thử nghiệm API thì Postman là một trong những công cụ phổ biến vì được thực nghiệm nhiều nhất. Nhờ Postman lập trình viên có thể gọi Rest API mà không cần phải viết bất kỳ dòng code nào. Postman có khả năng hỗ trợ mọi phương thức HTTP bao gồm: POST, PUT, DELETE, PATCH, GET,... Ngoài ra, Postman còn cho phép lập trình viên lưu lại lịch sử của các lần request nên vô cùng tiện lợi cho nhu cầu sử dụng lại.\
  \
  Đây là loại công cụ mã nguồn mở nên rất dễ để tải về.  Bạn cần truy cập vào website: <https://www.getpostman.com/downloads/>. Sau đó lựa chọn nền tảng mà bạn muốn tải (có thể là Windows, Linux hoặc Mac).

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FKiewIETOc0HcPEKk9R0C%2FPOSTMAN.png?alt=media&#x26;token=0898dbc1-9264-4336-81a6-3fa2885949d2" alt=""><figcaption><p>Giao diện trang web postman </p></figcaption></figure>