开放 API
把线索、账号、数据接进你自己的系统
标准 REST 接口 + 事件订阅。线索新增、分配、成交都能实时推送，失败自动重试并留日志。企业定制版默认开通，专业版可按需申请。
接入路径
四步，半天能跑通
01
申请密钥
后台「系统设置 → 开放接口」生成 AppKey / AppSecret，可分别设置读、写、事件三种权限。
5 分钟
02
换 access_token
用 AppKey + AppSecret 换 2 小时有效的 access_token，过期用 refresh_token 续期。
OAuth 2.0
03
拉数据 / 订阅事件
历史数据用分页接口拉全量；增量走 Webhook，配置回调地址并验签即可。
全量 + 增量
04
对账与重试
每次推送带唯一 event_id 与签名；失败按 1/5/30 分钟三次重试，日志可查。
不丢单
请求示例
先看一眼长什么样
所有接口统一走 HTTPS，返回 JSON，字段口径与后台页面完全一致
# 1. 换取 access_token
POST https://api.matrixpro.cn/oauth/token
Content-Type: application/json
{
"app_key": "mp_live_7f3c...",
"app_secret": "sk_9a1d...",
"grant_type": "client_credentials"
}
# 2. 拉取线索（分页，每页最多 100 条）
GET https://api.matrixpro.cn/v1/leads?page=1&size=100&updated_after=2026-10-01T00:00:00Z
Authorization: Bearer <access_token>
{
"total": 1286,
"list": [{
"lead_id": "ld_20261030_8821",
"name": "张女士",
"phone": "138****6602",
"intent": "初一数学",
"source_platform": "douyin",
"account": "@李老师聊升学",
"employee": "李老师",
"video_id": "vd_20261029_114",
"first_reply_seconds": 58,
"status": "assigned"
}]
}
# 3. 事件推送（我们 POST 给你，带签名）
POST https://your-crm.com/hooks/matrixpro
X-MP-Signature: sha256=6f2b...
X-MP-Event: lead.created
{
"event_id": "evt_01J8Z9...",
"event": "lead.created",
"occurred_at": "2026-10-30T13:40:12+08:00",
"data": { "lead_id": "ld_20261030_8821", "phone": "13800006602" }
}
提示：手机号在接口中默认脱敏。需要完整号码请在后台申请「明文手机号」权限，审批通过后接口返回完整值，且每次调用都会记录审计日志。
接口清单
当前开放的 14 个接口
按资源分组，完整文档在开通后可见
| 接口 | 方法 | 说明 |
|---|---|---|
| /v1/leads | GET | 线索列表，支持按时间、来源、状态、员工筛选 |
| /v1/leads/{id} | GET | 线索详情，含首次响应时长与归因视频 |
| /v1/leads/{id}/status | POST | 回写跟进状态（已联系 / 已到店 / 已成交 / 无效） |
| /v1/videos | GET | 成片列表，含播放、交互、带来线索数 |
| /v1/videos/{id} | GET | 成片详情，可下载原文件地址（有效期 30 分钟） |
| /v1/accounts | GET | 账号矩阵，含授权状态、粉丝量、最近发布 |
| /v1/accounts/{id}/unbind | POST | 解绑账号（离职回收场景） |
| /v1/plans | GET | 发布计划，含审核状态与排期时间 |
| /v1/plans | POST | 创建发布计划（外部系统触发发布） |
| /v1/reports/attribution | GET | 归因报表，按员工 / 视频 / 校区维度聚合 |
| /v1/orgs/members | GET | 员工与部门，含角色与席位状态 |
| /v1/quota | GET | 短信与算力余额、本月消耗明细 |
| /v1/quota/topup | POST | 发起充值（企业定制版可用，走对公或预授权） |
| /v1/health | GET | 服务健康检查，不带鉴权，用于对接自检 |
约定
几条必须知道的规则
- 限流：默认 600 次 / 分钟 / 应用，突发允许 1.5 倍；超限返回 429 并带 Retry-After，请按该值退避。
- 幂等：创建类接口支持 Idempotency-Key 头，重复提交同一 Key 返回首次结果，不会产生两条数据。
- 事件顺序：不保证严格有序，请以 occurred_at 与 event_id 去重排序。
- 重试：推送失败按 1 / 5 / 30 分钟重试三次，全部失败进死信队列，后台可手动补推。
- 版本：接口按 /v1、/v2 路径版本化，旧版本至少保留 12 个月并提前 90 天公告。
- 安全：必须校验 X-MP-Signature（HMAC-SHA256，含时间戳，5 分钟内有效），拒绝未验签请求。