# Care X

> API cho máy chủ công ty thành viên gửi tin Zalo ZBS bằng Zalo App, OA và ZBS của chính doanh nghiệp.

Tích hợp mới dùng một profile key không hết hạn cho `/v1/accounts` và `/v1/accounts/{accountId}/*`.
Key có phạm vi `all` (mặc định, gồm account tham gia/tạo sau này) hoặc `selected` (một/nhiều account, không tạo account mới).
Mỗi request kiểm tra trạng thái key/profile, phạm vi account và membership/role hiện tại; quyền Admin lúc cấp key không được giữ lại.
Đổi phạm vi cần phiên Dashboard và xác thực lại, không dùng machine key để tự nâng quyền. Không chọn scopes nghiệp vụ hay hạn dùng.

Ứng dụng công ty nhận App ID/App Secret/access-refresh token; máy chủ gọi API cấu hình Zalo, tạo/tải media/gửi duyệt/đồng bộ mẫu,
quản lý webhook và gửi/đọc tin bằng cùng key. Một account là một tenant và một OA. API nghiệp vụ cần query
`environment=development|live`; API cấu hình không cần query này. Secrets được mã hóa, không trả lại qua API đọc.
Website gọi qua máy chủ công ty; CORS allowlist nằm ở từng account và không thay thế xác thực. Gửi tin cần `template_id`
và `Idempotency-Key`; không tự gửi lại khi kết quả dispatch không rõ.

`contact_id` là mã khách ổn định riêng trong account, có cột/index trong notifications; giữ nguyên khi đổi SĐT hoặc dùng hash.
Gửi `recipient:{contact_id,phone}` hoặc `{contact_id,phone_hash}`; không tự gộp khách theo số/hash.
Mã khách của công ty ánh xạ qua `/contacts/external/{namespace}/{externalId}`, lưu `id` trả về làm contact_id.

Gửi tin hoặc từng item batch hỗ trợ `schedule_at` (ISO datetime có offset) để hẹn tương lai, trạng thái `scheduled`.
`expires_at` là hạn chót, mặc định 24 giờ sau lịch; không đặt hoặc đặt giờ đã qua dùng giờ hợp lệ sớm nhất từ hiện tại. Hủy/đổi lịch dùng cancel/replace
trước dispatch; lịch là thời điểm được phép bắt đầu gửi, không bảo đảm giờ nhận trên máy.
Cron/quét khách thuộc phần mềm công ty: sinh nhật hẹn 07:00; nhắc hẹn đặt schedule_at trước hẹn 30 phút và
expires_at bằng giờ hẹn. Worker dành năng lực riêng cho tin gửi ngay/tin hết hạn trong một giờ sau lịch,
và lịch hàng loạt. Mục tiêu sinh nhật xử lý sang Zalo trong 30 phút không tự đặt expiry lúc 07:30.
Chính sách giờ Zalo dùng chung toàn hệ thống; account không có setting giờ. Theo thông báo ngày 01/10/2026,
dự kiến từ 15/10/2026: Tag 1 gửi 24/24; Tag 2/3 gửi [07:00,22:00) giờ Việt Nam, cho cả SĐT/hash và UID.
Trước ngày hiệu lực vẫn gửi 24/24. Tag lấy từ mẫu Zalo đã đồng bộ, không từ purpose; tag chưa rõ dùng khung giới hạn.
Lịch ban đêm về 21:00 trước đó nếu chưa qua, nếu đã qua thì 07:00 kế tiếp sau lịch yêu cầu. Response scheduled_at là lịch hiệu lực.
Worker kiểm tra lại chính sách, expiry, quyền profile/key/range/membership và event_at lúc gửi; không tự resend unknown.
Vận hành cấu hình ZALO_SENDING_POLICY đồng nhất trên API/worker; khách không override. Chi tiết và nguồn Zalo ở mục 5.7 agent guide.

Hết quota Zalo: giữ tin cùng phạm vi OA/mẫu/người nhận và môi trường; ngày chờ ngày sau, tháng chờ tháng sau,
trong giờ cho phép nếu còn hạn. SĐT/hashphone chung phạm vi, UID riêng; hạn mức hậu mãi không chặn Tag 1/2.
Sự kiện notification.blocked vì quota có retry_at. Thiếu số dư/thanh toán ZBS (-115/-137) tạm ngưng live;
doanh nghiệp khắc phục rồi resume thủ công. Lỗi token cũng cần kết nối lại OA rồi chủ động gọi
POST /v1/accounts/{accountId}/zalo/resume; reconnect/health check không tự mở gửi. Resume cần Owner/Admin hiện tại,
body phone/template_id/template_data và Idempotency-Key. Kiểm tra App/Secret, token/OA, mẫu/giờ/quota rồi gửi một tin live tính phí; chỉ Zalo accepted và quyền/cấu hình còn đúng mới mở gửi. Cùng key/body trả kết quả đã lưu; 202 in_progress; unknown không resend. Lỗi tái diễn đình chỉ lại. Chi tiết mục 4–5 agent guide.

Bảo vệ lỗi bất thường: mặc định 5 tin live khác nhau lỗi chưa phân loại/unknown/lỗi provider trước gửi trong 10 phút
không có accepted mới hơn sẽ ngắt account; lỗi người nhận/mẫu/quota, điều kiện nội bộ và development không tính.
Retries cùng tin tính một lần; accepted xóa chuỗi khi đang ready. API cause/reason repeated_provider_failures,
suspension.failures có count/threshold/window_seconds/first_failure_at/last_failure_at/last_error.
Counter lưu database, không mất khi restart; không tự mở gửi. Verified resume thành công xóa chuỗi,
phản hồi cũ không cộng lại; failed/unknown không resend. Ngưỡng dùng chung ZALO_SEND_FAILURE_THRESHOLD=5,
ZALO_SEND_FAILURE_WINDOW_SECONDS=600 trên API/worker. Chi tiết mục 5.1 và 7.5 agent guide.

Báo cáo theo account: `/reports/summary`, `/reports/daily` (chart, có ngày trống, giờ Việt Nam hoặc UTC),
`/reports/details` (đối soát từng tin và chi phí). Chọn `date_field=accepted_at|scheduled_at|dispatched_at|delivered_at`,
lọc `from/to`, `phone`, `contact_id`, `template_id`, `status`; mặc định 30 ngày, tối đa 90 ngày.
Các danh sách API dùng `limit` (mặc định 50, tối đa 100), cursor ký gắn tài nguyên/account/môi trường/bộ lọc,
`next_cursor` và `has_more`. Events giữ dạng feed riêng (100/200 mục, retention 90 ngày). Mọi trang vẫn kiểm tra quyền hiện tại.

## Docs

- [Hướng dẫn tích hợp cho AI agent](https://carex.io.vn/developers/agent-guide.md): luồng profile key, phạm vi account, cấu hình Zalo/mẫu, endpoint/payload, webhook, lỗi và ví dụ; tương thích account key cũ ở mục 10.
- [Tài liệu API tiếng Việt](https://carex.io.vn/developers): bắt đầu nhanh cho máy chủ công ty với một profile key.
- [OpenAPI 3.1](https://api.carex.io.vn/v1/openapi.json): schema sinh từ API đang chạy, gồm profile routes và legacy routes; dùng security profileApiKey cho tích hợp mới.