> 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/api-contacts-va-batch-contacts.md).

# API Quản lý Contact & Xử lý Batch

API Contact là một trong những API quan trọng nhất trên hệ sinh thái **ABOT**. Tài liệu này hướng dẫn chi tiết cách tạo mới, tra cứu, cập nhật contact và các quy tắc sống còn khi thao tác với cơ chế **Định danh duy nhất (Unique Identifier)** và **Batch API**.

***

## 1. Phân biệt giữa API Đơn lẻ và API Batch

| Tiêu chí             | API Đơn lẻ (`/api/contacts/new`)                             | API Hàng loạt (`/api/contacts/batch/new`)                                          |
| -------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| **Endpoint**         | `POST /api/contacts/new`                                     | `POST /api/contacts/batch/new`                                                     |
| **Cấu trúc Body**    | Một **JSON Object `{ ... }`**                                | Một **Mảng các JSON Object `[ { ... } ]`**                                         |
| **Xử lý trùng lặp**  | Nếu trùng trường Unique ID ➡️ **Bị chặn và trả về lỗi 422**. | Nếu trùng trường Unique ID ➡️ **Tự động gộp (Merge) & Cập nhật contact cũ**.       |
| **Mục đích sử dụng** | Tạo từng khách hàng khi chắc chắn là khách mới.              | Nhập danh sách, đồng bộ từ Form/CRM hoặc khi không biết khách đã tồn tại hay chưa. |

***

## 2. Tạo Contact đơn lẻ (`POST /api/contacts/new`)

### Yêu cầu:

* **Method:** `POST`
* **URL:** `https://<domain>/api/contacts/new`
* **Headers:**
  * `Authorization: Basic <base64>`
  * `Content-Type: application/json`

### Body mẫu:

```json
{
  "firstname": "Hồng",
  "lastname": "Nguyễn",
  "email": "hong.nguyen@example.com",
  "phone": "0987654321",
  "company": "NC Network",
  "position": "Trưởng phòng Kinh doanh"
}
```

### ⚠️ Lưu ý quan trọng về Lỗi `422 This field must be unique`:

Từ phiên bản Mautic 5.0 đến ABOT 7.x, nếu trường `email` hoặc `phone` đang được bật cờ **Unique Identifier (Định danh duy nhất)** mà số điện thoại/email đó **đã tồn tại** trên hệ thống, API sẽ từ chối tạo mới và trả về:

```json
{
  "errors": [
    {
      "code": 422,
      "message": "phone: This field must be unique."
    }
  ]
}
```

👉 **Giải pháp:** Nếu muốn tự động cập nhật contact khi đã tồn tại thay vì báo lỗi 422, hãy chuyển sang dùng **Batch API** bên dưới.

***

## 3. Tạo / Hợp nhất Contact hàng loạt (`POST /api/contacts/batch/new`)

Batch API cho phép bạn gửi một hoặc nhiều contact cùng một lúc với khả năng **tự động kiểm tra trùng lặp (Deduplication) và gộp dữ liệu (Merge)**.

### Yêu cầu:

* **Method:** `POST`
* **URL:** `https://<domain>/api/contacts/batch/new`
* **Headers:**
  * `Authorization: Basic <base64>`
  * `Content-Type: application/json`

### ⚠️ QUY TẮC CẤU TRÚC BODY: BẮT BUỘC DÙNG MẢNG `[ ... ]`

Kể cả khi bạn chỉ muốn gửi **1 contact duy nhất**, Body gửi lên vẫn **BẮT BUỘC phải đặt trong cặp ngoặc vuông `[ ]`**:

#### ✅ Cấu trúc ĐÚNG (Có dấu `[` và `]`):

```json
[
  {
    "firstname": "Minh",
    "lastname": "Trần",
    "email": "minh.tran@nc-net.vn",
    "phone": "0912345678",
    "company": "Công ty Cơ khí A"
  }
]
```

#### ❌ Cấu trúc SAI (Gây lỗi HTTP 500 TypeError):

```json
{
  "firstname": "Minh",
  "email": "minh.tran@nc-net.vn"
}
```

*(Nếu gửi thiếu cặp ngoặc vuông `[]`, hệ thống sẽ trả về lỗi: `500 Argument #1 ($params) must be of type array, string given`).*

### Gửi nhiều contact cùng một lượt:

```json
[
  {
    "email": "contact1@example.com",
    "phone": "0911111111",
    "firstname": "Văn",
    "lastname": "Nguyễn"
  },
  {
    "email": "contact2@example.com",
    "phone": "0922222222",
    "firstname": "Thị",
    "lastname": "Lê"
  }
]
```

### Cơ chế hoạt động của Batch API:

1. Hệ thống đọc từng phần tử trong mảng.
2. Kiểm tra xem `email` hoặc `phone` đã có trong hệ thống chưa:
   * **Nếu CHƯA có:** Tạo mới và trả về mã `201 Created`.
   * **Nếu ĐÃ có:** Tự động chuyển sang phương thức `PATCH` để cập nhật thông tin bổ sung vào contact cũ và trả về mã `200 OK`.

***

## 4. Tra cứu Contact (`GET /api/contacts`)

### Tìm kiếm contact theo số điện thoại hoặc email:

```http
GET https://<domain>/api/contacts?search=phone:0987654321
GET https://<domain>/api/contacts?search=email:hong.nguyen@example.com
```

### Lấy thông tin chi tiết của 1 Contact theo ID:

```http
GET https://<domain>/api/contacts/{id}
```

***

## 5. Cập nhật Contact theo ID (`PATCH /api/contacts/{id}/edit`)

Khi bạn đã biết Contact ID (ví dụ: `184509`), bạn có thể cập nhật chính xác bản ghi đó:

### Yêu cầu:

* **Method:** `PATCH`
* **URL:** `https://<domain>/api/contacts/184509/edit`
* **Body:**

```json
{
  "company": "Công ty TNHH NC Network Việt Nam",
  "position": "Giám đốc Dự án"
}
```