# ZaPro

> ZaPro là API gửi tin Zalo (tin mẫu ZBS, trước gọi là ZNS) từ Zalo OA, cho lập trình viên Việt Nam. Gửi tin như gửi email bằng Resend: một API key, một lệnh POST. ZaPro tự làm mới token OA, giữ tin chăm sóc/quảng cáo ngoài 07:00–22:00, nhận webhook của Zalo thay bạn, báo lỗi bằng tiếng Việt.

Địa chỉ gốc: https://app.zapro.vn/v1. Xác thực: header "Authorization: Bearer zp_live_…". Body và phản hồi là JSON. Giới hạn 10 lệnh/giây mỗi key.

## Gửi tin

POST /v1/messages
{"oa": "<mã OA hoặc sandbox>", "to": "0901234567", "template": "<mã mẫu>", "data": {"<tham số>": "<giá trị>"}, "tracking_id": "<tùy chọn>", "scheduled_at": "<ISO 8601, tùy chọn>"}
Header tùy chọn: Idempotency-Key (chống gửi trùng).
Trả 202 với {"object":"message","id":"msg_…","status":"queued", ...}. Trạng thái: queued, scheduled, sending, sent, delivered, failed, canceled.
OA "sandbox" + mẫu "xac-nhan-lich-hen" (tham số ten, dich_vu, gio, ngay) để gửi thử tới số điện thoại của thành viên công ty.

## Các API khác

- POST /v1/messages/batch: mảng tối đa 100 tin (hoặc {"messages": [...]}), trả 207 kết quả từng tin.
- GET /v1/messages?status=&oa=&to=&limit=&before=: danh sách tin.
- GET /v1/messages/{id}: một tin kèm events.
- DELETE /v1/messages/{id}: hủy tin chưa gửi.
- GET /v1/templates?oa=: mẫu tin, kèm params (name, type, required, max_length).
- GET /v1/templates/{id}
- POST /v1/oas/{oa}/templates/sync: đồng bộ mẫu từ Zalo (key toàn quyền).
- GET /v1/oas, GET /v1/oas/{oa}: OA đã kết nối.
- POST /v1/connect/links: link để cửa hàng tự kết nối OA (gói Scale, key toàn quyền).
- GET/POST /v1/webhooks, DELETE /v1/webhooks/{id}: địa chỉ nhận sự kiện (key toàn quyền).
- GET /v1/usage: gói, số tin đã dùng, còn lại, phần vượt.

## Danh bạ, chiến dịch, tự động hóa (học theo Audience, Broadcasts, Automations của Resend)

- POST /v1/contacts {"phone","name","properties","unsubscribed","segments"}: thêm hoặc cập nhật theo số điện thoại.
- GET /v1/contacts?segment=&q=&unsubscribed=, GET/PATCH/DELETE /v1/contacts/{id hoặc số}.
- GET/POST /v1/segments, DELETE /v1/segments/{id hoặc tên}, POST /v1/segments/{id}/contacts {"contacts":[số hoặc ct_…]}.
- POST /v1/broadcasts {"name","oa","template","segment","mapping","send","scheduled_at"}; mapping: {"<tham số>": {"from":"name|phone|property|text|event","key","value","fallback"}}.
- GET /v1/broadcasts/{id}/review (người nhận, chi phí, lỗi), POST /v1/broadcasts/{id}/test {"to"}, /send {"scheduled_at"}, /cancel.
- GET /v1/metrics?days=7|15|30&oa=: gửi, tới máy, thất bại, phí; theo ngày, mẫu, chiến dịch.
- POST /v1/events {"event","phone","data"}: kích hoạt tự động hóa (202).
- POST /v1/automations {"name","trigger","steps","enabled"}; bước: send_message, delay, condition, wait_for_event, update_contact, add_to_segment. GET /v1/automations/{id}/runs.

## Webhook

Sự kiện: message.sent, message.delivered, message.failed, template.approved, template.rejected, oa.connected, oa.disconnected, oa.follower.added, oa.follower.removed, oa.message.received.
Header ZaPro-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + "." + rawBody)>. Gửi lại trong khoảng 24 giờ nếu không nhận 2xx.

## Lỗi

