API 签名与调用

请求地址

所有 API 服务统一走网关，通过 endpoint 指定具体服务：

POST https://www.tasi.cc/api/gateway.php?endpoint=realname

endpoint 使用产品标识，例如：realname、sms、invoice-check、enterprise。联调可先用 ping。

支付宝人脸实名

realname 采用“创建认证 + 查询结果”两步：

1. POST /api/gateway.php?endpoint=realname
{"action":"create","name":"张三","id_card":"身份证号","return_url":"https://你的站点/realname-return"}

返回 certify_id 和 certify_url，让用户打开 certify_url 完成人脸认证。return_url 可选，用于认证完成后跳回你的站点。

2. POST /api/gateway.php?endpoint=realname-query
{"action":"query","certify_id":"上一步返回的 certify_id"}

创建认证消耗 1 次配额，查询结果不扣配额。认证结果以支付宝返回的 certified 为准。

请求头

Header	说明
X-App-Id	控制台生成的 AppID
X-Timestamp	Unix 秒级时间戳，允许 ±300 秒
X-Nonce	8-64 位随机串，10 分钟内不能重复
X-Signature	Base64(HMAC-SHA256(待签串, AppSecret))

待签串

POST
/api/gateway.php
{AppID}
{Timestamp}
{Nonce}
{sha256(原始请求体)}

每行一个字段，使用 \n 连接；请求体哈希使用小写十六进制 SHA-256。

PHP 示例

<?php
$appId = 'ak_xxxxxxxxxxxxxxxx';
$secret = 'sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$body = json_encode(['action' => 'create', 'name' => '张三', 'id_card' => '...'], JSON_UNESCAPED_UNICODE);
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(8));

$stringToSign = "POST\n/api/gateway.php\n{$appId}\n{$timestamp}\n{$nonce}\n" . hash('sha256', $body);
$signature = base64_encode(hash_hmac('sha256', $stringToSign, $secret, true));

$ch = curl_init('https://www.tasi.cc/api/gateway.php?endpoint=realname');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        "X-App-Id: {$appId}",
        "X-Timestamp: {$timestamp}",
        "X-Nonce: {$nonce}",
        "X-Signature: {$signature}",
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);

返回格式

{"code":0,"message":"请让用户打开 certify_url 完成人脸认证，然后调用 realname-query 查询结果","data":{"certify_id":"...","certify_url":"...","query_endpoint":"realname-query"}}

{"code":0,"message":"认证通过","data":{"certify_id":"...","status":"CERTIFIED","passed":"T","certified":true}}

错误码

HTTP	code	说明
401	401	缺少签名头、时间戳过期、AppID 无效、签名错误
403	403	AppID 无权调用该接口
404	404	认证记录不存在
409	409	Nonce 已使用，疑似重放
429	429	套餐配额已用完
502	502	支付宝上游返回失败
503	503	接口上游尚未配置

配额在控制台「我的授权」里查看；目前新开通 API 默认 100 次测试配额。