Quy ước chung

Base URL

Loại	URL
REST API	https://app.zorio.vn/api/
Webhook nhận (do bạn cấu hình)	URL của bạn

Tên miền truy cập được cấp riêng trong quá trình khởi tạo hệ thống (onboarding).

Header chuẩn

Tất cả request:

Authorization: Bearer <token>
Accept: application/json

Tất cả request có body:

Content-Type: application/json; charset=utf-8

Response shape

Single resource / action

{ "data": {} }

List (paginated)

{
  "current_page": 1,
  "data": [],
  "last_page": 5,
  "per_page": 50,
  "total": 234
}

Error

{
  "message": "Mô tả lỗi tóm tắt",
  "errors": { "field_name": ["Mô tả chi tiết"] }
}

Pagination

Query ?page=1&per_page=50 (mặc định 50, tối đa 200).

Timestamp & Timezone

Mọi datetime ở ISO 8601 với offset:

• UTC: 2026-06-30T03:30:45+00:00
• VN: 2026-06-30T10:30:45+07:00

Khi gửi request, chấp nhận cả định dạng có hoặc không có microseconds (.000000Z).

Status codes phổ biến

HTTP	Khi nào
200	OK
201	Created
202	Accepted (async)
400	Bad request
401 - Token thiếu, không hợp lệ hoặc đã hết hạn.
403 - Không đủ quyền truy cập.
404	Resource không tồn tại
409 - Conflict (ví dụ: dữ liệu trùng hoặc trạng thái không hợp lệ).
422 - Dữ liệu đầu vào không hợp lệ.
429 - Vượt quá giới hạn tốc độ (kèm header Retry-After).
500 - Lỗi máy chủ.

Phone number format

• Lưu trong DB: format E.164 không dấu + (vd 84987654321).
• Request body chấp nhận: cả 0987654321 lẫn 84987654321 — Hệ thống tự chuẩn hóa số điện thoại.. Response trả về theo đúng định dạng mà client đã gửi.

Recording URL

Ghi âm trả qua signed URL TTL 30 phút (HMAC SHA256). Client cần tải file trong vòng 30 phút. Sau khi hết hạn, hãy yêu cầu Signed URL mới thông qua endpoint /recording. qua endpoint /recording.