Dạng: {"error": {"code": "...", "message": "<tiếng Việt, kèm cách xử lý>"}}
- 401 missing_api_key: Thiếu header Authorization: Bearer zp_live_…
- 401 invalid_api_key: Key sai hoặc đã bị thu hồi. Tạo key mới ở trang API keys.
- 403 forbidden: Key chỉ-gửi-tin dùng cho việc cần key toàn quyền (webhook, đồng bộ mẫu, link Connect).
- 403 sandbox_recipient_not_allowed: OA sandbox chỉ gửi tới số điện thoại của thành viên công ty.
- 403 email_not_verified: Cần xác minh email trước khi kết nối OA thật, mời thành viên hay đổi gói.
- 403 plan_limit: Đã chạm giới hạn của gói (số OA, số webhook, ZaPro Connect).
- 404 not_found: Không có tin, mẫu, OA hoặc webhook này trong công ty của key.
- 409 oa_disconnected: OA đã mất kết nối. Chủ OA cần kết nối lại trên bảng điều khiển.
- 422 validation_error: Dữ liệu gửi lên chưa đúng: số điện thoại, tham số mẫu, thời điểm hẹn giờ, hoặc có trường không tồn tại (ZaPro báo lỗi thay vì bỏ qua).
- 422 template_not_approved: Mẫu đang chờ duyệt, bị từ chối hoặc bị tắt. Không có tin nào được gửi.
- 429 rate_limited: Quá 10 lệnh mỗi giây cho một key. Chờ một chút rồi gửi lại.
- 429 quota_exceeded: Gói Miễn phí đã dùng hết 1.000 tin, hoặc hết tin thử sandbox trong tháng.

## Gói

- Miễn phí: 1.000 tin đầu tiên miễn phí (cả đời tài khoản), hết thì dừng.
- Pro: 290000đ/tháng, 20.000 tin mỗi tháng, vượt 20đ/tin.
- Scale: 1490000đ/tháng, 200.000 tin mỗi tháng, vượt 15đ/tin.
Phí Zalo từng tin (300–400đ) tính riêng theo giá Zalo.

## MCP

