App 向 crm.baseUrl 发 API 请求；crm.webUrl 是 CRM 网页目录，仅用于打开客户、订单和 Token 页面，两者可以不同。两个地址都必须是 HTTPS，且不能带 query 或 hash。
通用约定
- 所有 API 请求都发送
X-API-TOKEN: <token>、Accept: application/json和Content-Type: application/json。 - GET 参数放在
crm.baseUrl?action=...的 query 中；写操作使用 JSON body。 - 成功响应推荐为
{ "success": true, "data": ... }。为兼容旧连接器，直接返回业务对象也会被当作data。 - 失败使用非 2xx HTTP 状态，并返回
{ "success": false, "error": "说明" }或{ "success": false, "message": "说明" }。 - 请求超时为 15 秒。时间戳字段除特别说明外均为 Unix 秒。
crm.webUrl下可提供api_token.php、user.php和order.php页面；这是网页导航约定，不属于 API 鉴权接口。
Actions
whoami
GET ?action=whoami。响应 data：type: string、name: string、is_admin: boolean、可选 admin_id: number（token 归属员工 ID，legacy token 为 0）。新连接器必须返回 is_admin；App 用 admin_id 区分自己和同事的跟进任务（同事的不提醒）。旧服务器缺少它时，App 才会按历史用户名规则兼容。
customer
GET ?action=customer&email=<email>。返回单个客户：user_id、contact（也兼容 first_name/last_name）、email、phone、可选 company、packing_remark、add_time_formatted。不存在时返回空 data。
customer_search
两种 GET 查询：?action=customer_search&phone=<digits> 按号码查找，或 ?action=customer_search&q=<keyword> 按关键字搜索。data 为数组，每项含 user_id（或 id）、contact（或姓名字段）、email、phone（或 telphone），可选 company、whatsapp、packing_remark、add_time_formatted。
customer_orders
GET ?action=customer_orders&user_id=<id>。data 为订单数组：order_id（或 id）、user_id、status、order_amount（或 total）、currency、add_time_formatted、items。每个 item 含 product_id、name、quantity、price。
countries
GET ?action=countries。data 为 { id: number, name: string, code: string }[]，其中 code 是小写或大写 ISO 国家码。
owners
GET ?action=owners。data 为 { self_id: number, can_assign: boolean, owners: { id: number, name: string }[] }。
create_customer
POST ?action=create_customer。JSON body：必填 contact；可选 email、company、telphone、whatsapp、country、remark、user_type、admin_id。响应 data 至少含 user_id。
update_customer_avatar
POST ?action=update_customer_avatar，body { user_id: number, avatar_url: string }。响应成功即可，可在 data 返回 user_id。avatar_url 是同步 Worker 的公开媒体 URL。
update_customer_whatsapp
POST ?action=update_customer_whatsapp，body { user_id: number, whatsapp: string, confirm?: boolean }。响应 data：user_id、old_whatsapp、new_whatsapp、updated，冲突时可返回 needs_confirm: true。
products
GET ?action=products&search=<keyword>。data 为产品数组：id、name、sku、price、currency、stock，可选 description。
push_wa_messages
POST ?action=push_wa_messages，body { messages: [...] }。每条消息包含：
- 必填：
phone、contact_name、direction（in/out）、content、msg_time、account。 - 可选：
msg_ts、ts_unknown、account_name、account_phone、account_avatar、msg_type、media_url、file_name、idempotency_key。
响应 data：received、inserted、skipped，以及逐条确认 results。每项为 { idempotency_key, status }，status 是 inserted、duplicate 或 rejected，拒绝时可带 error。App 依赖逐条确认；缺少 results 的批次会留在本地重试。
wa_messages
GET ?action=wa_messages&phone=<digits>|wa_lid=<digits>&has_media=1&limit=200。App 只在附件面板使用，必须带 phone 或 wa_lid 之一，phone 优先。has_media=1 只返回 media_url 非空的消息；不支持此参数的旧连接器返回全部消息，App 会自行过滤。data 为按时间倒序的消息数组，App 读取 id、direction、msg_type、media_url、file_name、msg_time、msg_ts、account_name、contact_name。media_url 须是同步 Worker 的 https://…/media/<key>。
update_contact_dates
POST ?action=update_contact_dates，body 必填 user_id，可选 last_contact_time、last_reply_time。成功响应即可。
followup_tasks
GET ?action=followup_tasks&scope=all&updated_since=<seconds>&after_id=<id>[&updated_until=<seconds>]。App 总是带 scope=all：客户由团队共同维护，连接器应对任何在职员工的个人 token 返回全员任务，并允许 save_followup_task/set_followup_status 改同事的任务（负责人不变）；不支持时忽略该参数、只返回本人任务即可。响应 data：tasks、server_time、has_more、next_updated_at、next_id。
每个 task 包含 id、uuid、user_id、contact_name、phone、due_at、note、status（pending/done/cancelled）、channel、source（crm/whatsagent）、updated_at、revision、deleted_at、owner_admin_id、可选 owner_name（App 在同事任务上显示负责人）。source: "whatsagent" 是既有跨系统契约值，连接器不得改名。
save_followup_task
POST ?action=save_followup_task，body：uuid、user_id、due_at、note、status、channel、expected_revision。响应 data：id、uuid、updated_at、revision。版本冲突应返回非 2xx 错误。
set_followup_status
POST ?action=set_followup_status，body { uuid, status, expected_revision }。响应 data：id、uuid、updated_at、revision。
网页链接
配置 crm.webUrl 后，WhatsTant 会打开：
${crm.webUrl}/api_token.php：获取 Token。${crm.webUrl}/user.php?rec=view&user_id=<id>：查看客户。${crm.webUrl}/user.php?rec=edit&user_id=<id>：编辑客户。${crm.webUrl}/order.php?rec=view&order_id=<id>：查看订单。
App 只允许打开 HTTPS 且以前述 crm.webUrl 为目录前缀的 CRM 链接。