> For the complete documentation index, see [llms.txt](https://docs.abot.vn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.abot.vn/rest-api-and-webhooks/tong-quan-va-xac-thuc-api.md).

# Tổng quan và Phương thức Xác thực API

Hệ thống **ABOT** cung cấp hệ thống REST API toàn diện, cho phép bạn dễ dàng tích hợp danh bạ, chiến dịch, phân khúc và biểu mẫu với các phần mềm CRM, ERP, Website, Landing Page hoặc các công cụ tự động hóa như n8n, Make, Zapier.

***

## 1. Endpoint cơ sở (Base URL)

Tất cả các lệnh gọi API đều gửi tới URL có tiền tố `/api/`:

```
https://<ten-mien-abot-cua-ban>/api/
```

*Ví dụ:* `https://ncnetwork.abot.vn/api/` hoặc `https://cnctech.abot.vn/api/`

***

## 2. Các phương thức xác thực (Authentication)

ABOT hỗ trợ 2 phương thức xác thực: **Basic Authentication** (nhanh chóng, tiện dụng) và **OAuth2** (bảo mật cao, cấp quyền theo scope).

### 2.1. Basic Authentication (Khuyên dùng khi tích hợp backend nội bộ)

Đây là cách đơn giản và phổ biến nhất để gọi API từ hệ thống máy chủ của bạn.

#### Cách thức hoạt động:

1. Chuẩn bị tài khoản quản trị viên hoặc user có quyền API (ví dụ: `admin_ncnetwork`).
2. Ghép tên đăng nhập và mật khẩu theo định dạng: `username:password`.
3. Mã hóa chuỗi trên sang định dạng **Base64**.
4. Truyền chuỗi mã hóa vào Header HTTP: `Authorization: Basic <chuoi-base64>`.

#### Ví dụ tạo chuỗi Basic Auth:

* **Chuỗi gốc:** `admin_ncnetwork:Abot@NCNet2026!`
* **Mã hóa Base64:** `YWRtaW5fbmNuZXR3b3JrOkFib3RATkNOZXQyMDI2IQ==`
* **Header:**

  ```http
  Authorization: Basic YWRtaW5fbmNuZXR3b3JrOkFib3RATkNOZXQyMDI2IQ==
  ```

#### Gọi thử nghiệm bằng cURL:

```bash
curl -X GET "https://ncnetwork.abot.vn/api/contacts" \
  -H "Authorization: Basic YWRtaW5fbmNuZXR3b3JrOkFib3RATkNOZXQyMDI2IQ==" \
  -H "Accept: application/json"
```

*(Hoặc dùng cờ `-u` rút gọn: `curl -u "admin_ncnetwork:Abot@NCNet2026!" ...`)*

***

### 2.2. OAuth 2.0 (Dành cho ứng dụng bên thứ ba hoặc SaaS)

1. Đăng nhập vào ABOT ➡️ Vào **Cài đặt (Bánh răng)** ➡️ **Cấu hình (Configuration)** ➡️ **Cài đặt API (API Settings)**.
2. Bật cờ:
   * **API enabled:** Yes
   * **Enable HTTP basic auth:** Yes (nếu muốn dùng Basic Auth)
3. Vào **Bánh răng** ➡️ **API Credentials (Thông tin xác thực API)** ➡️ Bấm **New**:
   * **Name:** Tên ứng dụng của bạn.
   * **Redirect URI:** Địa chỉ callback của ứng dụng bạn.
   * **Authorization Type:** OAuth 2.
4. Lưu lại **Client ID** và **Client Secret** để sử dụng trong luồng Authorization Code Grant hoặc Client Credentials.

***

## 3. Định dạng Dữ liệu (Request & Response)

* **Content-Type:** `application/json` (bắt buộc khi gửi dữ liệu POST/PATCH).
* **Accept:** `application/json`.
* **Quy ước mã phản hồi HTTP:**
  * `200 OK`: Yêu cầu thành công, dữ liệu đã được cập nhật hoặc trả về.
  * `201 Created`: Bản ghi mới đã được tạo thành công.
  * `400 Bad Request`: Tham số yêu cầu không hợp lệ hoặc cú pháp JSON sai.
  * `401 Unauthorized`: Xác thực thất bại (sai username/mật khẩu hoặc token hết hạn).
  * `403 Forbidden`: Tài khoản không có quyền truy cập module này.
  * `404 Not Found`: Không tìm thấy bản ghi hoặc sai đường dẫn endpoint.
  * `422 Unprocessable Entity`: Dữ liệu không vượt qua bộ kiểm tra hợp lệ (ví dụ: trùng lặp trường định danh duy nhất `email` hoặc `phone`).
  * `500 Internal Server Error`: Lỗi phát sinh từ máy chủ.