Quy ước chung

Trang này tổng hợp các quy chuẩn kỹ thuật bắt buộc khi làm việc với API của ODS AI Contact Center, giúp kỹ sư tích hợp xây dựng ứng dụng đồng bộ, chính xác và tránh các lỗi phổ biến.

1. Base URL & Môi trường

Hệ thống phân tách domain chính thức theo từng cụm dịch vụ:

2. Giao thức, Phương thức & Headers

• Phương thức HTTP: 100% endpoint của ODS đều sử dụng POST, kể cả các tác vụ tra cứu danh sách (GetCallHistory, GetAudioList) hoặc tác vụ xóa (DeleteExtension, DeleteCampaign, DeleteAudio). Không sử dụng GET, PUT hay DELETE.
• Định dạng dữ liệu: Toàn bộ tham số gửi lên được đóng gói trong JSON Body.
• Request Headers bắt buộc:

POST /api/CloudFone/AutoCall HTTP/1.1
Host: api.ods.vn
Content-Type: application/json; charset=utf-8

3. Quy ước đặt tên trường (Casing) & Kiểu dữ liệu

Casing không đồng nhất giữa các nhóm API

Do hệ thống được phát triển qua nhiều giai đoạn, quy ước đặt tên thuộc tính JSON có sự khác biệt giữa các nhóm endpoint:

• Request Parameters: Hầu hết sử dụng PascalCase (ví dụ: ServiceName, ServiceCode, AuthUser, AuthKey, PhoneNumber, DateStart, DateEnd, PageIndex, PageSize). Tuy nhiên, một số endpoint sử dụng chữ thường (ví dụ: password, name trong API AddExtension).
• Response Properties:
  • Nhóm khởi tạo/CRUD: Thường trả về result, message, keySearch, idPhoneBook.
  • Mảng dữ liệu lịch sử cuộc gọi (GetCallHistory): Thuộc tính bản ghi bên trong dùng camelCase hoặc không dấu tiếng Việt (ví dụ: stt, key, ngayGoi, soGoiDen, dauSo, soNhan, trangThai, tongThoiGianGoi, thoiGianThucGoi, linkFile, typecall).

4. Cấu trúc phản hồi (Response Envelope)

Hệ thống không dùng chung một schema cho toàn bộ các API mà phân thành 2 dạng envelope chính có bằng chứng trong tài liệu nguồn:

Dạng 1: Phản hồi thực thi tác vụ (Action Response)

Áp dụng cho Click-to-Call, thêm/xóa máy nhánh, khởi tạo chiến dịch:

{
  "result": "success",
  "message": "GỌI TỰ ĐỘNG THÀNH CÔNG",
  "keySearch": "1b38fbda-4b7e-41a2-9bc3-7a28e9324a1b"
}

Hoặc trả về ID bản ghi mới tạo:

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

Dạng 2: Phản hồi danh sách phân trang (List Response)

Áp dụng cho tra cứu lịch sử cuộc gọi (GetCallHistory, GetCallLogs) và danh sách nhóm liên hệ:

{
  "result": "success",
  "message": "",
  "total": 415,
  "data": [
    {
      "stt": 1,
      "key": "1610039549.118173-9100(Nhóm)",
      "ngayGoi": "2026-10-15T08:30:00",
      "soGoiDen": "0900000000",
      "dauSo": "02873007788",
      "soNhan": "101",
      "trangThai": "ANSWERED",
      "tongThoiGianGoi": "02:15",
      "thoiGianThucGoi": "135",
      "linkFile": "https://api.ods.vn/recordings/call-123.mp3"
    }
  ]
}

• result: Trạng thái xử lý ("success" hoặc "failed").
• total: Tổng số bản ghi thỏa điều kiện lọc trong database (dùng để tính toán tổng số trang phía client).
• data: Mảng danh sách bản ghi thuộc trang hiện tại.

5. Quy tắc phân trang (Pagination)

Áp dụng cho các endpoint tra cứu dữ liệu (GetCallHistory, GetCallLogs, danh sách danh bạ):

6. Định dạng ngày tháng & Bẫy biên thời gian (DateEnd)

Trong các API lọc theo thời gian (DateStart, DateEnd):

• Định dạng nhận diện: Chuỗi YYYY-MM-DD hoặc YYYY-MM-DD HH:mm:ss (ví dụ: "2026-10-15 08:30:00").
• Múi giờ (Timezone): Mặc định tính theo giờ Việt Nam ICT (UTC+7). Tránh gửi chuỗi ISO có hậu tố Z (UTC) nếu chưa chuyển đổi giờ địa phương.

7. Phân biệt KeySearch với Idempotency Key

Trong các API khởi tạo cuộc gọi (Click-to-Call V1, Click-to-Call V2), tham số KeySearch có vai trò quan trọng nhưng thường bị hiểu nhầm:

8. Đối chiếu lỗi HTTP với lỗi nghiệp vụ

Khi tích hợp với ODS, lập trình viên cần xử lý 2 tầng lỗi riêng biệt:

Tầng 1: Lỗi giao thức HTTP (Network & Transport)

• 400 Bad Request: Payload JSON bị lỗi cú pháp hoặc thiếu tham số bắt buộc.
• 404 Not Found: Sai đường dẫn URL endpoint.
• 500 / 502 / 504: Máy chủ ODS gặp sự cố hoặc gateway timeout.

Tầng 2: Lỗi nghiệp vụ (Business Logic Failure)

Lập trình viên bắt buộc phải kiểm tra thuộc tính result bên trong thân JSON phản hồi:

{
  "result": "failed",
  "message": "Sai thông tin AuthUser hoặc AuthKey!"
}

// Node.js 22+ (Backend / Server-side)
async function createClickToCall({ ext, phoneNumber, phoneName = '' }) {
  const credentials = {
    ServiceName: process.env.ODS_SERVICE_NAME,
    AuthUser: process.env.ODS_AUTH_USER,
    AuthKey: process.env.ODS_AUTH_KEY,
  };

  const missing = Object.entries(credentials)
    .filter(([, value]) => !value)
    .map(([name]) => name);

  if (missing.length > 0) {
    throw new Error(`Thiếu cấu hình bắt buộc: ${missing.join(', ')}`);
  }
  if (!ext || !phoneNumber) {
    throw new Error('ext và phoneNumber là bắt buộc');
  }

  const response = await fetch('https://api.ods.vn/api/CloudFone/AutoCall', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      ...credentials,
      Ext: ext,
      PhoneNumber: phoneNumber,
      PhoneName: phoneName,
      Prefix: '0',
      KeySearch: crypto.randomUUID(),
    }),
  });

  if (!response.ok) {
    throw new Error(`Lỗi HTTP: ${response.status} ${response.statusText}`);
  }

  const data = await response.json();
  if (data.result !== 'success') {
    throw new Error(`Tổng đài từ chối: ${data.message ?? 'Không rõ nguyên nhân'}`);
  }

  return data;
}

// Không tự động retry hàm tạo cuộc gọi khi chưa xác định kết quả request trước.

Bài viết tiếp theo