API v2 文档

本文档介绍星楼网络平台 API v2 的鉴权方式与接口调用方法。所有接口均使用 API Key + HMAC-SHA256 签名 鉴权。

1. 基础信息

• 接口地址：https://api.starloft.cn/v2
• 请求格式：application/json
• 鉴权方式：请求头携带 API Key 与签名（见「请求鉴权」）

2. 调用前提（必读）

调用本 API 前，账户必须同时满足以下条件：

1. 账户已完成实名认证。实名状态（realname_status）按产品区分： 人脸核验（fv）需企业实名（realname_status=2）； 短信（sms）完成个人实名（realname_status=1）即可， 未实名（0）时所有服务均不可用。请在星楼网络控制台完成对应实名认证。
2. 创建 API 密钥。在控制台「API 密钥管理」中创建，可创建多把并各自配置权限； 密钥对（API Key + API Secret）创建后展示，API Secret 用于请求签名与回调验签。
3. API 密钥权限覆盖所调用的接口。密钥权限范围（permission）为 all（全部接口），或按接口逐项授权的标识集合（逗号分隔，如 fv_auth,sms_send）。可授权的接口标识见各接口说明与「错误码」章节， 在控制台「API 密钥管理」中创建或编辑密钥时勾选。 人脸核验（fv）与短信（sms）接口权限各自独立。

未完成对应实名、密钥权限未覆盖，或密钥无效时调用相应接口， 将返回 code: 403 提示。

3. 请求鉴权

服务端同时兼容两版签名协议：hmac_sha256_v2（推荐，新接入一律使用）与 hmac_sha256（存量兼容，仅过渡期保留，未来会择期下线）。

注意：以下 v1 / v2 指签名协议版本，与接口路径版本（/v1、/v2）无关——两版签名协议均可用于任一接口路径。

通用请求头如下（v2 全带 5 个；v1 可不带 X-Nonce）：

签名算法（v2，hmac_sha256_v2，推荐）

先计算原始请求体 SHA-256，再把方法、调用方可见路径、原始查询串、时间戳、nonce 与正文摘要用换行符拼接：

canonical = METHOD + "\n" + PATH + "\n" + RAW_QUERY + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + hex(SHA256(body))
sign = hex(HMAC-SHA256(api_secret, canonical))

PHP 示例：

$bodyHash = hash('sha256', $body);
$canonical = implode("\n", [$method, $path, $rawQuery, $timestamp, $nonce, $bodyHash]);
$sign = hash_hmac('sha256', $canonical, $apiSecret);

签名算法（v1，hmac_sha256，存量兼容）

签名为对原始请求体（POST 的 JSON 字符串，与发送内容完全一致）进行 HMAC-SHA256 运算后的小写十六进制字符串。该版本不强制 X-Nonce、不做原子防重放，请尽快迁移到 v2：

sign = hex(HMAC-SHA256(api_secret, 原始请求体))

PHP 示例：

$sign = hash_hmac('sha256', $body, $apiSecret); // 小写十六进制

4. 接口列表

本产品接口

• 发起人脸核验 /v2/fv/auth
• 查询核验结果 /v2/fv/result
• 获取活体最佳图 /v2/fv/best-img
• 获取认证媒体 /v2/fv/media

4.4 产品与资源包

平台提供的下游能力与人脸核验子产品计费方式如下：

人脸核验按子产品 fv_auth 计费，对应独立资源包。 短信服务（sms）按短信资源包计费，先扣资源包、余额兜底； 短信发送时通过 sign_name 选择签名、template_id 与 template_params 选择模板与参数， 短信类别（验证码 / 通知 / 营销，验证码与通知同属通知类，计费一致；仅营销短信单独扣营销资源包）由平台在模板审核环节判定，不随请求传递。

4.5 发起人脸核验（FV）

POST/v2/fv/auth（有源人脸核验，服务标识 fv_auth）

发起一次人脸核验，需 API 密钥权限覆盖 fv_auth， 或权限为 all。 有源（auth）需传入 name 与 id_card（人脸 + 公安库比对）； 接口支持传入 notify_url； return_url 可选，留空时核验完成后停留在平台认证结果页、不回跳下游， 计费与资源包按子产品隔离（fv_auth 独立资源包）。

扣费时机：平台返回 token（接受本次核验）成功后才扣费——被平台拦截、连接失败时不扣费， 订单仍会保留并写入失败原因（状态「超时/连接超时」），便于对账排查。 发起前平台会校验额度（命中资源包或余额足够），不足时直接返回错误、不产生订单。 命中资源包时按次扣减 1 次（订单「资源包扣减」列可见），未命中则扣余额；结果为不计费（6000/6100）时自动原路退还。

请求参数

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "biz_no": "46382671905182934716",
    "site_url": "https://service.starloft.cn/fv/auth?token=xxx"
  }
}

data.site_url 为平台自站承接链接（PC 打开该链接会展示核验二维码供手机扫码，移动端打开会直接跳转核验页）。 用户核身后平台先回跳 /v2/fv/return 完成一次结果校对，再 302 到你填写的 return_url，无需你自建中转页； 未填写 return_url 时，承接页停留在认证结果界面（认证成功/失败）不做跳转。

4.6 查询核验结果（FV）

POST/v2/fv/result

按业务流水号 biz_no 查询认证订单状态，用于前台轮询与结果校对， 返回的是平台已落地的订单状态。建议优先配置 notify_url： 结果由异步通知驱动落地，无需轮询即可实时到达。

