/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后,紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}
400热线经常被标记广告,对接来电名片接口修正展示信息,字段、回调、生效时效是高频踩坑点。
号码被标记这事,做企业热线的人多少都碰过。客户手机上来电显示“疑似推销”,接起来第一句就是“你们是不是推销的”。想修正展示信息,就得对接来电名片接口。接口本身不复杂,复杂的是字段对不上、回调收不到、提交完迟迟不生效。这篇按对接顺序拆,把调试阶段最容易卡住的地方逐条列出来。
摘要
400来电名片接口对接的核心是把企业名称、号码、资质、展示标签按平台规范提交,并处理审核状态回调和运营商同步时效。本文拆解对接前资质准备、鉴权与提交接口、字段映射、回调处理、生效时效排查和常见错误码,给出字段对照表、脱敏请求与回调日志片段、调试清单和FAQ,帮助减少“提交成功但不展示”“回调收不到”“审核过了运营商没同步”这类对接问题。
关键词
400来电名片接口;来电名片对接;号码标记修正;企业信息展示;回调调试
一、先搞清楚:来电名片展示的是什么
来电名片不是改手机本地通讯录,也不是改某个App的标记库。它是在通话建立时,由运营商侧向被叫终端下发一段企业展示信息,终端支持的情况下显示企业名称、logo或标签。
所以对接前要分清三件事:
| 号码归属 | 运营商 | 400号码本身是否在你名下 |
| 展示内容 | 名片平台提交、运营商审核 | 企业名称、logo、标签、行业 |
| 终端展示 | 被叫手机/终端厂商 | 是否支持、是否开启展示 |
第三项不受接口控制。同一个企业名片,有的手机显示,有的不显示,先确认终端支持情况,再排查接口,不然容易在错误的方向上耗时间。
二、对接前要准备的资质和字段
接口提交的不是一段文字,是一组带资质的企业信息。常见准备项:
| 企业营业执照 | 主体核验 | 名称与400开户主体不一致会被退 |
| 400号码归属证明 | 证明号码归你使用 | 号码在代理商名下、企业名下,材料不同 |
| 企业简称/展示名称 | 终端展示用 | 超长、含敏感词、与执照名称差异过大 |
| logo文件 | 终端展示 | 尺寸、格式、背景透明要求各平台不同 |
| 行业/标签 | 展示分类 | 选错行业可能影响审核 |
| 联系人信息 | 审核沟通 | 手机号填错收不到审核通知 |
这里第一个坑就出现了:提交主体和号码归属主体不一致。400号码挂在代理商名下、企业只是使用方,和号码直接在企业名下,需要提交的授权材料不一样。对接前先确认号码归属,再按平台要求准备授权书或使用证明,别等提交被退才回头补。
三、接口对接流程:四步走
常见对接流程是:鉴权→提交→查询→回调。不同平台接口路径和字段名不同,但环节类似。
3.1 鉴权
一般用appkey/secret换token,或签名方式。调试时先确认:
-
token有效期和刷新机制;
-
签名串拼接顺序是否和文档一致;
-
时间戳时区(有的平台要求毫秒,有的要求秒);
-
请求头Content-Type和编码。
签名错是最常见的401/403来源,先把签名调通,再调业务接口。
3.2 提交
提交接口一般接收号码、企业信息、资质文件ID。伪代码示意:
json
{
"number": "400****888",
"company_name": "某某设备维修服务部",
"company_short_name": "某某维修",
"industry_code": "M73",
"logo_file_id": "file_20261117_001",
"contact_phone": "138****1234",
"auth_material_ids": ["mat_001", "mat_002"]
}
字段名是示意,以你签约平台的接口文档为准。提交后一般返回一个工单号或申请ID,后面查状态、对回调都用它。
3.3 查询
提交成功不等于审核通过。查询接口按工单号拉状态,常见状态值:
| submitted | 已提交 | 等待审核 |
| reviewing | 审核中 | 等待 |
| rejected | 驳回 | 看驳回原因,改材料重提 |
| approved | 审核通过 | 等待运营商同步 |
| effective | 已生效 | 验证终端展示 |
| expired | 已过期 | 续期或重新提交 |
注意“approved”和“effective”是两回事,这是后面时效坑的根源。
3.4 回调
平台把审核结果、生效结果推到你配置的回调地址。回调要处理:
-
验签,确认是平台发的;
-
幂等,同一工单可能重复推送;
-
落库,把状态和工单号关联;
-
失败重试,回调地址不可达时平台可能重推,也可能不重推,要问清楚。
四、字段调试坑:逐条拆
坑1:展示名称和执照名称差异过大被退。
企业简称可以比执照名称短,但不能看不出关联。提交前对照平台对简称的规则,别用纯品牌词代替主体名称。
坑2:logo格式对了,尺寸不对。
有的平台要求正方形、有的要求横版,透明背景和白色背景的要求也不一样。先按文档给一张合规图,别拿官网横幅图直接裁。
坑3:行业编码填错。
行业编码一般有对照表,填错不一定被退,但可能影响展示分类。调试时把编码表拉出来对一遍。
坑4:号码格式不统一。
带不带横线、带不带区号、是否补零,各平台要求不同。提交前用平台给的格式校验接口或正则对一遍。
坑5:资质文件ID和上传接口不匹配。
先调上传接口拿file_id,再调提交接口。有人把本地文件路径直接填进提交字段,返回“文件不存在”。
坑6:多号码批量提交时字段错位。
批量接口常见数组字段和号码数组长度不一致,导致A号码绑了B企业的信息。批量提交前先单条跑通,再上量。
五、脱敏请求与回调日志片段:调试时先看这几段
光看文档不够,调试期要把原始请求和回调原文打出来。下面是一段脱敏后的日志示意,字段名按你平台的实际日志调整。
text
# 提交请求(脱敏)
POST /v1/namecard/submit
headers:
Authorization: Bearer eyJ****
Content-Type: application/json
body:
number: 400****888
company_name: 某某设备维修服务部
company_short_name: 某某维修
industry_code: M73
logo_file_id: file_20261117_001
auth_material_ids: [mat_001, mat_002]
# 提交响应
status: 200
body:
code: 0
message: accepted
ticket_id: NC20261117-0087
# 回调原文(脱敏)
POST /callback/namecard
headers:
X-Signature: 9f2c****
body:
ticket_id: NC20261117-0087
status: approved
review_time: 2026-11-17 14:20:31
remark: 材料齐全
# 回调验签结果
sign_verify: pass
idempotent_hit: false
这段日志能回答几个问题:提交请求体里字段有没有缺、返回的工单号有没有落库、回调状态是什么、验签过没过、幂等有没有命中。调试期日志比代码值钱,原始请求体、请求头、回调原文、验签结果四项都留着。
六、回调调试坑:收不到、重复、验签失败
回调是调试阶段第二大卡点。常见问题:
| 收不到回调 | 回调地址外网不可达、端口未放行、HTTPS证书问题 | 用平台提供的回调测试工具打一次 |
| 回调重复 | 平台重推、你的接口超时未返回成功 | 做幂等,按工单号去重 |
| 验签失败 | 签名串拼接顺序错、编码不一致、时间戳过期 | 对照文档逐字段打印签名原文 |
| 状态字段对不上 | 平台状态值和文档版本不一致 | 拉最新文档,确认状态枚举 |
| 回调里没有工单号 | 提交时没把工单号落库 | 提交成功立即落库,别等回调 |
一个实操建议:回调接口先写日志,把原始请求体、请求头、验签结果全打出来,再处理业务。调试期日志比代码值钱。
七、生效时效坑:审核过了,为什么还不展示
这是问得最多的一类问题。拆开看有三段时效:
| 平台审核 | 名片平台 | 1—3个工作日 | 材料是否齐全、是否被驳回 |
| 运营商同步 | 运营商 | 审核通过后数个工作日 | 是否收到生效回调、号码是否在同步范围 |
| 终端展示 | 终端厂商/手机设置 | 取决于终端 | 被叫手机是否支持、是否开启展示 |
三段里任何一段没走完,都会表现为“提交了但看不到”。排查顺序建议:
查工单状态是不是effective,不是的话先解决审核和同步;
确认测试号码在同步范围内,换一台支持展示的终端复测;
确认被叫手机没开拦截或关闭了名片展示;
以上都排除,再找平台查运营商侧同步记录。
别一上来就怀疑接口,很多“不生效”其实是终端不支持或测试号码不在范围。
八、错误码与处理建议
不同平台错误码定义不同,下面按类别归纳,具体码值以你平台文档为准。
| 鉴权类 | 401/403、token过期 | 重取token、核对签名 |
| 参数类 | 400、字段缺失/格式错 | 对照字段表逐项校验 |
| 资质类 | 审核驳回 | 看驳回原因,补材料 |
| 频率类 | 429、提交过于频繁 | 加退避重试,别硬刷 |
| 状态类 | 工单不存在/已过期 | 核对工单号、重新提交 |
| 回调类 | 验签失败/超时 | 打日志、对签名原文 |
九、调试清单:上线前过一遍
- □
号码归属主体确认,授权材料齐全
- □
鉴权调通,token刷新逻辑可用
- □
单号码提交成功,拿到工单号并落库
- □
查询接口能拉到全部状态值
- □
回调地址外网可达,验签通过,幂等生效
- □
驳回场景走通,能改材料重提
- □
approved到effective的时效有监控
- □
批量提交前单条验证,字段不错位
- □
日志保留原始请求和回调原文
- □
测试终端覆盖至少两种支持展示的机型
不同服务商的接口字段命名和回调格式差异不小,像优音通信这类服务商的文档里字段叫法可能和运营商规范有差异,对接时以你签约主体提供的接口文档为准,别拿别家文档硬套。
常见问题(FAQ)
Q:来电名片接口提交成功,为什么不展示?
A:提交成功只代表受理,还要过平台审核、运营商同步、终端支持三段。先查工单状态是否effective,再确认测试终端是否支持展示。
Q:回调收不到怎么办?
A:先确认回调地址外网可达、端口放行、证书有效;用平台回调测试工具打一次;再看平台是否只对失败重推。
Q:展示名称可以随便写吗?
A:不行。简称要和执照主体有关联,不能纯品牌词替代主体名称,差异过大容易被驳回。
Q:审核通过后多久生效?
A:平台审核常见1—3个工作日,运营商同步还要数个工作日,终端展示取决于被叫手机。具体时效以平台文档和工单状态为准。
Q:同一工单回调重复推送怎么处理?
A:按工单号做幂等,重复推送只更新状态不重复执行业务;回调接口要快速返回成功,避免平台判定超时重推。
Q:批量提交多个号码要注意什么?
A:先单条跑通;批量时确认号码数组和字段数组长度一致、顺序对应;提交后逐条落库工单号,别只存一个批次号。
Q:号码在代理商名下,能对接吗?
A:可以,但需要按平台要求提供号码使用证明或授权材料,具体清单以平台审核要求为准。
Q:配置项找不到对应字段怎么办?
A:先在你平台的接口文档中心搜“来电名片”“号码标记”“回调验签”“工单状态”这几个关键词;找不到就直接问平台技术支持要字段对照表,别照着其他平台的截图硬配。
网硕互联帮助中心





评论前必须登录!
注册