Tạo máy nhánh (AddExtension)

API tạo mới tài khoản máy nhánh (extension) trên tổng đài PBX ODS, phục vụ cấp phát tự động từ HRM/CRM.

POSThttps://api.ods.vn/api/CloudFone/AddExtension

API AddExtension cho phép hệ thống HRM / CRM tự động khởi tạo tài khoản máy nhánh (extension) trên tổng đài ODS khi có nhân sự mới, thay vì phải cấu hình thủ công trên Portal.

Ứng dụng thực tế

Cấp số nội bộ tự động: Tự động sinh tài khoản thoại ngay khi hoàn tất thủ tục onboarding nhân sự.
Đàm thoại nội bộ & Tiếp nhận cuộc gọi: Máy nhánh sau khi tạo có thể gọi nội bộ miễn phí, tham gia nhóm trực (Ring Group / Queue) nhận cuộc gọi từ khách hàng.
Thực hiện cuộc gọi ra: Đóng vai trò là số máy nhánh điều khiển trong Click-to-Call V1 hoặc thoại qua Softphone/IP Phone.

Cơ chế hoạt động: API này thực hiện khởi tạo bản ghi tài khoản trên hệ thống tổng đài PBX. Để thực hiện hoặc nhận cuộc gọi, nhân sự sử dụng số máy nhánh Ext và mật khẩu password vừa tạo để đăng ký SIP trên thiết bị IP Phone, Softphone hoặc WebRTC.

Tham số request

Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả chi tiết
`ServiceCode`	string	Có	Mã dịch vụ tổng đài khi đăng ký tại ODS (ví dụ: `CF-BSXXXX`). Lưu ý: Endpoint này sử dụng `ServiceCode`, không dùng `ServiceName`.
`AuthUser`	string	Có	Mã tài khoản khách hàng do ODS cấp (ví dụ: `ODSXXXX`).
`AuthKey`	string	Có	Khóa bí mật API do ODS cấp để xác thực quyền quản trị.
`Ext`	string	Có	Số máy nhánh cần tạo (ví dụ: `1001`, `1997`). Dùng làm số gọi nội bộ và SIP Username. Ràng buộc: Độ dài phải nhỏ hơn 5 chữ số.
`password`	string	Có	Mật khẩu máy nhánh dùng để xác thực thiết bị SIP (độc lập với `AuthKey`). Ràng buộc: Tối thiểu 8 ký tự, gồm ít nhất 1 chữ hoa, 1 chữ thường, 1 số và 1 ký tự đặc biệt.
`name`	string	Có	Tên hiển thị của máy nhánh khi gọi nội bộ (Caller ID Name). Ràng buộc: Không chứa dấu tiếng Việt và không chứa ký tự đặc biệt (ví dụ: `NhanVien1`).

Ví dụ request

curl -X POST "https://api.ods.vn/api/CloudFone/AddExtension" \
  -H "Content-Type: application/json" \
  -d '{
    "ServiceCode": "CF-BSXXXX",
    "AuthUser": "YOUR_AUTH_USER",
    "AuthKey": "YOUR_AUTH_KEY",
    "Ext": "1001",
    "password": "Password@123",
    "name": "NhanVien1"
  }'

Response mẫu

{
  "result": "success",
  "message": "Thành công!"
}

Cấu trúc phản hồi

Trường	Kiểu dữ liệu	Mô tả
`result`	string	Trạng thái xử lý yêu cầu (`"success"` hoặc `"failed"`).
`message`	string	Thông báo kết quả chi tiết từ hệ thống tổng đài (ví dụ: `"Thành công!"`).

Lưu ý quan trọng

Ràng buộc số máy nhánh (Ext): Phải là chuỗi số có độ dài nhỏ hơn 5 chữ số.
Chính sách mật khẩu (password): Tối thiểu từ 8 ký tự trở lên, bắt buộc có đủ: chữ hoa (A-Z), chữ thường (a-z), chữ số (0-9) và ký tự đặc biệt (như @, #, $, !).
Tên hiển thị (name): Không chứa dấu tiếng Việt và không chứa ký tự đặc biệt.
Mã dịch vụ: Endpoint này dùng ServiceCode (không dùng ServiceName).
Đăng ký SIP: Sau khi tạo tài khoản thành công qua API, cần cấu hình thiết bị SIP (IP Phone, Softphone, WebRTC) với Ext và password thì máy nhánh mới có thể đàm thoại.

Tạo máy nhánh (AddExtension)

Ứng dụng thực tế

Tham số request

Cấu trúc phản hồi

Lưu ý quan trọng

Lỗi thường gặp và cách xử lý

Bài viết liên quan

Xóa máy nhánh (DeleteExtension)

Khởi tạo cuộc gọi Click-to-Call

Tạo máy nhánh (AddExtension)

Số máy nhánh không hợp lệ hoặc đã tồn tại

Mật khẩu không thỏa mãn chính sách bảo mật

Tên hiển thị chứa dấu hoặc ký tự đặc biệt

Sai thông tin xác thực hoặc sai ServiceCode

Xóa máy nhánh (DeleteExtension)

Khởi tạo cuộc gọi Click-to-Call