未配置 notify_url 的订单（「跳过异步通知」模式）没有任何推送，平台会在你轮询时 按每笔订单的反查次数上限与最小间隔同步结果并落地后再返回（平台对同一笔核身 仅允许有限次结果反查，超出后该笔结果将不可取回）。因此请勿按秒级高频轮询： 高频轮询不会让结果更早出现，只会增加无效请求，建议间隔 ≥ 5~10 秒并设置轮询上限 （核身链接通常有效 60 分钟，以平台返回的 expired_time 为准；平台未返回时平台按 60 分钟兜底，过期未完成的订单平台会自动终结并退还已扣费用）。

请求参数

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "biz_no": "46382671905182934716",
    "status": 2,
    "result_code": "1000",
    "result_message": "SUCCESS"
  }
}

status：0 待认证 / 1 认证中 / 2 认证成功 / 3 认证失败 / 5 超时结束（核身链接过期未完成、或核验结果已不可取回，不计费、已扣费用已退还）/ 6 发起失败（平台拦截或连接超时，未扣费）； status ≥ 2 即为终态，可作为轮询结束条件。result_code / result_message 见「5.1 result_code 说明」。

4.7 获取活体最佳图（FV）

POST/v2/fv/best-img

认证成功（status=2）后 24 小时内可领取该笔订单的活体最佳图（base64）， 每笔订单仅可领取一次；平台实时取图转交，本地不落库。

请求参数

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "biz_no": "46382671905182934716",
    "best_img": "data:image/jpeg;base64,xxxx"
  }
}

4.7.1 获取认证媒体（FV）

POST/v2/fv/media

认证成功（status=2）后，平台自动从平台下载该笔订单的活体照片（image_best）与 验证视频（video），本地保存 30 天；期间可随时经本接口下载（均返回 base64）， 过期后自动清理不可再获取。

请求参数

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "biz_no": "46382671905182934716",
    "media": {
      "image_best": "/9j/4AAQSkZJRg...（base64）",
      "video": "AAAAIGZ0eXBpc29t...（base64，无则缺省）"
    }
  }
}

视频为完整可播放的 MP4（base64），解密后存储，无需再向平台申请；若平台未返回某类媒体，对应字段缺省。

5. 回调说明（notify_url 与 return_url）

发起人脸核验时需提供 notify_url（异步通知），return_url（同步跳转）可选， 用于认证结果回流。两者触发时机与数据格式如下。

5.1 异步通知（notify_url）

认证产生最终结果（成功或失败）后，平台会以 POST 方式向你的 notify_url 发送通知，Content-Type: application/json。 通知携带 sign（HMAC-SHA256 签名，基于你的 API Secret 生成）， 下游应校验签名后再落地结果，防止伪造回调；同时可依据 biz_no（平台订单号）关联订单。

请求体

{
  "biz_no": "46382671905182934716",
  "status": 2,
  "result_code": "1000",
  "result_message": "SUCCESS",
  "cost": 1.50,
  "sign": "a1b2c3d4e5f6..."
}

字段说明

签名算法

取 biz_no、cost、result_code、 result_message、status 五个字段， 按 key 字典序拼接为原始字符串（不做 URL 编码），以 API Secret 计算 HMAC-SHA256：

canonical = "biz_no=xxx&cost=1.50&result_code=1000&result_message=xxx&status=2"
sign = 小写hex( HMAC-SHA256(api_secret, canonical) )

其中 cost 固定保留两位小数（如 1.50），status 为整数。校验失败应拒绝该通知（返回非 2xx）。若通知丢失，可调用 /v2/fv/result 按 biz_no 主动查询。

result_code 说明

6000 / 6100 为不计费结果，平台会自动退还预扣金额； NOT_STARTED / PROCESSING 表示认证尚未完结，不会作为最终通知发送。

核身未产生核验结果时，平台以自有结果码结束订单（均为不计费，已扣费用自动退还）：

上述结果同样经 notify_url 推送，下游应以「通知为准」并配合低频轮询，请勿按秒级高频轮询 /v2/fv/result：平台内部反查结果的次数每笔订单有限（且平台已按额度预算控制）， 高频轮询不会让结果更早出现，只会增加无效请求。

响应要求

下游收到通知后返回 HTTP 200～299 即可（平台校验 2xx 视为通知成功，否则后续重试）。

5.2 同步跳转（return_url）

认证结果确定后，平台会将用户浏览器以 GET 方式 302 跳转回你发起认证时填写的 return_url，且不附加任何参数（跳转地址与你传入的 return_url 完全一致， 认证失败同样跳回该 return_url）。 下游应依据自己记录的 biz_no 展示结果，最终核验状态以异步通知（5.1）为准。

示例：

https://yourdomain.com/certification/star_loft_fv_for_zjmf_mfcw/result

未填写 return_url（留空）时，平台不发起回跳：用户核身后停留在平台承接页的认证结果界面 （认证成功展示「认证成功」并停留；认证失败展示失败原因），结果仍以异步通知（5.1）为准。 填写 return_url 时，承接页会在认证结束后展示结果并倒计时 3 秒自动跳转到该地址（也可点击「立即返回」）。

说明：return_url 用于用户侧页面回流，notify_url 用于服务端结果落地， 两者配合使用；若 notify_url 未及时到达，可调用 /v2/fv/result 按 biz_no 主动查询。

7. 错误码