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 khi onboarding.

Header chuẩn

Mọi request:

Authorization: Bearer <token>
Accept: application/json

Mọi 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ó/không 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 / sai / expired
403	Thiếu permission
404	Resource không tồn tại
409	Conflict (duplicate / state machine vi phạm)
422	Validation lỗi
429	Rate limit hit (kèm Retry-After)
500	Server error

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 — backend tự normalize.
• Response trả về: format gốc client gửi lên (preserve).

Recording URL

Ghi âm trả qua signed URL TTL 30 phút (HMAC SHA256). Client download trong 30' — quá hạn phải request URL mới qua endpoint /recording.