Tích hợp AntBuddy
1. Tổng quan
INFO: Toàn bộ API từ phía Rạng Đông CRM sử dụng method
POST
1.1. Thông tin chung
Base URL:
1.2. Authentication
Phía Rạng Đông sẽ cung cấp Service Account. Service Account bao gồm code và password.
- Dev: code / password
- Prod: code / password
TODO: Rạng Đông cung cấp code/password
Dev:code/passwordProd:code/password
AntBuddyAnt gọi vào API /rpc/portal/service-profile/login để lấy JWT.
{
"code": "string",
"password": "string"
}
Response trả về sẽ có dạng:Response:
{
"token": "string",
"expiredTime": "0000-00-00T00:00:00"
}
Thời hạn của JWT là 12 tiếng (43200 giây)
2. Customer
2.1. Luồng xử lý
- Khi Agent tạo/sửa thông tin khách hàng trên Ant, Ant sẽ gọi webhook để đồng bộ dữ liệu về CRM
- Khi Agent sửa thông tin khách hàng trên CRM, CRM gọi api cập nhật khách hàng trên Ant
2.2. API
2.2.0. Map thông tin Ant <-> CRM
- Địa chỉ: Ant (addresses) <-> CRM (Customer)
- city = provinceId
- state = districtId
- wards = wardId
- street = address
- SĐT: Ant (phones) <-> CRM (CustomerPhone)
- type = phoneTypeId + phoneType.name (map theo PhoneType)
- value = phone
[
{
"phoneTypeId": 0,
"phoneType": {
"name": "string"
},
"phone": "0123456789"
}
]
[
{
"phoneTypeId": 0,
"phoneType": {
"name": "string"
},
"phone": "0123456789"
}
]
Bảng enum PhoneType
| ID | Code | Name |
|---|---|---|
| 1 | MOBILE | Di động |
| 2 | TELEPHONE | Cố định |
- Email: Ant (emails) <-> CRM (customerEmails)
- type = emailTypeId + emailType.name (map theo EmailType)
- value = email
[
{
"emailTypeId": 0,
"emailType": {
"name": "string"
},
"email": "customer@example.com"
}
]
Bảng enum EmailType
| ID | Code | Name |
|---|---|---|
| 1 | PERSONAL | Cá nhân |
| 2 | COMPANY | Công ty |
| 3 | OTHER | Khác |
2.2.1. Webhook đồng bộ khách hàng Ant -> CRM
API: /rpc/crm/ant/customer/webhook
| Field | Type | Description | Note |
|---|---|---|---|
| id | long | ID khách hàng (CRM) | Nếu create, id = 0 |
| codeDraft | string | ID khách hàng (Ant) | |
| name | string | Tên khách hàng | |
| sexId | string | Giới tính khách hàng | Map theo Gender |
| birthday | datetime | Sinh nhật khách hàng | ISO string |
| address | string | Địa chỉ khách hàng | Xem mục 2.2.0. |
| customerPhones | CustomerPhone[] | SDT khách hàng | Xem mục 2.2.0. |
| customerEmails | CustomerEmail[] | Email khách hàng | Xem mục 2.2.0. |
| customerTypeId | long | ID Loại khách hàng | Map theo CustomerType |
| appUserId | long | ID người phụ trách | |
| taxCode | string | MST khách hàng |
Bảng enum CustomerType
| ID | Code | Name |
|---|---|---|
| 1 | RETAIL | Khách hàng lẻ |
| 2 | COMPANY | Hệ thống đối tác CTDA |
| 3 | STORE | Khách hàng đại lý |
| 4 | MODEL | Khách hàng mô hình |
| 5 | WORKER | Khách hàng thầu thợ |
2.2.2. Đồng bộ khách hàng CRM -> Ant
API: https://apiring.antbuddy.com/contacts (PUT)
| Field | Type | Description | Note | CRM Note |
|---|---|---|---|---|
| customerId | string | ID khách hàng (Ant) | Map vào CodeDraft | |
| gender | string | Giới tính khách hàng | Map theo Gender | = sexId |
| dateOfBirth | string | Sinh nhật khách hàng | = birthday | |
| name | string | Tên khách hàng | = name | |
| addresses | object[] | Địa chỉ khách hàng | Xem mục 2.2.0. | |
| phones | object[] | SDT khách hàng | Xem mục 2.2.0. | |
| emails | object[] | Email khách hàng | Xem mục 2.2.0. | |
| crmCustomerId | long | ID khách hàng (CRM) | ||
| crmCustomerTypeId | long | ID Loại khách hàng (CRM) | Map theo CustomerType | |
| crmAppUserId | long | ID người phụ trách (CRM) | ||
| crmTaxCode | string | MST khách hàng (CRM) |
Bảng enum Gender
| ID | Ant ID | Code | Description |
|---|---|---|---|
| 1 | 0 | MALE | Nam |
| 2 | 1 | FEMALE | Nữ |
| 3 | 2 | OTHER | Khác |
3. Ticket
3.1. Khái niệm
- Ant Ticket tương ứng với CRM Issue
- CRM Ticket là luồng nội bộ, không liên quan đến Ant Ticket
3.2. Luồng xử lý
end
3.3. API
3.3.1. Webhook đồng bộ Ant -> CRM
API: /rpc/crm/ant/issue/webhook
| Field | Type | Description | Note |
|---|---|---|---|
| id | long | ID vấn đề | Nếu create, id = 0 |
| title | string | Tiêu đề | |
| description | string | Mô tả vấn đề | |
| issueStatusId | long | ID trạng thái | Map bảng IssueStatus |
| issueTypeId | long? | ID loại vấn đề | Map bảng IssueType |
| customerId | long? | ID khách hàng | Map bảng Customer |
| customerDraft | string | Tên KH nháp | |
| phoneNumberDraft | string | SĐT nháp | |
| antId | long | ID vấn đề (Ant) |
INFO: Nếu có
customerIdthì không cầncustomerDraftvàphoneNumberDraft
INFO: Bảng
IssueType,IssueStatus,TicketPriorityphía Rạng Đông sẽ cung cấp qua file excel/csv
3.3.2. Đồng bộ CRM -> Ant
API: https://apiring.antbuddy.com/tickets (POST)PUT)
| Field | Type | Description | Note | CRM Note |
|---|---|---|---|---|
| ticketId | string | ID vấn đề | ||
| title | string | Tiêu đề | ||
| summary | string | Mô tả | = description | |
| priority | string | Mức độ ưu tiên | Map bảng TicketPriority | = ticket.ticketPriority.name |
| status | string | Trạng thái | = issueStatus.name | |
| customerId | long? | ID khách hàng | Map bảng Customer |
|
| long | ID vấn đề (CRM) | |||
| crmTicketId | long | ID ticket (CRM) | ||
| crmAppUserId | long | ID GDV xử lý (CRM) | Map bảng AppUser | |
| crmIssueTypeId | long? | ID loại vấn đề (CRM) | Map bảng IssueType | |
| crmCustomerDraft | string | Tên KH nháp (CRM) | ||
| string | SĐT nháp (CRM) | |||
| crmCompletedAt | datetime | Thời điểm xử lý (CRM) |
4. Call Log
4.1. Webhook đồng bộ lịch sử cuộc gọi Ant -> CRM
API: /rpc/crm/ant/call-log/webhook
| Field | Type | Description | Note |
|---|---|---|---|
| callId | string | Mã định danh cuộc gọi | |
| phone | string | Số điện thoại khách hàng | |
| string | Email khách hàng | ||
| callFrom | string | Số gọi đi | |
| callTo | string | Số nhận cuộc gọi | |
| customerId | long? | ID khách hàng | |
| callTime | datetime | Thời điểm thực hiện cuộc gọi | |
| startAt | datetime? | Thời điểm bắt đầu cuộc gọi | |
| endAt | datetime? | Thời điểm kết thúc cuộc gọi | |
| duration | string | Thời lượng cuộc gọi | |
| callTypeId | long? | ID loại cuộc gọi | Map bảng CallType |
| callStatusId | long? | ID trạng thái cuộc gọi | Map bảng CallStatus |
| appUserId | long | ID nhân viên phụ trách | Map bảng AppUser |
| note | string | Ghi chú cuộc gọi | |
| recordUrl | string | Đường dẫn file ghi âm |
Bảng enum CallType
| ID | Code | Description |
|---|---|---|
| 1 | CALL AWAY | Cuộc gọi đi |
| 2 | CALL INCOMING | Cuộc gọi đến |
INFO: Rạng Đông không sử dụng cuộc gọi nội bộ
Bảng enum CallStatus
| ID | Code | Description |
|---|---|---|
| 1 | ANSWERED | Đã trả lời |
| 2 | NO ANSWER | Không trả lời |
| 3 | MISSED CALL | Cuộc gọi nhỡ |
| 4 | REJECTED CALL | Từ chối cuộc gọi |
4.2. Lấy file ghi âm
URL: Lấy từ recordUrl trong payload của webhook
TODO: Cần Ant làm rõ
- Thời hạn của URL
- Authentication như nào?