Máy chủ MCP: https://app.zapro.vn/mcp (Streamable HTTP, không giữ phiên). Xác thực: header Authorization: Bearer <API key>, hoặc OAuth 2.1 (claude.ai, ChatGPT): metadata ở https://app.zapro.vn/.well-known/oauth-authorization-server, đăng ký động, PKCE S256.
Claude Code: claude mcp add --transport http zapro https://app.zapro.vn/mcp --header "Authorization: Bearer <API key>"
Tool:
- get_usage: Xem công ty đang ở gói nào, đã gửi bao nhiêu tin trong tháng, còn bao nhiêu tin thử sandbox, đã kết nối mấy OA, và ZaPro đang nối Zalo thật hay giả lập.
- list_oas: Liệt kê các Zalo OA đã kết nối với công ty, kèm mã OA dùng trong send_message, trạng thái kết nối và điều kiện gửi. Chưa có OA thì dùng "sandbox" để gửi thử.
- get_oa: Xem chi tiết một OA: tên, trạng thái kết nối, gói OA, lần làm mới token gần nhất.
- list_templates: Liệt kê mẫu tin ZBS đã đồng bộ từ Zalo, kèm trạng thái duyệt, loại tin (giao dịch, chăm sóc, quảng cáo), đơn giá và danh sách tham số cần điền khi gửi.
- get_template: Xem chi tiết một mẫu tin: tham số, kiểu dữ liệu, độ dài tối đa, đơn giá, lý do bị từ chối (nếu có).
- sync_templates: Lấy lại danh sách mẫu tin mới nhất của một OA từ Zalo, ví dụ sau khi vừa tạo hoặc vừa được duyệt mẫu. Cần API key toàn quyền.
- send_message: Gửi một tin Zalo theo mẫu ZBS đã duyệt tới một số điện thoại. Trả về tin ở trạng thái "queued" (đang chờ) hoặc "scheduled" (hẹn giờ, hoặc tin chăm sóc/quảng cáo rơi ngoài 07:00–22:00 được giữ tới 07:00). Gọi get_message để theo dõi. Tin thật bị Zalo tính phí khi gửi thành công.
- send_messages_batch: Gửi tối đa 100 tin trong một lệnh. Trả kết quả từng tin theo thứ tự: mã tin nếu nhận, hoặc lỗi của riêng tin đó.
- list_messages: Liệt kê tin mới nhất trước, lọc theo trạng thái, OA hoặc số điện thoại. Dùng before (mã tin cuối trang) để xem trang tiếp.
- get_message: Xem trạng thái một tin kèm các mốc thời gian (nhận lệnh, gửi đi, tới máy) và lý do lỗi bằng tiếng Việt nếu thất bại.
- cancel_message: Hủy một tin đang chờ, đang hẹn giờ hoặc đang được giữ ngoài khung giờ. Tin đã gửi đi thì không hủy được.
- create_connect_link: Tạo đường link để một cửa hàng tự kết nối Zalo OA của họ vào công ty bạn (dành cho công ty phần mềm phục vụ nhiều cửa hàng, gói Scale). Cần API key toàn quyền.
- list_webhooks: Liệt kê các địa chỉ nhận webhook của công ty và sự kiện mỗi địa chỉ đăng ký. Cần API key toàn quyền.
- create_webhook: Đăng ký một địa chỉ HTTPS nhận sự kiện (tin đã gửi, đã tới máy, thất bại, mẫu được duyệt…). Trả về secret để kiểm chữ ký ZaPro-Signature; secret chỉ hiện một lần. Cần API key toàn quyền.
- delete_webhook: Xóa một địa chỉ nhận webhook. ZaPro ngừng gửi sự kiện tới địa chỉ đó ngay. Cần API key toàn quyền.
- list_contacts: Liệt kê liên hệ trong danh bạ, mới nhất trước. Lọc theo phân khúc (tên hoặc mã), tìm theo tên hoặc số, lọc người đã từ chối nhận tin.
- upsert_contact: Thêm liên hệ theo số điện thoại; số đã có thì cập nhật tên, gộp thuộc tính. Có thể thêm vào phân khúc (tạo phân khúc nếu chưa có).
- list_segments: Liệt kê phân khúc của danh bạ kèm số liên hệ và số người đã từ chối nhận tin.
- add_to_segment: Thêm nhiều số điện thoại (hoặc mã liên hệ) vào một phân khúc; số chưa có trong danh bạ sẽ được tạo. Cần API key toàn quyền.
- list_broadcasts: Liệt kê chiến dịch kèm trạng thái (draft, scheduled, sending, sent, canceled) và số liệu: đã gửi, tới máy, thất bại, chi phí.
- get_broadcast: Xem chiến dịch: cách điền tham số, người nhận, người bị bỏ qua và lý do, số liệu gửi.
- create_broadcast: Tạo chiến dịch nháp: một mẫu tin đã duyệt gửi tới một phân khúc (bỏ trống = cả danh bạ). Chưa gửi gì. Gọi review_broadcast để xem số người nhận và chi phí, rồi hỏi người dùng trước khi send_broadcast.
- update_broadcast: Sửa tên, OA, mẫu, phân khúc hoặc cách điền tham số của chiến dịch nháp.
- review_broadcast: Như nút Review: lỗi phải sửa, cảnh báo, số người nhận thật sự (đã bỏ người từ chối và người thiếu dữ liệu), chi phí Zalo ước tính, giờ tin bắt đầu đi.
- test_broadcast: Gửi một tin thử của chiến dịch tới một số điện thoại, dùng dữ liệu của liên hệ có số đó. Tin thử bị Zalo tính phí như tin thật.
- send_broadcast: Gửi chiến dịch ngay hoặc hẹn giờ (scheduled_at ISO 8601, trong 30 ngày). Tin thật bị Zalo tính phí từng tin: luôn gọi review_broadcast và hỏi người dùng xác nhận số người nhận và chi phí trước khi gọi.
- cancel_broadcast: Đang hẹn giờ thì quay về nháp; đang gửi thì dừng, tin chưa đi bị hủy, tin đã đi giữ nguyên.
- send_event: Ghi một sự kiện tùy chỉnh cho một số điện thoại (ví dụ "booking.created" kèm data {"gio":"15:30"}). Số chưa có trong danh bạ sẽ được thêm. Tự động hóa đang bật có kích hoạt là sự kiện này sẽ chạy, và có thể gửi tin Zalo thật.
- list_automations: Liệt kê tự động hóa: trạng thái bật/tắt, sự kiện kích hoạt, các bước, số lượt chạy.
- create_automation: Tạo tự động hóa (đang tắt). steps là danh sách bước theo thứ tự, mỗi bước có type: send_message {oa, template, mapping}, delay {amount, unit: minutes|hours|days}, condition {field: contact.<khóa>|event.<khóa>, operator: eq|neq|contains|starts_with|gt|gte|lt|lte|exists|is_empty, value}, wait_for_event {event, amount, unit, onTimeout: stop|continue}, update_contact {properties, unsubscribed}, add_to_segment {segment}. mapping giống create_broadcast, thêm nguồn {"from":"event","key":"gio"}. Bật bằng enable_automation sau khi người dùng đồng ý.
- enable_automation: Bật (enabled=true) hoặc tắt tự động hóa. Khi bật, mỗi sự kiện khớp sẽ chạy các bước và có thể gửi tin Zalo thật: hỏi người dùng trước.
- list_automation_runs: Các lượt chạy gần đây của một tự động hóa: liên hệ, trạng thái, bước đang ở, nhật ký từng bước (đã gửi tin nào, bỏ qua vì sao).
- get_metrics: Số liệu 7, 15 hoặc 30 ngày: đã gửi, tới máy, thất bại, tỉ lệ tới máy, phí Zalo; theo ngày, theo mẫu, theo chiến dịch; lý do thất bại phổ biến.

## Tài liệu

- [Bắt đầu nhanh](https://app.zapro.vn/docs)
- [Gửi tin](https://app.zapro.vn/docs/send)
- [Tra cứu và hủy tin](https://app.zapro.vn/docs/messages)
- [Mẫu tin](https://app.zapro.vn/docs/templates)
- [Zalo OA và ZaPro Connect](https://app.zapro.vn/docs/oas)
- [Webhook](https://app.zapro.vn/docs/webhooks)
- [Gói và hạn mức](https://app.zapro.vn/docs/usage)
- [Lỗi](https://app.zapro.vn/docs/errors)
- [MCP và AI](https://app.zapro.vn/docs/mcp)