协议与接口约定

接口按提交、校验、授权、返回和记录五个阶段处理。请求只携带解析所需字段,返回只包含授权范围内的信息,错误按类型区分,调用方按返回结果决定后续业务请求,处理过程写入记录,调用方不重复提交同一请求。

处理阶段

一次请求从提交开始,经过格式与状态校验、授权判断,再返回结果并写入记录。阶段按顺序执行,前一阶段不通过时不进入下一阶段。

请求进入解析节点后,先判断字段是否齐全,再核对标识格式和记录状态。校验不通过时直接返回错误,不进入授权判断。

  1. 提交:携带标识、调用方标识和凭据。
  2. 校验:检查字段完整性、标识格式和记录状态。
  3. 授权:按调用方标识确定可见字段和可用节点。
  4. 返回:输出端点、版本、状态和权属摘要。
  5. 记录:写入请求编号、调用方、结果和失败原因。

请求字段

请求字段以解析所需为限。调用方不提交业务正文,也不提交与本次解析无关的主体信息。

凭据随请求提交,不放在地址参数中。调用方标识应与凭据所属主体一致,不一致时按无权限处理。

字段必填说明
标识是待解析的完整标识
调用方标识是已登记的主体或节点标识
凭据是接入时签发的调用凭据
请求字段否指定需要的返回字段,缺省返回基础字段
请求编号否调用方生成的幂等编号,长度不超过 64 位

返回字段

成功返回包含标识、记录版本、端点、状态、权属摘要和记录编号。失败返回错误码、错误说明和记录编号,不返回端点。

返回字段按授权范围裁剪。调用方请求超出范围的字段时,接口拒绝请求,不返回部分结果。

返回项内容说明
标识本次解析对象与请求标识一致
记录版本当前版本号变更后递增
端点地址、协议、接入方式仅在解析成功时返回
权属摘要主体名称与授权范围按授权范围返回
记录编号本次请求记录编号用于核对与排查

错误分类

错误按原因分类,调用方按类型处理,不对同一错误连续重试。

错误说明用于定位原因,调用方按说明核对字段和权限,不把错误说明直接展示给最终用户。

错误类型处理方式
格式错误核对标识和字段格式后重新提交
标识不存在停止请求,核对标识来源
无权限检查调用方标识和授权范围
记录校验失败暂停使用结果,联系登记节点
版本不一致等待节点同步后重新解析

幂等与版本协商

调用方可为同一次业务请求生成请求编号,重复提交时按请求编号识别,避免重复写入记录。请求编号由调用方生成,长度不超过 64 位。

涉及接口字段调整时,按版本协商处理。调用方在接入测试阶段确认字段含义和返回方式,正式使用后按当前版本处理,不混用旧字段。

请求编号相同的重复提交,按首次结果返回,不重复写入记录。调用方在超时后重试时沿用原请求编号,避免产生多条记录。

核对安全边界

凭据、权限、记录和注销的处理方式在安全与合规说明中列明,接入前可一并核对。

查看安全说明