要素核验 API v2 文档

本文档介绍要素核验接口。平台提供企业三/四要素核验与身份证二要素核验能力；按核验次数计费，资源包优先、余额兜底。

1. 基础信息

接口地址：https://api.starloft.cn/v2/ev
请求格式：application/json
鉴权方式：API Key + HMAC-SHA256 签名（与平台其它产品一致，见「请求鉴权」）
可授权接口标识：ev_biz3（企业三要素）、ev_biz4（企业四要素）、ev_idcard（身份证二要素）

2. 调用前提

账户已完成企业实名（realname_status = 2，要素核验三档均需企业实名）。
已创建 API 密钥，且密钥权限包含对应接口标识（或为 all）。
账户有对应档位资源包次数或余额（核验前平台会做额度预检，不足时返回 402）。

3. 发起核验

接口	说明
`POST /v2/ev/biz3/verify`	企业三要素：企业名称 + 统一社会信用代码 + 法人姓名
`POST /v2/ev/biz4/verify`	企业四要素：三要素 + 法人身份证号
`POST /v2/ev/idcard/verify`	身份证二要素：姓名 + 身份证号

参数	类型	必填	说明
`ent_name`	string	企业类必填	企业名称
`credit_code`	string	企业类必填	统一社会信用代码
`lr_name`	string	企业类必填	法人姓名
`id_number`	string	四要素 / 身份证二要素必填	身份证号（落库脱敏，仅保留前 3 后 4）
`name`	string	身份证二要素必填	被核验人姓名

{
  "ent_name": "示例科技有限公司",
  "credit_code": "911101085636549482",
  "lr_name": "张三",
  "id_number": "110101199001011234"
}

4. 响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "biz_no": "83920174651293847561",
    "service": "ev_biz4",
    "verified": true,
    "status_code": 0,
    "verify_result": 1,
    "operating_status": "1",
    "request_id": "ff3cb900-...",
    "charge_status": 1,
    "billed": true,
    "amount": 2.0,
    "pay_type": 1,
    "pack_count": 0
  }
}

5. 计费规则与错误码

企业类仅当平台返回 status_code=0（成功并计入平台账单）时计 1 次；系统异常（1）与查询无结果（2）不计费。
身份证二要素：result=01（一致）与 02（不一致）计费，03（不确定）与 04（失败）不计费。
计费顺序：先扣对应档位资源包次数，不足时扣余额。
错误码：400 参数缺失 / 类型非法；402 资源包与余额均不足；503 产品未开通；502 平台调用失败。