API ReferenceBắt đầu
Xác thực API
Cơ chế xác thực tài khoản qua ServiceName, ServiceCode, AuthUser và AuthKey trên ODS AI Contact Center.
Khác với các hệ thống sử dụng HTTP Header (như Authorization: Bearer <token>), ODS AI Contact Center xác thực các yêu cầu REST API thông qua bộ tham số định danh được truyền trực tiếp trong phần thân (body) của mỗi HTTP POST request dưới định dạng JSON.
1. Bộ ba thông số xác thực REST API
Mỗi request gửi tới tổng đài ODS cần chứa 3 thông tin nhận diện do ODS cấp khi đăng ký dịch vụ:
| Tên tham số | Kiểu dữ liệu | Ý nghĩa | Quy ước tên trường |
|---|---|---|---|
ServiceName hoặc ServiceCode | string | Mã gói dịch vụ tổng đài (ví dụ: CF-BS00XXXXX hoặc CF-BSXXXX). | • Nhóm PBX (Click-to-Call, Lịch sử, Danh bạ): Dùng ServiceName• Nhóm Máy nhánh & toàn bộ Autocall: Dùng ServiceCode |
AuthUser | string | Mã khách hàng định danh tài khoản doanh nghiệp (ví dụ: CF000XXX hoặc ODSXXXX). | Dùng đồng nhất AuthUser trên toàn hệ thống |
AuthKey | string | Khóa bí mật API (chuỗi UUID/GUID cấp quyền truy cập tổng đài). | Dùng đồng nhất AuthKey trên toàn hệ thống |
Lưu ý khi truyền dữ liệu:
- Cả 3 thông số đều được gửi trong JSON Body của HTTP POST request. Tổng đài không nhận xác thực qua HTTP Header hay Query string.
- Khuyến nghị gọi REST API từ máy chủ Backend và lưu trữ
AuthKeytrong biến môi trường (.env), không để lộ tại client/trình duyệt web.
{
"ServiceName": "CF-BS00XXXXX",
"AuthUser": "CF000XXX",
"AuthKey": "eea8c834-f0d5-4ff5-91fc-xxxxxxxxxxxx",
"Ext": "9119",
"PhoneNumber": "0900000000"
}2. Phân biệt thông tin xác thực theo giao thức
Tùy thuộc vào phương thức kết nối, hệ thống sử dụng các thông tin bảo mật riêng biệt:
| Giao thức / Kênh kết nối | Áp dụng cho | Bộ thông số sử dụng | Ghi chú |
|---|---|---|---|
| REST API | CRM Backend ➔ ODS | AuthUser + AuthKey + ServiceName / ServiceCode | Xác thực các tác vụ gọi API quản trị và điều khiển cuộc gọi. |
| SIP / Softphone / WebRTC | Thiết bị đầu cuối & Trình duyệt | Ext (Số máy nhánh) + password (Mật khẩu máy nhánh) | Dùng để đăng ký tài khoản thoại (SIP REGISTER) trên IP Phone hoặc JsSIP. Không dùng AuthKey để đăng ký máy nhánh. |
| Webhook Popup | ODS ➔ CRM Receiver | ApiKey hoặc Secret Token cấu hình trên tổng đài | Gửi kèm trong payload Webhook để CRM xác thực request đến từ ODS. |
3. Cấu hình biến môi trường mẫu
Khai báo thông số tích hợp trong file .env trên máy chủ Backend của bạn:
# Cấu hình kết nối ODS AI Contact Center
ODS_PBX_URL="https://api.ods.vn"
ODS_AUTOCALL_URL="https://apiai.cloudfone.vn"
# Thông tin xác thực do ODS cấp
ODS_SERVICE_NAME="CF-BS00XXXXX"
ODS_SERVICE_CODE="CF-BSXXXX"
ODS_AUTH_USER="CF000XXX"
ODS_AUTH_KEY="eea8c834-f0d5-4ff5-91fc-xxxxxxxxxxxx"