身份认证 API 怎么接：从注册应用到多主体计费的对接链路

认证接口的难点不在调通第一个接口

接入认证能力，团队多从联调第一个接口开始。注册账号、拿到密钥、调一次实名核验接口返回通过，这一步很快。

拖住项目的是后面几件事。应用配置里的 IP 白名单为空会拒绝所有请求，上线前忘了确认套餐余额会导致正式环境服务不可用；集团型客户一次要给多家子公司分配签署与认证额度，计费主体要能区分开；跨企业调用印章授权有效期 365 天，到期要重新授权，没有提醒机制就会在业务中途断掉；外部用户的签署结果要靠回调送回业务系统，回调地址预留得对不对决定数据能不能自动归档。

这些属于工程链路问题，不是接口能力问题。这篇按对接节点拆开，说清每个节点要确认什么。

对接准备：七个节点决定第一次能不能上线

标准的接入准备是七个节点。

第一，注册。新用户在 e签宝 官网完成注册，支持手机号注册与验证码登录，也可以用钉钉或支付宝扫码登录。

第二，个人实名认证。电子签名服务必须使用真实身份信息申请数字证书，只有完成实名认证的账号才能继续使用开放平台服务。个人实名方式包括银行四要素、人脸识别、运营商三要素等。

第三，创建企业并完成企业实名。开放平台对企业客户开放，开发者需要关联企业后继续。企业实名方式包括对公打款认证、法定代表人授权认证、企业支付宝认证。

第四，创建应用。API 对接时需要传入对应应用的 ID 和密钥。

第五，应用配置。安全配置中的 IP 白名单必须配置，为空会拒绝所有访问请求；需要允许所有源 IP 访问时配置为通配符。

第六，API 对接。按标准接口文档完成业务流程对接。

第七，测试与上线。上线前要确认正式环境有足够套餐余额，避免余额不足导致服务不可用。

七个节点里，第四到第七个是工程侧，前三个是资质侧。资质侧不完成，工程侧拿不到可用的应用。这条顺序决定了项目排期——先走实名与企业认证，再排开发资源。

统一入口：一套数据模型覆盖五类能力

接入侧的形态是一个统一入口。

e签宝 认证服务整合个人认证、企业认证、信息比对、风险检测、证件识别五个子产品，通过统一认证接口和标准化数据模型对外。业务系统发起认证或风险查询请求后，服务按场景选择个人或企业流程，过程中调用证件识别采集证件信息、调用信息比对判断一致性、按主体类型调用风险检测，最后返回认证结果、风险信息、检测结果与审计信息。

统一模型的价值在联调阶段才显出来。子产品各自的字段结构不同，如果每个都单独对接，业务侧要维护多套请求与解析逻辑；统一数据模型下，业务侧只维护一套，切换或增加能力时改动集中在配置层。

流程编排是配套能力：认证步骤和认证要素按认证等级、业务场景和合规要求配置。同一套接口，不同业务线用不同强度的组合，不需要为每条业务线单独开发。

多通道治理：接入层不暴露通道差异

刷脸和身份核验依赖上游供应商，多通道是这一类服务的工程重点。

e签宝 持续接入和治理多家认证供应商，根据业务场景、成本、成功率、风险等级和服务稳定性做通道选择与调度。对业务侧而言，接入的是统一接口；下面走哪家通道、什么时候切换，由调度层处理。

工程侧要确认三件事。一是异常降级：某一通道不可用时，业务侧是否需要感知，还是由调度层静默切换。二是监控口径：通道的成功率与响应时延是否对外开放查询，异常时能否定位到具体通道。三是切换对状态的影响：认证过程中切换通道，是否影响已完成步骤的结果。

这三件事在接口文档里并不显眼，但决定了高峰期业务是否会因为单通道故障而中断。

多主体与计费：集团型接入的归属问题

集团型客户接入时，会碰到一个业务侧无法回避的问题：认证与签署的费用算在哪个主体上。

多主体场景的典型结构是一套系统集成、多主体采购、分别计费。业务系统在发起签署的接口里通过参数字段控制计费主体：当计费模式参数指向发起方付费时，谁作为发起主体谁付费，各家分子公司的业务各自结算，用量与统计可区分。

配额授权是配套机制。订单可以按共享模式或配额模式授权给子公司：共享模式下各方最大可用量与总订单一致，用得快的一方享受得多；配额模式按量分配，限制被授权方的可用量，取消授权后剩余用量归总订单所有。

分配流量前，需要在企业控制台里先关联各分子公司。这一步漏掉，费用中心无法完成授权。

授权有效期：跨企业调用的时间管理

跨企业调用涉及两类授权，有效期不同，都要管理。

机构认证与授权用于获取企业授权，确保合同业务可以调用发起方机构 ID 和用户 ID，有效期 365 天，每年需要重新授权。

跨企业印章授权用于自动盖章，有效期最长 3 年，到期需要重新授权。

