CRM 推送接口

CRM 直接提交客户业务字段，PushMsg 将其转换为“仙宝科技”公众号的“新客户跟进通知”。公众号通道、微信模板 ID 与微信字段名由服务端配置。

接口与鉴权

服务地址：https://openid.xianboss.com。

每个调用系统同时携带 X-API-Key: YOUR_CRM_API_KEY 和 X-API-Secret: YOUR_CRM_API_SECRET。Key 也支持 Authorization: Bearer YOUR_CRM_API_KEY，Secret 仍必填。凭据须具有当前 CRM 公众号通道权限，且 OpenID 须已在后台绑定到该系统及通道。未绑定或停用的接收人返回 403 RECIPIENT_FORBIDDEN，不会入队。

系统之间的接收人独立授权；新系统没有接收人时不能推送。凭据轮换会同时更换 Key 和 Secret，旧凭据立即失效。旧版单 Key 接入需先在管理后台轮换凭据、配置接收人，再使用双凭据请求。

openId 对应通知接收人，例如 CRM 负责人或管理人员；客户字段描述 CRM 中的客户记录。接收人的 OpenID 必须属于目标公众号，可通过 OpenID 页面获取后由管理员绑定到对应调用系统，再与 CRM 员工账号绑定；仅获取 OpenID 不会自动授予推送权限。

提交请求

POST /api/v1/crm/push
Content-Type: application/json
X-API-Key: YOUR_CRM_API_KEY
X-API-Secret: YOUR_CRM_API_SECRET

{
  "requestId": "crm-customer-C0001-followup-001",
  "openId": "YOUR_OPENID",
  "customerName": "测试客户",
  "customerType": "潜在客户",
  "customerSource": "CRM录入",
  "customerPhone": "13800000000",
  "markedAt": "2026-10-26 11:00",
  "url": "https://crm.example.com/customers/C0001"
}

所有字段使用 JSON 字符串；必填字段不可为空白，字符串不接受控制字符。服务不会自动去除空格或改写值。markedAt 不会默认取当前时间，重试时应保持本次业务事件的时间不变。

请求只接受表中字段。channelId、templateId、type、data 或其他额外字段会返回 400 UNSUPPORTED_CRM_FIELD。

成功接收与去重

首次提交返回 HTTP 202：

{
  "id": "11111111-2222-4333-8444-555555555555",
  "status": "PENDING",
  "duplicate": false
}

幂等范围为“调用方应用 + requestId”，标识区分大小写。同一标识及相同映射内容返回 HTTP 200、原消息 ID、当前状态及 duplicate:true；内容变化返回 409 IDEMPOTENCY_CONFLICT。JSON 对象键顺序不影响去重，接收人、字段值和详情 URL 的变化会影响消息内容。

状态查询

curl --fail-with-body \
  'https://openid.xianboss.com/api/v1/crm/messages/11111111-2222-4333-8444-555555555555' \
  -H "X-API-Key: $CRM_PUSH_API_KEY" \
  -H "X-API-Secret: $CRM_PUSH_API_SECRET"

必须使用原调用方的密钥；其他调用方的消息按不存在处理，返回 HTTP 404。

{
  "id": "11111111-2222-4333-8444-555555555555",
  "requestId": "crm-customer-C0001-followup-001",
  "status": "SENT",
  "attempts": 1,
  "maxAttempts": 5,
  "wechatMessageId": "WECHAT_MESSAGE_ID",
  "lastError": null,
  "createdAt": "2026-10-26T11:00:00",
  "updatedAt": "2026-10-26T11:00:01"
}

时间字段按北京时间返回，可能带小数秒。微信消息 ID 以字符串处理，未成功或微信未返回时可能为 null。

可每 2–5 秒查询一次，按业务量适当放宽间隔。对网络超时或临时服务错误的提交重试，应继续使用原 requestId 和原内容。UNKNOWN 人工重试可能产生重复通知。

模板字段映射

GET /api/v1/crm/template
X-API-Key: YOUR_CRM_API_KEY
X-API-Secret: YOUR_CRM_API_SECRET

当前默认通道为 xianbao，模板为“新客户跟进通知”。接口会返回通道 ID、模板名称、模板 ID、时区及以下字段映射，调用方须有该通道权限。

发送时使用左侧业务字段即可。当前完整微信模板 ID 为 OpH0RvriM-Zi5WmN25X6ox0FY6rKMoStoXb_ab-jiRw；以模板配置接口返回值为准。

cURL 调用

先将请求示例保存为 crm-message.json，替换接收人和业务数据，再执行：

export CRM_PUSH_API_KEY='YOUR_CRM_API_KEY'
export CRM_PUSH_API_SECRET='YOUR_CRM_API_SECRET'

curl --fail-with-body \
  'https://openid.xianboss.com/api/v1/crm/push' \
  -H "X-API-Key: $CRM_PUSH_API_KEY" \
  -H "X-API-Secret: $CRM_PUSH_API_SECRET" \
  -H 'Content-Type: application/json' \
  --data-binary @crm-message.json

下载 CRM JSON 示例或 OpenAPI 3.0.3 定义。完整的可编译 Java 17 标准库调用和轮询示例见 完整 CRM 调用文档。

错误码与限制

应用错误一般返回以下 JSON；入口层的请求大小与限流错误也可能返回 HTTP 错误页面。

{"code":"INVALID_CRM_TIME","message":"markedAt 必须是有效的北京时间，格式 yyyy-MM-dd HH:mm"}

常见 400 错误包括 VALIDATION_ERROR、INVALID_CRM_REQUEST、INVALID_CRM_TIME、INVALID_CRM_PHONE、UNSUPPORTED_CRM_FIELD 和 INVALID_URL。微信最终拒绝的任务会记录为 FAILED，具体原因见 lastError。