> For the complete documentation index, see [llms.txt](https://help-cdp.hub-js.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help-cdp.hub-js.com/webhook-and-api/webhook.md).

# WEBHOOK

Hướng dẫn Tích hợp Webhook cho CDP

Các hệ thống third-party gửi dữ liệu đến CDP thông qua một endpoint webhook duy nhất.&#x20;

Loại dữ liệu được xác định qua trường object\_type.

#### Endpoint

POST {cdp-domain}/erp/webhook\
Content-Type: application/json

#### Cấu trúc request chung

| Field        | Type   | Required | Mô tả                                                         |
| ------------ | ------ | -------- | ------------------------------------------------------------- |
| object\_type | string | ✅        | "customer" / "order" / "deal" / "ticket"                      |
| object\_id   | int    | ✅        | ID của object bên đối tác                                     |
| action       | string | ✅        | "create" / "update" / "delete"                                |
| data         | object | ✅        | Dữ liệu chi tiết (xem từng section bên dưới)                  |
| timestamp    | string | -        | Thời gian gửi — ISO 8601 (VD: 2026-04-17T03:12:54) (Optional) |

Response

| HTTP Code | Body              | Mô tả                                             |
| --------- | ----------------- | ------------------------------------------------- |
| 200       | {"success":true}  | Nhận thành công                                   |
| 500       | {"success":false} | Lỗi hệ thống hoặc định dạng request không hợp lệ. |
| 404       | {"success":false} | Lỗi lưu dữ liệu                                   |

Webhook xác nhận nhận dữ liệu ngay lập tức. Việc xử lý thực tế diễn ra bất đồng bộ ở phía CDP.

{% hint style="info" %}
***Lưu ý: Cơ chế Định danh Khách hàng (Deduplication)***

*Với tất cả các loại webhook, khách hàng được nhận diện theo thứ tự ưu tiên:*

*1. id\_vendor (ID khách hàng bên third-party)*\
*2. phone (Số điện thoại)*\
*3. email*\
*→ Nếu không tìm thấy: Tạo mới khách hàng.*
{% endhint %}

### 1. Customer (Khách hàng)

#### data object

| Field       | Type         | Required | Mô tả                                            |
| ----------- | ------------ | -------- | ------------------------------------------------ |
| id          | int          | ✅        | ID khách hàng bên đối tác                        |
| phone       | string       | ✅        | Số điện thoại                                    |
| name        | string       | -        | Họ tên đầy đủ                                    |
| email       | string\|null | ✅        | Nếu phone trống thì cần có dữ liệu email         |
| address     | string\|null | -        | Địa chỉ                                          |
| birthday    | string\|null | -        | Ngày sinh định dạng YYYY-MM-DD                   |
| gender      | string\|null | -        | "male" / "female"                                |
| facebook    | string\|null | -        | Facebook URL hoặc username                       |
| sources     | array        | -        | Danh sách nguồn khách hàng (xem bên dưới)        |
| branches    | array        | -        | <p>Danh sách chi nh</p><p>ánh (xem bên dưới)</p> |
| owner       | object\|null | -        | Nhân viên phụ trách (xem bên dưới)               |
| created\_at | string       | -        | Ngày tạo - ISO 8601                              |
| updated\_at | string       | -        | Ngày cập nhật - ISO 8601                         |

{% hint style="danger" %}
***Lưu ý:***&#x20;

* Cần cung cấp ít nhất một trong hai trường phone hoặc email.
* Ngoài các field trong bảng trên, payload có thể gửi bất kỳ key nào có alias trùng với Trường tùy chỉnh object “Contacts” trong CDP → hệ thống sẽ tự apply. Key không match alias sẽ bị bỏ qua (không báo lỗi).\
  Ví dụ: "vip\_tier": "gold", "occupation": "engineer", "dac\_points": 1500 — nếu CDP có 3 custom field alias trùng → giá trị được lưu vào object contact; nếu không có → bỏ qua, không ảnh hưởng các field khác.
* Lưu ý, các key sau không pass-through (do đã có cấu trúc mapping sang alias khác hoặc logic xử lý riêng), gồm: \`id\`, \`phone\`, \`name\`, \`address\`, \`birthday\`, \`created\_at\`, \`updated\_at\`, \`sources\`, \`branches\`, \`owner\`, \`assistant\`.
* **Khi cần truyền thêm các thông tin của object Customer như (Mục tiêu, Nghề nghiệp, Hạng thành viên, Tổng tiền tích lũy, …) hoàn toàn có thể tạo thêm trường tùy chỉnh trên hệ thống CDP sau đó bổ sung payload truyền các dữ liệu này sang.**
  {% endhint %}

**data.sources\[]**

| Field      | Type   | Mô tả                             |
| ---------- | ------ | --------------------------------- |
| id         | int    | ID nguồn bên đối tác              |
| code       | string | Mã nguồn (VD: "VANG\_LAI")        |
| name       | string | Tên nguồn (VD: "Tự đến/Vãng lai") |
| is\_active | bool   | True - Đang hoạt động             |

{% hint style="warning" %}
*Lưu ý: Chỉ xử lý phần tử đầu tiên trong mảng.*
{% endhint %}

**data.branches\[]**

| Field | Type   | <p>Mô tả</p><p><br></p>      |
| ----- | ------ | ---------------------------- |
| id    | int    | ID chi nhánh bên đối tác     |
| code  | string | Mã chi nhánh (VD: "QGV")     |
| name  | string | Tên chi nhánh (VD: "Gò Vấp") |

{% hint style="warning" %}
*Lưu ý: Hỗ trợ nhiều chi nhánh, khách hàng sẽ được gắn vào tất cả các chi nhánh tương ứng*
{% endhint %}

#### &#x20;data.owner

| Field      | Type   | Mô tả                                                          |
| ---------- | ------ | -------------------------------------------------------------- |
| id         | int    | ID nhân viên trên hệ thống third-party                         |
| full\_name | string | Họ tên nhân viên                                               |
| email      | string | Email nhân viên — sử dụng để mapping với CDP qua thông tin này |

{% hint style="warning" %}
*Lưu ý: Nếu không tìm thấy email trong CDP → bỏ qua, không báo lỗi*
{% endhint %}

#### Ví dụ mảng body request hợp lệ

```
{
  "object_type": "customer",
  "object_id": 30,
  "action": "create",
  "data": {
    "id": 30,
    "name": "Test",
    "phone": "0123456789",
    "email": null,
    "address": "Dương Quảng Hàm, Hà Nội",
    "birthday": null,
    "gender": "female",
    "ranking_label": "Gold",
    "occupation": "KOL",
    "target": "Thon mặt",
    "facebook": null,
    "sources": [
      {
        "id": 1,
        "code": "GIOI_THIEU",
        "name": "Giới thiệu",
        "is_active": true
      }
    ],
    "branches": [
      {
        "id": 1,
        "code": "HCM",
        "name": "Hồ Chí Minh"
      }
    ]
   "owner": {
      "id": 40,
      "full_name": "NGUYỄN THÀNH TRUNG",
      "email": "ntrung@example.com"
    },
    "created_at": "2026-04-17T10:11:57",
    "updated_at": "2026-04-17T10:11:57"
   }
}
```

### 2. Order (Đơn hàng)

#### data object

| Field             | Type   | Required    | Mô tả                                                      |
| ----------------- | ------ | ----------- | ---------------------------------------------------------- |
| id                | int    | ✅           | ID đơn hàng bên đối tác — Unique key                       |
| code              | string | ✅           | Mã đơn hàng (VD: "ĐH-20260417-00003")                      |
| order\_date       | string | ✅           | Ngày tạo đơn — ISO 8601                                    |
| status            | string | -           | "completed" / "pending" / "cancelled"                      |
| payment\_status   | string | -           | "completed" / "pending" / "partial"                        |
| subtotal          | number | -           | Tổng tiền trước giảm                                       |
| total             | number | -           | Tổng tiền thực thu                                         |
| discount          | number | -           | Tổng giảm giá                                              |
| discount\_code    | text   | <p><br></p> | Mã voucher/coupon đã áp dụng (null nếu không dùng voucher) |
| note              | string | -           | Ghi chú đơn hàng                                           |
| order\_group      | string | -           | Nhóm đơn (VD: "Liệu trình", "Sản phẩm")                    |
| source\_name      | string | -           | Nguồn đơn hàng (VD: "Offline", "Online")                   |
| branch\_name      | string | -           | Tên chi nhánh                                              |
| branch\_code      | string | -           | Mã chi nhánh                                               |
| created\_by\_id   | int    | -           | ID nhân viên tạo đơn bên đối tác                           |
| created\_by\_name | string | -           | Tên nhân viên tạo đơn                                      |
| contact           | object | ✅           | Thông tin khách hàng (xem bên dưới)                        |
| items             | array  | -           | Danh sách sản phẩm/dịch vụ (xem bên dưới)                  |
| created\_at       | string | -           | Ngày tạo — ISO 8601                                        |
| updated\_at       | string | -           | Ngày cập nhật — ISO 8601                                   |

**data.contact**

| Field | Type         | Required | Mô tả                     |
| ----- | ------------ | -------- | ------------------------- |
| id    | int          | ✅        | ID khách hàng bên đối tác |
| phone | string       | ✅\*      | Số điện thoại             |
| name  | string       | -        | Họ tên                    |
| email | string\|null | -        | Email                     |

**data.items\[]**

Hệ thống tự tìm/tạo sản phẩm theo {type}\_{product\_id} - third-party không cần biết ID sản phẩm bên CDP.

| Field                 | Type           | Required | Mô tả                                                                                                                                                           |
| --------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| line\_item\_id        | string         | ✅        | Unique ID của item trong đơn (VD: "treatment\_147411", "product\_101141")                                                                                       |
| product\_id           | int/string     | ✅        | ID sản phẩm/dịch vụ bên đối tác                                                                                                                                 |
| title                 | string         | ✅        | Tên sản phẩm/dịch vụ                                                                                                                                            |
| sku                   | string         | -        | Mã SKU                                                                                                                                                          |
| barcode               | string         | -        | Barcode                                                                                                                                                         |
| variant\_title        | string         | -        | Tên biến thể                                                                                                                                                    |
| type                  | string         | -        | "product" / "service" / "service\_card" / "treatment"                                                                                                           |
| price                 | number         | -        | <p>Giá bán của item</p><p>(Đơn giá, không nhân với số lượng)</p>                                                                                                |
| price\_original       | number         | -        | Giá gốc trước giảm giá                                                                                                                                          |
| quantity              | int            | -        | Số lượng                                                                                                                                                        |
| total\_discount       | number         | -        | Tổng số tiền giảm giá của item                                                                                                                                  |
| line\_item\_status    | int            | -        | 0 = bình thường, 1 = đã hoàn trả                                                                                                                                |
| lifecycle\_expire     | string         | -        | Ngày hết hạn — YYYY-MM-DD (dùng cho service/thẻ)                                                                                                                |
| lifecycle             | int            | -        | Số ngày hiệu lực                                                                                                                                                |
| image                 | string         | -        | URL ảnh sản phẩm                                                                                                                                                |
| product\_category     | string         | -        | Tên danh mục sản phẩm                                                                                                                                           |
| product\_category\_id | int            | -        | ID danh mục bên đối tác                                                                                                                                         |
| product\_attribute    | object\|string | -        | Thuộc tính mở rộng (JSON hoặc string)                                                                                                                           |
| provider              | object\|null   | -        | <p>Bác sĩ hiện dịch vụ trên item này.</p><p><br></p><p>→ CDP tự lookup/insert vào bảng `Doitac_providers`, gán `provider_id` cho order item (xem bên dưới).</p> |

#### data.items\[].provider

{% hint style="info" %}
Lưu ý:

* Lookup theo thứ tự: \`erp\_id\` → \`phone\`. Nếu không khớp cả 2, INSERT mới (yêu cầu phải có \`id\`).
* Khi item đã có provider mà payload mới không gửi \`provider\` → giữ nguyên \`provider\_id\` cũ (không clear).<br>
  {% endhint %}

#### Ví dụ mảng body request hợp lệ

```
{
  "object_type": "order",
  "object_id": 38778,
  "action": "create",
  "data": {
    "id": 38778,
    "code": "ĐH-20260417-00003",
    "order_date": "2026-04-17T09:12:47",
    "status": "completed",
    "payment_status": "completed",
    "subtotal": 100300,
    "total": 100300,
    "discount": 0,
    "discount_code": "VOUCHER2026",
    "note": "Khách sử dụng liệu trình DX 10'",
    "source_name": "Offline",
    "branch_code": "QGV",
    "branch_name": "Gò Vấp",
    "order_group": "Liệu trình",
    "created_by_id": 52,
    "created_by_name": "NGUYỄN HỒNG DIỄM",
    "contact": {
      "id": 56754,
      "phone": "0848599778",
      "email": null,
      "name": "TRẦN THỊ NGỌC THƠ"
    },
    "items": [
      {
        "line_item_id": "treatment_147411",
        "product_id": 28,
        "title": "DX (10')",
        "sku": "SVC-00028",
        "barcode": null,
        "variant_title": "DX (10')",
        "type": "treatment",
        "price": 5100,
        "price_original": 150000,
        "total_discount": 0,
        "quantity": 1,
        "line_item_status": 0,
        "lifecycle_expire": null,
        "lifecycle": null,
        "image": null,
        "product_category": "Vật lý trị liệu",
        "product_category_id": 3,
        "product_attribute": null,
        "provider": {
          "id": 56754,
          "phone": "0848599778",
          "email": null,
          "name": "TRẦN THỊ NGỌC THƠ"
        }
      },
      {
        "line_item_id": "product_101141",
        "product_id": 101141,
        "title": "CANDINO-Q-G-Da",
        "sku": "C4618/1",
        "barcode": "213331231320251862",
        "variant_title": "CANDINO-Q-G-Da",
        "type": "product",
        "price": 4725000,
        "price_original": 6750000,
        "total_discount": 2025000,
        "quantity": 1,
        "line_item_status": 0,
        "lifecycle_expire": "2028-04-17",
        "lifecycle": 730,
        "image": null,
        "product_category": "Đồng hồ",
        "product_category_id": 5,
        "product_attribute": null,
        "provider": {
          "id": 60100,
          "phone": "0901234567",
          "email": "kts@example.com",
          "name": "LÊ VĂN KIỆT"
        }
      }
    ],
    "created_at": "2026-04-17T09:12:47",
    "updated_at": "2026-04-17T09:12:47"
  },
  "timestamp": "2026-04-17T03:12:54"
}
```

### 3. Deal (Cơ hội bán hàng)

Pipeline và Stage của deal được cấu hình sẵn ở phía CDP — third-party không cần gửi pipeline\_id / stage\_id.

→ Sử dụng để lưu dữ liệu cơ hội bán hàng (tư vấn dịch vụ/ sản phẩm cho KH tiềm năng/ up sell/ cross sell)

#### data object

| Field                   | Type         | Required | Mô tả                                                                                                                                                                          |
| ----------------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id                      | int          | ✅        | ID deal bên đối tác — Unique key                                                                                                                                               |
| code                    | string       | ✅        | Mã deal (VD: "DEAL-28910745-207")                                                                                                                                              |
| name                    | string       | ✅        | Tên deal                                                                                                                                                                       |
| description             | string       | -        | Mô tả                                                                                                                                                                          |
| priority                | string       | -        | "high" / "medium" / "low"                                                                                                                                                      |
| source\_name            | string       | -        | Nguồn deal (VD: "Offline", "Online")                                                                                                                                           |
| revenue                 | number       | -        | Doanh thu dự kiến                                                                                                                                                              |
| cost                    | number       | -        | Chi phí                                                                                                                                                                        |
| extra\_charges          | number       | -        | Phí phát sinh                                                                                                                                                                  |
| discount                | number       | -        | Giảm giá                                                                                                                                                                       |
| due\_date               | string       | -        | Hạn xử lý — ISO 8601                                                                                                                                                           |
| is\_locked              | bool         | -        | Deal bị khoá                                                                                                                                                                   |
| is\_interaction\_active | bool         | -        | <p>Đánh dấu deal còn hiệu lực hay đã hết hiệu lực.</p><p>Mặc định giá trị = true (tương ứng hiệu lực) khi tạo mới</p>                                                          |
| stage                   | object\|null | -        | <p>Stage của cơ hội → Ưu tiên hơn `deal_default_stage` ở config plugin;</p><p><br></p><p>→ CDP tự lookup/insert theo `source_integration` + pipeline=</p><p>(xem bên dưới)</p> |
| user                    | object\|null | -        | Nhân viên phụ trách (xem bên dưới)                                                                                                                                             |
| customer                | object       | ✅        | Thông tin khách hàng (xem bên dưới)                                                                                                                                            |
| meta\_data              | object       | -        | Dữ liệu mở rộng (xem bên dưới)                                                                                                                                                 |
| created\_at             | string       | -        | Ngày tạo — ISO 8601                                                                                                                                                            |
| updated\_at             | string       | -        | Ngày cập nhật — ISO 8601                                                                                                                                                       |

**data.stage\[]**

| Field       | Type   | Mô tả                                                                                 |
| ----------- | ------ | ------------------------------------------------------------------------------------- |
| id          | int    | ID trạng thái cơ bội bên đối tác. CDP lưu thành \`source\_integration = 'erp\_{id}'\` |
| name        | string | Tên stage (VD: "Đã xác nhận"). Bắt buộc truyền khi tạo mới deal.                      |
| description | string | Mô tả chi tiết về trạng thái cơ hội.                                                  |

{% hint style="warning" %}
***Lưu ý:***

* *CDP tra Stage theo cặp \`(source\_integration = 'erp\_{id}', pipeline = deal\_default\_pipeline)\` — nếu chưa có sẽ INSERT mới (gắn vào pipeline mặc định, position = MAX hiện tại + 1).*
* *Nếu payload không gửi \`stage\` → fallback \`deal\_default\_stage\` từ config plugin.*
  {% endhint %}

**data.user**

| Field       | Type   | Mô tả                                   |
| ----------- | ------ | --------------------------------------- |
| id          | int    | ID nhân viên bên đối tác                |
| email       | string | Email — dùng để tìm nhân viên trong CDP |
| first\_name | string | Tên                                     |
| last\_name  | string | Họ                                      |
| full\_name  | string | Họ tên đầy đủ                           |
| avatar      | string | URL ảnh đại diện                        |
| mobile      | string | Số điện thoại                           |

{% hint style="warning" %}
*Lưu ý: Nếu không tìm thấy nhân viên theo email trong CDP → Dùng người phụ trách mặc định đã cấu hình; nếu vẫn không có → bỏ qua, không báo lỗi.*
{% endhint %}

**data.customer**

| Field | Type   | Required | Mô tả                     |
| ----- | ------ | -------- | ------------------------- |
| id    | int    | ✅        | ID khách hàng bên đối tác |
| phone | string | -        | Số điện thoại             |
| name  | string | -        | Họ tên                    |
| email | string | ✅\*      | Email                     |

**data.meta\_data**

| Field         | Type  | Mô tả                                   |
| ------------- | ----- | --------------------------------------- |
| enable\_items | bool  | true nếu có danh sách sản phẩm đính kèm |
| deal\_items   | array | Danh sách sản phẩm (xem bên dưới)       |

**data.meta\_data.deal\_items\[]**

Hệ thống tự tìm/tạo sản phẩm theo {type}\_{product\_id} — third-party không cần biết ID sản phẩm bên CDP.

| Field                 | Type       | Required | Mô tả                                                           |
| --------------------- | ---------- | -------- | --------------------------------------------------------------- |
| line\_item\_id        | string     | ✅        | Unique ID của item (VD: "treatment\_147411", "product\_101141") |
| product\_id           | int/string | ✅        | ID sản phẩm/dịch vụ bên đối tác                                 |
| title                 | string     | ✅        | Tên sản phẩm/dịch vụ                                            |
| sku                   | string     | -        | Mã SKU                                                          |
| barcode               | string     | -        | Barcode                                                         |
| variant\_title        | string     | -        | Tên biến thể                                                    |
| type                  | string     | -        | "product" / "service" / "service\_card" / "treatment"           |
| price                 | number     | -        | <p>Tổng giá của dòng item</p><p>= đơn giá × số lượng</p>        |
| price\_original       | number     | -        | Giá gốc trước giảm                                              |
| total\_discount       | number     | -        | Giảm giá của item                                               |
| quantity              | int        | -        | Số lượng                                                        |
| line\_item\_status    | int        | -        | 0 = bình thường, 1 = đã hoàn trả                                |
| lifecycle\_expire     | string     | -        | Ngày hết hạn — YYYY-MM-DD                                       |
| lifecycle             | int        | -        | Số ngày hiệu lực                                                |
| image                 | string     | -        | URL ảnh sản phẩm                                                |
| product\_category     | string     | -        | Tên danh mục sản phẩm                                           |
| product\_category\_id | int        | -        | ID danh mục bên đối tác                                         |
| product\_attribute    | object     | -        | Thuộc tính mở rộng                                              |

#### Ví dụ mảng body request hợp lệ

```
{
  "object_type": "deal",
  "object_id": 2,
  "action": "create",
  "data": {
    "id": 2,
    "code": "DEAL-28910745-207",
    "name": "Quyết tâm",
    "description": "KH đang về xin tiền",
    "user": {
      "id": 63,
      "email": "nguyennthihanh25@gmail.com",
      "first_name": "hanhnt",
      "last_name": "",
      "full_name": "hanhnt",
      "avatar": "",
      "mobile": ""
    },
    "revenue": null,
    "cost": null,
    "extra_charges": null,
    "discount": null,
    "priority": "high",
    "source_name": "Offline",
    "due_date": "2026-03-31T00:00:00",
    "is_locked": false,
    "stage": {
      "id": 3,
      "name": "Chăm sóc lại",
      "description": "KH đang cân nhắc hoặc hỏi ý gia đình"
    },
    "customer": {
      "id": 35560,
      "name": "Nguyễn Thanh Phương",
      "phone": "0888099800",
      "email": null
    },
    "meta_data": {
      "enable_items": true,
      "deal_items": [
        {
          "line_item_id": "treatment_147411",
          "product_id": 28,
          "title": "DX (10')",
          "sku": "SVC-00028",
          "barcode": null,
          "variant_title": "DX (10')",
          "type": "treatment",
          "price": 5100,
          "price_original": 150000,
           "total_discount": 0,
          "quantity": 1,
          "line_item_status": 0,
          "lifecycle_expire": null,
          "lifecycle": null,
          "image": null,
          "product_category": "Vật lý trị liệu",
          "product_category_id": 3,
          "product_attribute": null
        },
        {
          "line_item_id": "product_101141",
          "product_id": 101141,
          "title": "CANDINO-Q-G-Da",
          "sku": "C4618/1",
          "barcode": "213331231320251862",
          "variant_title": "CANDINO-Q-G-Da",
          "type": "product",
          "price": 4725000,
          "price_original": 6750000,
            "total_discount": 2025000,
          "quantity": 1,
          "line_item_status": 0,
          "lifecycle_expire": "2028-04-17",
          "lifecycle": 730,
          "image": null,
          "product_category": "Đồng hồ",
          "product_category_id": 5,
          "product_attribute": null
        }
      ]
    },
    "created_at": "2026-03-24T12:10:23",
    "updated_at": "2026-03-24T12:10:23"
  },
  "timestamp": "2026-03-24T05:10:37"
}
```

### 4. Ticket (Phiếu hỗ trợ)

Pipeline, Type và Category của ticket được cấu hình sẵn ở phía CDP — third-party không cần gửi các trường này.

→ Sử dụng để lưu các dữ liệu: Call Log/ Khiếu nại/ Phản hồi của KH

#### data object

| Field               | Type          | Required | Mô tả                                                                                                                                                                                                                        |
| ------------------- | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                  | int           | ✅        | ID ticket bên đối tác — Unique key                                                                                                                                                                                           |
| code                | string        | -        | Mã ticket (VD: "TICKET-84163710-249")                                                                                                                                                                                        |
| description         | string        | -        | Nội dung / mô tả ticket                                                                                                                                                                                                      |
| due\_date           | string\|null  | -        | Hạn xử lý — ISO 8601                                                                                                                                                                                                         |
| is\_locked          | bool          | -        | Ticket bị khoá                                                                                                                                                                                                               |
| is\_active          | bool          | -        | true = đang hoạt động, false = vô hiệu                                                                                                                                                                                       |
| user                | object\|null  | -        | Nhân viên phụ trách (xem bên dưới)                                                                                                                                                                                           |
| customer            | object        | ✅        | Thông tin khách hàng (xem bên dưới)                                                                                                                                                                                          |
| meta\_data          | object        | -        | Dữ liệu mở rộng (xem bên dưới)                                                                                                                                                                                               |
| ticket\_source      | object\|null  | -        | Nguồn ticket (object)                                                                                                                                                                                                        |
| ticket\_status      | string\| null | -        | <p>Tên trạng thái ticket</p><p>(VD: Đang xử lý, Hoàn thành)</p><p>→ Ưu tiên hơn cấu hình ở config plugin; CDP tự lookup TicketConfig type='status' theo tên; nếu chưa có sẽ tạo mới và chỉ ghi nhận khi khởi tại ticket.</p> |
| stakeholder\_id     | int\|null     | -        | ID stakeholder                                                                                                                                                                                                               |
| stakeholder\_source | any           | -        | Nguồn stakeholder                                                                                                                                                                                                            |
| created\_at         | string        | -        | Ngày tạo — ISO 8601                                                                                                                                                                                                          |
| updated\_at         | string        | -        | Ngày cập nhật — ISO 8601                                                                                                                                                                                                     |
| created\_by         | int           | -        | ID người tạo bên đối tác                                                                                                                                                                                                     |
| updated\_by         | int           | -        | ID người cập nhật bên đối tác                                                                                                                                                                                                |
| ticket\_type        | string        | ✅        | Loại ticket                                                                                                                                                                                                                  |
| ticket\_subtype     | string        | ✅        | Phân loại ticket                                                                                                                                                                                                             |

{% hint style="warning" %}
*Lưu ý: Type và SubType được ERP truyền qua \`ticket\_type\` / \`ticket\_subtype\`; CDP tự tìm hoặc tạo mới nếu chưa tồn tại. Nếu không gửi, hệ thống tự động fallback về cấu hình mặc định trong plugin.*
{% endhint %}

#### data.user

| Field       | Type   | Mô tả                                   |
| ----------- | ------ | --------------------------------------- |
| id          | int    | ID nhân viên bên đối tác                |
| email       | string | Email — dùng để tìm nhân viên trong CDP |
| first\_name | string | Tên                                     |
| last\_name  | string | Họ                                      |
| full\_name  | string | Họ tên đầy đủ                           |
| avatar      | string | URL ảnh đại diện                        |
| mobile      | string | Số điện thoại                           |

(\*Lưu ý: Nếu không tìm thấy nhân viên theo email trong CDP, thông tin sẽ được bỏ qua mà không báo lỗi.)

<br>

**data.customer**

| Field   | Type         | Required | Mô tả                     |
| ------- | ------------ | -------- | ------------------------- |
| id      | int          | ✅        | ID khách hàng bên đối tác |
| phone   | string       | ✅\*      | Số điện thoại             |
| name    | string       | -        | Họ tên                    |
| email   | string\|null | -        | Email                     |
| address | string\|null | -        | Địa chỉ                   |

#### data.meta\_data

| Field         | Type  | Mô tả                                   |
| ------------- | ----- | --------------------------------------- |
| enable\_items | bool  | true nếu có danh sách sản phẩm đính kèm |
| ticket\_items | array | Danh sách sản phẩm (xem bên dưới)       |

**data.meta\_data.ticket\_items\[]**

Hệ thống tự tìm/tạo sản phẩm theo {type}\_{product\_id} — đối tác không cần biết ID sản phẩm bên CDP.

| Field                 | Type           | Required | Mô tả                                                       |
| --------------------- | -------------- | -------- | ----------------------------------------------------------- |
| line\_item\_id        | string         | ✅        | Unique ID của item (VD: "treatment\_28", "product\_101141") |
| product\_id           | int/string     | ✅        | ID sản phẩm/dịch vụ bên đối tác                             |
| title                 | string         | ✅        | Tên sản phẩm/dịch vụ                                        |
| sku                   | string         | -        | Mã SKU                                                      |
| barcode               | string         | -        | Barcode                                                     |
| variant\_title        | string         | -        | Tên biến thể                                                |
| type                  | string         | -        | "product" / "service" / "service\_card" / "treatment"       |
| price                 | number         | -        | Tổng giá của dòng item (= đơn giá × số lượng)               |
| price\_original       | number         | -        | Giá gốc trước giảm                                          |
| price\_promotion      | number         | -        | Giá khuyến mãi                                              |
| total\_discount       | number         | -        | Giảm giá của item                                           |
| quantity              | int            | -        | Số lượng                                                    |
| line\_item\_status    | int            | -        | 0 = bình thường, 1 = đã hoàn trả                            |
| lifecycle\_expire     | string         | -        | Ngày hết hạn — YYYY-MM-DD                                   |
| lifecycle             | int            | -        | Số ngày hiệu lực                                            |
| image                 | string         | -        | URL ảnh sản phẩm                                            |
| product\_category     | string         | -        | Tên danh mục sản phẩm                                       |
| product\_category\_id | int            | -        | ID danh mục bên đối tác                                     |
| product\_attribute    | object\|string | -        | Thuộc tính mở rộng                                          |

&#x20;

#### Ví dụ

```
{
  "object_type": "ticket",
  "object_id": 23,
  "action": "create",
  "data": {
    "id": 23,
    "code": "TICKET-84163710-249",
    "description": "Tư vấn thuốc sau điều trị",
    "priority": "medium",
    "source_name": "",
    "due_date": null,
    "is_locked": false,
    "ticket_subtype": “Lỗi”,
    "ticket_type": “Hỏng máy”,
    "meta_data": {
      "enable_items": true,
      "ticket_items": [
        {
          "line_item_id": "treatment_28",
          "product_id": 28,
          "title": "DX (10')",
          "sku": "SVC-00028",
          "barcode": null,
          "variant_title": "DX (10')",
          "type": "treatment",
          "price": 5100,
          "price_original": 150000,
            "total_discount": 0,
          "quantity": 1,
          "line_item_status": 0,
          "lifecycle_expire": null,
          "lifecycle": null,
          "image": null,
          "product_category": "Vật lý trị liệu",
          "product_category_id": 3,
          "product_attribute": null
        }
      ]
    },
    "stakeholder_id": null,
    "stakeholder_source": null,
    "is_active": true,
    "user": {
      "id": 63,
      "email": "nguyennthihanh25@gmail.com",
      "first_name": "hanhnt",
      "last_name": "",
      "full_name": "hanhnt",
      "avatar": "",
      "mobile": ""
    },
    "customer": {
      "id": 4210,
      "name": "Trang Trần Ngọc",
      "phone": "0373381232",
      "email": "trangtn@hub-js.com",
      "address": "125 Dương Quảng Hàm"
    },
    "ticket_source": "Hotline",
    "ticket_status": "Đang xử lý",
    "created_at": "2026-05-04T15:43:27.110768",
    "updated_at": "2026-05-04T15:43:27.110787",
    "created_by": 1,
    "updated_by": 1
  },
  "timestamp": "2026-05-04T08:43:28.503380"
}
```

### 5. Hành động (action)

| Giá trị | Mô tả                                                                                |
| ------- | ------------------------------------------------------------------------------------ |
| create  | Upsert: Tạo mới hoặc cập nhật nếu đã tồn tại.                                        |
| update  | Upsert: Cập nhật hoặc tạo mới nếu chưa tồn tại.                                      |
| delete  | Bỏ qua (CDP không thực hiện xóa dữ liệu theo yêu cầu từ hệ thống bên ngoài gửi vào). |

<br>