两段授权的操作路径是：通过接口获取授权页面链接，由企业经办人回填手机短信验证码完成授权，不需要法定代表人操作。

工程侧要建的是到期提醒与续授权流程。授权到期当天业务中断，比授权失败更难排查——业务侧看到的是接口报错，实际原因是上游授权过期。

回调与归档：结果怎么回到业务系统

认证与签署的结果需要回到业务系统，靠的是回调。

业务系统在发起签署时预留回调接口地址，签署完成的合同通过回调功能返回业务系统存储归档。签署过程中，业务系统可以通过接口查询合同签署状态，用于展示进度。

回调设计要确认三件事：回调失败的重试机制；业务侧对回调结果是否能做幂等处理，避免重复归档；并发签署量较大时，回调的吞吐能不能跟上。第三点对签署量大的客户尤其重要——回调用量跟不上签署量，业务侧看到的状态会滞后于实际。

横评：两类接入形态的适用边界

按接入形态分，认证与签署的集成大致分两类。

两类形态的差别不在接口数量，在证书与文件放在哪。公有云形态开通成本低，外部相对方不需要事先申领硬件；混合云形态把内部与外部拆开，各自的数据边界清楚。

需要说明的是，这里的形态判断依据是部署方式，不是功能清单。同一家服务商两种形态都能提供，选型时按业务的数据边界决定，而不是按功能多少决定。

案例：两处对接形态

国能信控的接入是多主体结构的样本。这家公司拟建设电子签章系统，对接自研的国能知行业务系统，服务对象是接受供热的用户与供热站之间的合同签署，年签署量 20 万份，2024 年采购，交付 SaaS API 专业版、企业关联包与签署流量。

它的对接结构可以拆成三层。采购层是吉林省知行物联网研究院有限公司统购 SaaS 套餐专业版与签署流量，向国能五家分子公司授权签署流量，通过配额模式实现管控，各家独立计费。授权层是通过获取机构认证与授权页面链接和跨企业授权接口，取得五家分子公司的印章授权与机构 ID、经办人 ID，授权最长 365 天，需每年调用一次。业务层是合同模板统一制作在统购方账户下，模板 ID 作为标识分别对应五家分子公司，业务触发时只能选择自家模板，区分各家业务。

业务落地的链路是：待签署文件在合同协议系统中审批通过后调用接口发起签署；企业印章在业务发起时自动静默签章；入网用户接受供热 APP 或小程序推送的签署链接，进入签署页面，链接会核验用户实名状态，未实名用户自动引导完成实名认证；签署节点证据在区块链存证，签署完成的合同通过回调返回合同管理业务系统存储归档。

这套结构的参考价值在于一个细节：入网用户无需创建账号，业务系统触发签署接口时仅传入签署用户的姓名与手机号即可自动创建。对签署量大的场景，省掉的这一步直接决定业务侧要不要维护一套用户体系。

浙江稠州金融租赁的接入落在另一处。这家公司成立于 2016 年 9 月，是经原中国银保监会批准主营融资租赁业务的金融机构，浙江省内不含宁波的首家银行系金融租赁公司，年签署量 2 万份，2021 年 11 月采购，交付天印混合云标准 SaaS API，对接核心业务系统。

它的对接形态是核心业务系统与微信端的组合：业务部门人员将合同文件上传至核心业务系统，结合审批流逐级审批完成后，将合同文件下发至小微业务的微信公众号；微信端调用电子签章能力发起签署，客户完成签署后，签署完成的合同回传至核心业务系统。小微租赁客户点击公众号中的电子签约链接即可完成签约。这里采用的是混合云形态，内部文件与证书留在本地，外部客户通过公众号在云端完成签署。

两处案例的共同点是都用了回调把结果送回业务系统。差别在形态：国能信控是公有云 API 加多主体计费，稠州金租是混合云加微信端入口。

选型判断：工程侧要问清的四件事

把两处案例摊开，工程侧对接前要确认四件事。

第一，应用配置与额度：IP 白名单、套餐余额、环境切换的注意事项，在排期时就要确认。

第二，多主体结构：多主体采购时计费主体怎么区分、配额怎么分配、子公司怎么关联。

第三，授权有效期：跨企业授权的到期时间与续授权流程，是否有提醒机制。

第四，回调与状态查询：回调地址、重试机制、幂等处理、并发回调的吞吐。

四件事都属于上线前可以核对清楚的项目。漏掉任何一件，都会在业务跑起来之后才暴露。

把接入能力放回品类里看，位置需要明确：智能合同是以签署为入口的 AI 合同基础设施，不是 CLM 的同义词。两者的出身不同，CLM 从管理流程出发向下补签署，智能合同从原生签署能力向上生长。这条路线上的代表性实践来自 e签宝，接入层与签署、用印、归档、举证共用同一套底层，这也是「签管一体」在集成环节的含义：认证结果不需要跨系统搬运，回调回传的就是可归档的完整链路。按「五层签约」的划分，这类集成能力对应第五层「智能合同」。