Tổng quan hệ thống & Tiêu chuẩn giao tiếp của VBot Open API

1. Giới thiệu (Introduction)

VBot Open API là giải pháp giao tiếp cốt lõi cung cấp hệ thống RESTful Endpoints, cho phép các nền tảng và phần mềm của bên thứ ba tích hợp sâu vào hệ sinh thái VBot. Thông qua bộ API này, doanh nghiệp có thể tự động hóa toàn diện các nghiệp vụ tổng đài bao gồm: quản lý nhân sự (thành viên), điều phối hotline, truy xuất dữ liệu cuộc gọi theo thời gian thực và vận hành các chiến dịch gọi tự động (Auto-Call Campaigns).

2. Cấu hình môi trường (Environment Configuration)

Để khởi tạo các request đến hệ thống VBot, mọi truy vấn đều phải tuân thủ các thông số kỹ thuật mạng và phương thức xác thực (Authentication) dưới đây:

Thuộc tính	Định dạng / Giá trị	Ghi chú
Base URL	`https://open-api-h01.vbot.vn/v3.0`	Không bao gồm dấu `/` ở cuối
Content-Type	`application/json`	Bắt buộc cho các request body
X-API-Key	`token-open-api`	Header xác thực bắt buộc để định danh dự án

3. Phân hệ chức năng (API Modules)

Tài liệu được chia thành các phân hệ nghiệp vụ độc lập, giúp lập trình viên dễ dàng tra cứu và tích hợp theo từng giai đoạn của dự án:

Quản lý thành viên (User & Account Management): Cung cấp các thao tác CRUD đối với thành viên dự án, cấp phát và quản lý thông tin tài khoản SDK/SIP.
Nhóm & Hotline (Routing & Hotline): Cấu hình định tuyến cuộc gọi, quản lý danh sách hotline và phân bổ nhóm nhân viên (Agents).
Lịch sử cuộc gọi (Call Logs & Records): Truy xuất siêu dữ liệu (metadata) của các phiên gọi, tra cứu CDR (Call Detail Record) và trích xuất file ghi âm.
Gọi tự động (Auto-Call / Campaign): Vận hành toàn trình các chiến dịch gọi tự động, gọi xác nhận (Voice OTP), quản lý trường dữ liệu tùy chỉnh (Custom Fields) và Template kịch bản IVR.
VBot SDK: Các API bổ trợ cho việc tích hợp SDK bao gồm sinh Token, đẩy Log hệ thống, đồng bộ thông tin và lịch sử cuộc gọi trên Client.
Tiện ích khác (Utilities & Webhooks): Theo dõi thống kê lưu lượng dự án, tích hợp hệ sinh thái OneSME và thiết lập Webhook nhận biến động SMS/Call.

4. Tiêu chuẩn dữ liệu trả về (Standard Response Format)

Để đảm bảo tính nhất quán trong quá trình phân tích dữ liệu (Parsing) tại phía Client, toàn bộ API của VBot đều trả về một cấu trúc JSON duy nhất (Response Envelope).

{
  "error": 0,
  "message": "success",
  "data": {
    // Payload chi tiết của từng API sẽ được đặt tại đây
  }
}

Chi tiết các tham số:

Tham số	Kiểu dữ liệu	Mô tả chi tiết
`error`	Integer	Mã định danh kết quả của Request. Giá trị `0` là thành công, khác `0` là có lỗi.
`message`	String	Thông điệp giải thích chi tiết trạng thái trả về (rất hữu ích cho việc Debug).
`data`	Any	Payload chứa dữ liệu thực tế. Kiểu dữ liệu (Object, Array, Null) phụ thuộc vào từng Endpoint.

Lưu ý quan trọng về phiên bản (Breaking Change): Kể từ phiên bản v3.0, Response không còn sử dụng trường status. Các hệ thống tích hợp vui lòng chuyển sang kiểm tra thuộc tính error để xác định trạng thái của vòng đời Request.

5. Bảng mã lỗi hệ thống (Error Codes)

Khi tham số error trả về giá trị khác 0, hệ thống đã từ chối xử lý hoặc gặp sự cố. Lập trình viên có thể dựa vào bảng mã HTTP/Custom Status dưới đây để có phương án xử lý (Retry/Alert):

Mã lỗi (`error`)	Ý nghĩa	Hướng xử lý đề xuất
-1	Sai tham số (Bad Request)	Kiểm tra lại Payload, định dạng dữ liệu hoặc các trường bắt buộc.
0	Thành công (Success)	Request hợp lệ, xử lý payload trong trường `data`.
401	Không có quyền truy cập	Kiểm tra lại tính hợp lệ và thời hạn của `X-API-Key`.
403	Không có quyền thực hiện	API Key đúng nhưng tài khoản không được cấp quyền cho hành động này.
404	Không tìm thấy tài nguyên	ID đối tượng (thành viên, chiến dịch, cuộc gọi...) không tồn tại.
409	Dữ liệu đã tồn tại (Conflict)	Bị trùng lặp dữ liệu (ví dụ: tạo số điện thoại đã tồn tại).
500	Lỗi hệ thống (Internal Error)	Lỗi từ phía Server VBot. Client nên thiết lập cơ chế Retry sau vài giây.

Backend