第三方消息推送对接

快速开始

在 Web 管理后台为目标公司创建第三方应用，复制 App ID 和 App Secret；如需接收最终结果，再填写可选的 Callback URL。Engine 会为绑定公司的全部有效用户生成通知中心记录，并仅向符合条件的已注册设备尝试发送系统 Push。

接口与认证

API 环境：

测试环境：https://aim-api-test.proton-system.com
正式环境：https://aim-api.proton-system.com

第三方服务端发送的每个 JSON 请求都必须通过 HTTP Basic Authentication 携带 Authorization: Basic Base64(KEY:SECRET)，其中 KEY 是 App ID，SECRET 是 App Secret：

接口：POST /openapi/v1/notifications。

curl --request POST 'https://<your-engine-host>/openapi/v1/notifications' \
  --header 'Authorization: Basic <Base64(AppID:AppSecret)>' \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"order-20260819-001","title":"订单已完成","body":"您的订单已经完成。","imageUrls":["https://cdn.example.com/order/001-1.webp","https://cdn.example.com/order/001-2.webp"]}'

请求契约

严格 JSON 接受必填的 requestId、title、body，以及可选的 imageUrls。不传 imageUrls，或传 null、[]，都表示没有图片；否则按展示顺序传入 1-9 个 URL。每个值会先去除首尾空白，必须唯一，必须是无用户名和密码的绝对 HTTPS URL，并且最多 2048 个 Unicode 字符；任一 URL 不合法都会拒绝整个请求。Engine 只存储 URL，不会抓取、探测、代理或缓存图片。完整请求体上限为 256 KiB；requestId 最多 128 个 Unicode 字符，title 最多 100 个，body 最多 1000 个。每个 App ID 每分钟最多 10 次、每小时最多 100 次。

使用相同 requestId、title、body 和顺序一致的 imageUrls 重试会返回原有的已存储结果，因此处理完成后，其 status 可能是 SUCCESS、PARTIAL_SUCCESS 或 FAILED，而不是 ACCEPTED；相同 requestId 携带不同内容或图片顺序会返回 IDEMPOTENCY_CONFLICT。

接收响应

合法请求返回 HTTP 202：

{
  "requestId": "order-20260819-001",
  "notificationId": "00000000-0000-0000-0000-000000000001",
  "status": "ACCEPTED"
}

ACCEPTED 仅表示 Engine 已保存请求并等待分发，不代表 APNs/FCM 或设备已经展示系统横幅。

Callback 结果

配置 Callback URL 后，Engine 会发送一次终态结果：

{
  "requestId": "order-20260819-001",
  "status": "PARTIAL_SUCCESS",
  "recipientCount": 8,
  "pushAcceptedCount": 1,
  "pushFailedCount": 1
}

recipientCount 是通知中心接收用户数；pushAcceptedCount 和 pushFailedCount 是 Push Outbox 批次数，不是用户数、设备数或系统横幅送达数。

Callback 测试

管理后台每次测试 Callback 时都会发送一个独立的探测事件：

{
  "requestId": "callback-test-<unique-id>",
  "status": "SUCCESS",
  "recipientCount": 1,
  "pushAcceptedCount": 1,
  "pushFailedCount": 0,
  "test": true
}

收到 test: true 时，只需校验结构并返回 2xx；不要将该探测事件关联到已提交的通知请求，也不要更新业务送达状态。其中的计数是固定探测值，不代表真实接收用户或 Push Outbox 批次。

终态 status 为 SUCCESS、PARTIAL_SUCCESS 或 FAILED。返回任意 2xx 即确认成功，否则 Engine 会在 1 分钟、5 分钟、30 分钟、2 小时、6 小时和 24 小时后重试。当前 Callback 没有 HMAC 签名：必须使用 HTTPS、校验非测试结果的 requestId 是否属于己方请求、尽量限制入口暴露范围，并保证幂等处理。

错误说明

HTTP	Code	含义
400	`INVALID_REQUEST`	Content-Type、JSON 结构、大小或字段校验失败。
401	`INVALID_APP_CREDENTIALS`	App ID 或 App Secret 无效。
403	`APPLICATION_INACTIVE`	应用或绑定公司未启用。
409	`IDEMPOTENCY_CONFLICT`	相同 requestId 被用于不同内容。
429	`RATE_LIMITED`	超过应用级限流。
503	`NOTIFICATION_UNAVAILABLE`	通知服务暂时不可用。

安全与发送范围

移动客户端每张图片最多接受 5 MiB，且单张图片完整下载操作的超时时间为 10 秒。客户端不会跟随 3xx 重定向，因此每个 URL 都必须直接返回图片。

App ID 和 App Secret 是服务端到服务端凭证，禁止放入浏览器、移动 App、公开代码库、URL 或客户端存储；如有泄露请立即重置 App Secret。绑定公司的全部有效用户都会获得通知中心记录并计入 recipientCount；系统 Push 仅尝试发送到有效且允许 BUSINESS 分类的 PushInstallation，仍不保证每台设备一定显示系统横幅。imageUrls 只在通知详情展示，不会进入 Push 或 Callback 载荷。title 和 body 必须在没有图片时仍能完整表达通知；图片下载或渲染失败不会改变 accepted、Callback 或 Push 状态。移动客户端会直接从公共 CDN 下载图片，因此 URL 不得要求认证或 Cookie，且应至少保持 90 天可访问；CDN 会获得用户 IP、请求时间和 User-Agent。URL 对应内容可能变化，如需稳定保留历史展示，请使用不可变对象 URL。