Quy ước chung

#Envelope

Thành công:

{ "success": true, "data": { }, "pagination": { "limit": 50, "has_more": true, "next_before": 1760000000000 }, "request_id": "..." }

Lỗi:

{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Tham số body không hợp lệ", "details": [{ "path": "body.text", "message": "Tối đa 10000 ký tự" }] }, "request_id": "..." }

Mỗi response có header X-Request-Id: gửi kèm khi báo lỗi.

#Mã lỗi

#Phân trang

• Danh sách thường: ?limit=50&offset=0, đọc pagination.next_offset.
• Tin nhắn: mới → cũ, ?limit=50&before=<epoch ms>; trang sau dùng pagination.next_before. Tin cùng mốc thời gian có thể lặp ở ranh giới → khử trùng theo msg_id.

#Dữ liệu

• Thời gian: epoch mili giây.
• Tên trường: snake_case theo cột DB. Cột JSON (attachments, reactions, quote) đã được parse.
• Không trả cookie, session, mật khẩu, đường dẫn file trên máy.
• ID tài khoản = accounts.zalo_id (Facebook: Facebook ID; Telegram: ID tài khoản Telegram).

#Idempotency

Với POST, gửi header Idempotency-Key: <chuỗi duy nhất>. Gọi lại cùng key trong 24 giờ trả nguyên kết quả cũ (header Idempotent-Replayed: true) thay vì gửi tin lần hai. Lỗi tạm thời (409, 429, 5xx) không được lưu để bạn retry.

#Giới hạn

• Body JSON tối đa 10 MB, file upload tối đa 100 MB (đổi trong Cài đặt).
• Mặc định không giới hạn tốc độ. Bạn có thể đặt giới hạn cho từng key hoặc mặc định toàn cục.
• Lời gọi được xếp hàng tối đa N việc đồng thời (mặc định 4) để app không bị giật; request không bị từ chối vì hàng đợi.
• Gửi tin đi qua cùng hàng đợi gửi theo tài khoản như app để tài khoản Zalo không bị khoá do gửi dồn.