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:

{
  "firstname": "Hồng",
  "lastname": "Nguyễn",
  "email": "[email protected]",
  "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ề:

{
  "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à ]):

[
  {
    "firstname": "Minh",
    "lastname": "Trần",
    "email": "[email protected]",
    "phone": "0912345678",
    "company": "Công ty Cơ khí A"
  }
]

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

{
  "firstname": "Minh",
  "email": "[email protected]"
}

(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:

[
  {
    "email": "[email protected]",
    "phone": "0911111111",
    "firstname": "Văn",
    "lastname": "Nguyễn"
  },
  {
    "email": "[email protected]",
    "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:

GET https://<domain>/api/contacts?search=phone:[phone]
GET https://<domain>/api/contacts?search=email:[email protected]

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

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:

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