Skip to main content

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:

  • Dev: https://rdev.supa.vn
  • Prod: https://portal.rangdong.com.vn

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

Ant gọi API /rpc/portal/service-profile/login để lấy JWT.

{
    "code": "string",
    "password": "string"
}

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

  1. Địa chỉ: Ant (addresses) <-> CRM (Customer)
  • city = provinceId
  • state = districtId
  • wards = wardId
  • street = address
  1. SĐT: Ant (phones) <-> CRM (CustomerPhone)
  • type = phoneTypeId + phoneType.name (map theo PhoneType)
  • value = phone
[
    {
        "phoneTypeId": 0,
        "phoneType": {
            "name": "string"
        },
        "phone": "0123456789"
    }
]

Bảng enum PhoneType

ID Code Name
1 MOBILE Di động
2 TELEPHONE Cố định
  1. 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ý

sequenceDiagram
    Agent->>Ant: Tạo ticket
    Ant->>CRM: Tạo CRM Issue
    alt Không tạo CRM Ticket
      alt CRM xử lý
        CRM->>CRM: Xử lý/Đóng vấn đề
        CRM->>Ant: Đồng bộ
        Note left of CRM: ticketId = null
      else Ant xử lý
        Ant->>Ant: Xử lý/Đóng vấn đề
        Ant->>CRM: Đồng bộ
      end
    else Tạo CRM Ticket
      CRM->>CRM: Tạo CRM Ticket
      CRM->>Ant: Đồng bộ
      Note left of CRM: ticketId != null
      Ant->>Ant: Chặn xử lý/đóng trên Ant
      CRM->>CRM: Xử lý/Đóng ticket
      CRM->>Ant: Đồng bộ
    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ó customerId thì không cần customerDraft và phoneNumberDraft

INFO: Bảng IssueType, IssueStatus, TicketPriority phí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 (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
crmIssueId 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)
crmPhoneNumberDraft 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
email 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?
Back to top