开放 API 文档

<?php
// 短信开放 API 调用示例（PHP 7.4 及以上，需要 curl 扩展）

const APP_ID = '你的 AppId';
const APP_SECRET = '你的 AppSecret'; // 只保存在服务端，切勿写进网页、小程序或 App
const API_ORIGIN = 'https://am.siyun223.com';
const API_PREFIX = '/api/open/v1';

/**
 * 签名并发送请求，返回 [HTTP 状态码, 响应数组]
 */
function openApiRequest(string $method, string $path, ?array $payload = null, array $extraHeaders = []): array
{
    $method = strtoupper($method);
    $fullPath = API_PREFIX . $path;
    $body = $payload === null ? '' : json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
    $timestamp = (string) time();
    $nonce = bin2hex(random_bytes(16));

    // 待签名串：方法、路径、规范查询串（无查询参数时为空）、时间戳、随机串、请求体 SHA256，用 \n 连接
    $stringToSign = implode("\n", [$method, $fullPath, '', $timestamp, $nonce, hash('sha256', $body)]);
    $signature = hash_hmac('sha256', $stringToSign, APP_SECRET);

    $headers = array_merge([
        'Accept: application/json',
        'X-App-Id: ' . APP_ID,
        'X-Timestamp: ' . $timestamp,
        'X-Nonce: ' . $nonce,
        'X-Signature: ' . $signature,
    ], $extraHeaders);

    $ch = curl_init(API_ORIGIN . $fullPath);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
    curl_setopt($ch, CURLOPT_TIMEOUT, 15);
    if ($payload !== null) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POSTFIELDS, $body); // 发送的必须是参与签名的同一个字符串
    }
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

    $response = curl_exec($ch);
    if ($response === false) {
        throw new RuntimeException('请求失败：' . curl_error($ch));
    }

    return [(int) curl_getinfo($ch, CURLINFO_HTTP_CODE), json_decode($response, true)];
}

// 1. 查询余额
[$status, $result] = openApiRequest('GET', '/account/balance');
echo $status, ' ', json_encode($result, JSON_UNESCAPED_UNICODE), PHP_EOL;

// 2. 获取可用模板：发送时使用 items[].variant.id 与 items[].signature.id
[$status, $result] = openApiRequest('GET', '/sms/templates');
echo $status, ' ', json_encode($result, JSON_UNESCAPED_UNICODE), PHP_EOL;

// 3. 发送短信：Idempotency-Key 建议使用业务单号，网络异常重试时保持不变
[$status, $result] = openApiRequest('POST', '/sms/send', [
    'template_variant_id' => 12,
    'signature_id' => 2,
    'phone_numbers' => ['13800000000'],
    'template_params' => ['code' => '123456'],
], ['Idempotency-Key: order-20261008-0001']);
echo $status, ' ', json_encode($result, JSON_UNESCAPED_UNICODE), PHP_EOL;

// 4. 查询发送结果
if ($status === 200 && !empty($result['data']['batch_uuid'])) {
    [$status, $result] = openApiRequest('GET', '/sms/batches/' . $result['data']['batch_uuid']);
    echo $status, ' ', json_encode($result, JSON_UNESCAPED_UNICODE), PHP_EOL;
}

# 短信开放 API 调用示例（Python 3.6 及以上，只使用标准库）
import hashlib
import hmac
import json
import secrets
import time
import urllib.error
import urllib.request

APP_ID = "你的 AppId"
APP_SECRET = "你的 AppSecret"  # 只保存在服务端，切勿写进网页、小程序或 App
API_ORIGIN = "https://am.siyun223.com"
API_PREFIX = "/api/open/v1"


def open_api_request(method, path, payload=None, headers=None):
    """签名并发送请求，返回 (HTTP 状态码, 响应内容)"""
    method = method.upper()
    full_path = API_PREFIX + path
    body = b"" if payload is None else json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
    timestamp = str(int(time.time()))
    nonce = secrets.token_hex(16)

    # 待签名串：方法、路径、规范查询串（无查询参数时为空）、时间戳、随机串、请求体 SHA256，用 \n 连接
    string_to_sign = "\n".join([method, full_path, "", timestamp, nonce, hashlib.sha256(body).hexdigest()])
    signature = hmac.new(APP_SECRET.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()

    request_headers = {
        "Accept": "application/json",
        "X-App-Id": APP_ID,
        "X-Timestamp": timestamp,
        "X-Nonce": nonce,
        "X-Signature": signature,
    }
    if payload is not None:
        request_headers["Content-Type"] = "application/json"
    request_headers.update(headers or {})

    request = urllib.request.Request(
        API_ORIGIN + full_path,
        data=body if payload is not None else None,  # 发送的必须是参与签名的同一份字节
        headers=request_headers,
        method=method,
    )
    try:
        with urllib.request.urlopen(request, timeout=15) as response:
            return response.status, _parse(response.read())
    except urllib.error.HTTPError as error:
        return error.code, _parse(error.read())


def _parse(raw):
    try:
        return json.loads(raw.decode("utf-8"))
    except ValueError:
        return raw.decode("utf-8", "replace")


if __name__ == "__main__":
    # 1. 查询余额
    print(open_api_request("GET", "/account/balance"))

    # 2. 获取可用模板：发送时使用 items[].variant.id 与 items[].signature.id
    print(open_api_request("GET", "/sms/templates"))

    # 3. 发送短信：Idempotency-Key 建议使用业务单号，网络异常重试时保持不变
    status, result = open_api_request("POST", "/sms/send", {
        "template_variant_id": 12,
        "signature_id": 2,
        "phone_numbers": ["13800000000"],
        "template_params": {"code": "123456"},
    }, {"Idempotency-Key": "order-20261008-0001"})
    print(status, result)

    # 4. 查询发送结果
    if status == 200 and isinstance(result, dict) and result.get("data", {}).get("batch_uuid"):
        print(open_api_request("GET", "/sms/batches/" + result["data"]["batch_uuid"]))

// 短信开放 API 调用示例（Java 11 及以上，只使用 JDK 标准库）
// 保存为 OpenApiDemo.java，执行：javac -encoding UTF-8 OpenApiDemo.java && java OpenApiDemo
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.SecureRandom;
import java.time.Duration;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class OpenApiDemo {
    private static final String APP_ID = "你的 AppId";
    private static final String APP_SECRET = "你的 AppSecret"; // 只保存在服务端，切勿写进网页、小程序或 App
    private static final String API_ORIGIN = "https://am.siyun223.com";
    private static final String API_PREFIX = "/api/open/v1";
    private static final HttpClient CLIENT = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(5)).build();
    private static final SecureRandom RANDOM = new SecureRandom();

    public static void main(String[] args) throws Exception {
        // 1. 查询余额
        HttpResponse<String> balance = request("GET", "/account/balance", null, null);
        System.out.println(balance.statusCode() + " " + balance.body());

        // 2. 获取可用模板：发送时使用 items[].variant.id 与 items[].signature.id
        HttpResponse<String> templates = request("GET", "/sms/templates", null, null);
        System.out.println(templates.statusCode() + " " + templates.body());

        // 3. 发送短信：请求体可以用 Jackson、Gson 等生成，签名与发送必须使用同一个字符串
        String body = "{\"template_variant_id\":12,\"signature_id\":2,"
                + "\"phone_numbers\":[\"13800000000\"],\"template_params\":{\"code\":\"123456\"}}";
        HttpResponse<String> sent = request("POST", "/sms/send", body, "order-20261008-0001");
        System.out.println(sent.statusCode() + " " + sent.body());

        // 4. 查询发送结果（示例用正则提取 batch_uuid，生产代码请用 JSON 库解析）
        Matcher matcher = Pattern.compile("\"batch_uuid\":\"([0-9a-fA-F-]{36})\"").matcher(sent.body());
        if (sent.statusCode() == 200 && matcher.find()) {
            HttpResponse<String> batch = request("GET", "/sms/batches/" + matcher.group(1), null, null);
            System.out.println(batch.statusCode() + " " + batch.body());
        }
    }

    /** 签名并发送请求 */
    static HttpResponse<String> request(String method, String path, String body, String idempotencyKey) throws Exception {
        String fullPath = API_PREFIX + path;
        String payload = body == null ? "" : body;
        String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
        String nonce = randomHex(16);

        // 待签名串：方法、路径、规范查询串（无查询参数时为空）、时间戳、随机串、请求体 SHA256，用 \n 连接
        String stringToSign = String.join("\n", method, fullPath, "", timestamp, nonce, sha256Hex(payload));

        HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create(API_ORIGIN + fullPath))
                .timeout(Duration.ofSeconds(15))
                .header("Accept", "application/json")
                .header("X-App-Id", APP_ID)
                .header("X-Timestamp", timestamp)
                .header("X-Nonce", nonce)
                .header("X-Signature", hmacSha256Hex(APP_SECRET, stringToSign));
        if (idempotencyKey != null) {
            builder.header("Idempotency-Key", idempotencyKey);
        }
        if (body == null) {
            builder.method(method, HttpRequest.BodyPublishers.noBody());
        } else {
            builder.header("Content-Type", "application/json")
                    .method(method, HttpRequest.BodyPublishers.ofString(payload, StandardCharsets.UTF_8));
        }

        return CLIENT.send(builder.build(), HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
    }

    static String sha256Hex(String value) throws Exception {
        return toHex(MessageDigest.getInstance("SHA-256").digest(value.getBytes(StandardCharsets.UTF_8)));
    }

    static String hmacSha256Hex(String secret, String value) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        return toHex(mac.doFinal(value.getBytes(StandardCharsets.UTF_8)));
    }

    static String randomHex(int bytes) {
        byte[] buffer = new byte[bytes];
        RANDOM.nextBytes(buffer);
        return toHex(buffer);
    }

    static String toHex(byte[] bytes) {
        StringBuilder hex = new StringBuilder(bytes.length * 2);
        for (byte b : bytes) {
            hex.append(String.format("%02x", b));
        }
        return hex.toString();
    }
}

// 短信开放 API 调用示例（Node.js 18 及以上，使用内置 fetch 与 crypto，无需安装依赖）
// 保存为 open-api-demo.mjs，执行：node open-api-demo.mjs
import { createHash, createHmac, randomBytes } from 'node:crypto';

const APP_ID = '你的 AppId';
const APP_SECRET = '你的 AppSecret'; // 只保存在服务端，切勿写进网页、小程序或 App
const API_ORIGIN = 'https://am.siyun223.com';
const API_PREFIX = '/api/open/v1';

/** 签名并发送请求，返回 { status, data } */
async function openApiRequest(method, path, payload = null, extraHeaders = {}) {
  const fullPath = API_PREFIX + path;
  const body = payload === null ? '' : JSON.stringify(payload);
  const timestamp = String(Math.floor(Date.now() / 1000));
  const nonce = randomBytes(16).toString('hex');

  // 待签名串：方法、路径、规范查询串（无查询参数时为空）、时间戳、随机串、请求体 SHA256，用 \n 连接
  const bodyHash = createHash('sha256').update(body, 'utf8').digest('hex');
  const stringToSign = [method, fullPath, '', timestamp, nonce, bodyHash].join('\n');
  const signature = createHmac('sha256', APP_SECRET).update(stringToSign, 'utf8').digest('hex');

  const headers = {
    Accept: 'application/json',
    'X-App-Id': APP_ID,
    'X-Timestamp': timestamp,
    'X-Nonce': nonce,
    'X-Signature': signature,
    ...extraHeaders,
  };
  if (payload !== null) {
    headers['Content-Type'] = 'application/json';
  }

  const response = await fetch(API_ORIGIN + fullPath, {
    method,
    headers,
    body: payload === null ? undefined : body, // 发送的必须是参与签名的同一个字符串
    signal: AbortSignal.timeout(15000),
  });
  const text = await response.text();
  let data = text;
  try {
    data = JSON.parse(text);
  } catch {
    // 非 JSON 响应原样返回
  }
  return { status: response.status, data };
}

// 1. 查询余额
console.log(JSON.stringify(await openApiRequest('GET', '/account/balance')));

// 2. 获取可用模板：发送时使用 items[].variant.id 与 items[].signature.id
console.log(JSON.stringify(await openApiRequest('GET', '/sms/templates')));

// 3. 发送短信：Idempotency-Key 建议使用业务单号，网络异常重试时保持不变
const sent = await openApiRequest('POST', '/sms/send', {
  template_variant_id: 12,
  signature_id: 2,
  phone_numbers: ['13800000000'],
  template_params: { code: '123456' },
}, { 'Idempotency-Key': 'order-20261008-0001' });
console.log(JSON.stringify(sent));

// 4. 查询发送结果
if (sent.status === 200 && sent.data?.data?.batch_uuid) {
  console.log(JSON.stringify(await openApiRequest('GET', `/sms/batches/${sent.data.data.batch_uuid}`)));
}

#!/usr/bin/env bash
# 短信开放 API 调用示例（bash、curl 与 openssl）
# 保存为 open-api-demo.sh，执行：bash open-api-demo.sh
set -euo pipefail

APP_ID='你的 AppId'
APP_SECRET='你的 AppSecret'   # 只保存在服务端，切勿写进网页、小程序或 App
API_ORIGIN='https://am.siyun223.com'
API_PREFIX='/api/open/v1'

# 用法：open_api_request 方法 路径 [JSON 请求体] [Idempotency-Key]
open_api_request() {
  local method="$1" path="${API_PREFIX}$2" body="${3:-}" idempotency_key="${4:-}"
  local timestamp nonce body_hash signature
  timestamp=$(date +%s)
  nonce=$(openssl rand -hex 16)
  body_hash=$(printf '%s' "$body" | openssl dgst -sha256 -hex | awk '{print $NF}')
  # 待签名串：方法、路径、规范查询串（无查询参数时为空行）、时间戳、随机串、请求体 SHA256
  signature=$(printf '%s\n%s\n\n%s\n%s\n%s' "$method" "$path" "$timestamp" "$nonce" "$body_hash" \
    | openssl dgst -sha256 -hmac "$APP_SECRET" -hex | awk '{print $NF}')

  local args=(-sS -X "$method" "${API_ORIGIN}${path}"
    -H 'Accept: application/json'
    -H "X-App-Id: ${APP_ID}"
    -H "X-Timestamp: ${timestamp}"
    -H "X-Nonce: ${nonce}"
    -H "X-Signature: ${signature}"
    -w '\nHTTP %{http_code}\n')
  if [ -n "$body" ]; then
    args+=(-H 'Content-Type: application/json' --data-binary "$body")
  fi
  if [ -n "$idempotency_key" ]; then
    args+=(-H "Idempotency-Key: ${idempotency_key}")
  fi
  curl "${args[@]}"
}

# 1. 查询余额
open_api_request GET /account/balance

# 2. 获取可用模板：发送时使用 items[].variant.id 与 items[].signature.id
open_api_request GET /sms/templates

# 3. 发送短信：Idempotency-Key 建议使用业务单号，网络异常重试时保持不变
open_api_request POST /sms/send \
  '{"template_variant_id":12,"signature_id":2,"phone_numbers":["13800000000"],"template_params":{"code":"123456"}}' \
  'order-20261008-0001'

# 4. 查询发送结果：把发送接口返回的 data.batch_uuid 填到路径末尾
# open_api_request GET /sms/batches/替换为batch_uuid

<?php
// 短信签名 / 模板申请示例（PHP 7.4 及以上，需要 curl 扩展）

const APP_ID = '你的 AppId';
const APP_SECRET = '你的 AppSecret'; // 只保存在服务端，切勿写进网页、小程序或 App
const API_ORIGIN = 'https://am.siyun223.com';
const API_PREFIX = '/api/open/v1';

/** 规范查询串：按参数名字节序升序，RFC 3986 编码 */
function canonicalQuery(array $query): string
{
    ksort($query, SORT_STRING);
    $pairs = [];
    foreach ($query as $key => $value) {
        $pairs[] = rawurlencode((string) $key) . '=' . rawurlencode((string) $value);
    }
    return implode('&', $pairs);
}

/**
 * 签名并发送请求，$body 为原始请求体字节（JSON 字符串或图片字节），返回 [HTTP 状态码, 响应数组]
 */
function openApiRequest(string $method, string $path, array $query = [], string $body = '', string $contentType = 'application/json'): array
{
    $method = strtoupper($method);
    $fullPath = API_PREFIX . $path;
    $queryString = canonicalQuery($query);
    $timestamp = (string) time();
    $nonce = bin2hex(random_bytes(16));

    $stringToSign = implode("\n", [$method, $fullPath, $queryString, $timestamp, $nonce, hash('sha256', $body)]);
    $headers = [
        'Accept: application/json',
        'X-App-Id: ' . APP_ID,
        'X-Timestamp: ' . $timestamp,
        'X-Nonce: ' . $nonce,
        'X-Signature: ' . hash_hmac('sha256', $stringToSign, APP_SECRET),
    ];

    $ch = curl_init(API_ORIGIN . $fullPath . ($queryString === '' ? '' : '?' . $queryString));
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);
    if ($body !== '') {
        $headers[] = 'Content-Type: ' . $contentType;
        curl_setopt($ch, CURLOPT_POSTFIELDS, $body); // 发送的必须是参与签名的同一份字节
    }
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $response = curl_exec($ch);
    if ($response === false) {
        throw new RuntimeException('请求失败：' . curl_error($ch));
    }
    return [(int) curl_getinfo($ch, CURLINFO_HTTP_CODE), json_decode($response, true)];
}

function json(array $data): string
{
    return json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
}

// 1. 上传签名证明材料：请求体为图片原始字节，slot / position 为查询参数并参与签名
[$status, $result] = openApiRequest('POST', '/sms/signatures/files', ['slot' => 'other', 'position' => 0], file_get_contents(__DIR__ . '/proof.jpg'), 'image/jpeg');
echo $status, ' ', json($result), PHP_EOL;
$fileToken = $result['data']['file_token'] ?? '';

// 2. 提交签名申请：qualification_id 取「资质列表」中 usable_for_signature 为 true 的资质
[$status, $result] = openApiRequest('POST', '/sms/signatures', [], json([
    'qualification_id' => 8,
    'content' => '示例科技',
    'sign_source' => 1,
    'scene' => '用于向注册用户发送登录验证码与订单通知',
    'files' => ['other' => [$fileToken]],
]));
echo $status, ' ', json($result), PHP_EOL;

// 3. 提交模板申请：signature_id 可用本人已通过的签名或平台共享签名
[$status, $result] = openApiRequest('POST', '/sms/templates/applications', [], json([
    'name' => '登录验证码',
    'channel_type' => 'CN_OTP',
    'signature_id' => 23,
    'content' => '您的验证码为${code}，5分钟内有效，请勿泄露给他人。',
]));
echo $status, ' ', json($result), PHP_EOL;

// 4. 查询模板审核结果：status 为 approved 后，send_options 给出发送用的 template_variant_id 与 signature_id
if ($status === 201) {
    [$status, $result] = openApiRequest('GET', '/sms/templates/applications/' . $result['data']['id']);
    echo $status, ' ', json($result), PHP_EOL;
}

# 短信签名 / 模板申请示例（Python 3.6 及以上，只使用标准库）
import hashlib
import hmac
import json
import secrets
import time
import urllib.error
import urllib.parse
import urllib.request

APP_ID = "你的 AppId"
APP_SECRET = "你的 AppSecret"  # 只保存在服务端，切勿写进网页、小程序或 App
API_ORIGIN = "https://am.siyun223.com"
API_PREFIX = "/api/open/v1"


def canonical_query(query):
    """规范查询串：按参数名字节序升序，RFC 3986 编码"""
    pairs = sorted((str(k), str(v)) for k, v in (query or {}).items())
    return "&".join(urllib.parse.quote(k, safe="-_.~") + "=" + urllib.parse.quote(v, safe="-_.~") for k, v in pairs)


def open_api_request(method, path, query=None, body=b"", content_type="application/json"):
    """签名并发送请求，body 为原始请求体字节，返回 (HTTP 状态码, 响应内容)"""
    method = method.upper()
    full_path = API_PREFIX + path
    query_string = canonical_query(query)
    timestamp = str(int(time.time()))
    nonce = secrets.token_hex(16)

    string_to_sign = "\n".join([method, full_path, query_string, timestamp, nonce, hashlib.sha256(body).hexdigest()])
    headers = {
        "Accept": "application/json",
        "X-App-Id": APP_ID,
        "X-Timestamp": timestamp,
        "X-Nonce": nonce,
        "X-Signature": hmac.new(APP_SECRET.encode(), string_to_sign.encode(), hashlib.sha256).hexdigest(),
    }
    if body:
        headers["Content-Type"] = content_type

    url = API_ORIGIN + full_path + ("?" + query_string if query_string else "")
    request = urllib.request.Request(url, data=body or None, headers=headers, method=method)
    try:
        with urllib.request.urlopen(request, timeout=30) as response:
            return response.status, json.loads(response.read().decode("utf-8"))
    except urllib.error.HTTPError as error:
        return error.code, json.loads(error.read().decode("utf-8") or "{}")


def to_json(data):
    return json.dumps(data, ensure_ascii=False, separators=(",", ":")).encode("utf-8")


if __name__ == "__main__":
    # 1. 上传签名证明材料：请求体为图片原始字节，slot / position 为查询参数并参与签名
    with open("proof.jpg", "rb") as image:
        status, result = open_api_request("POST", "/sms/signatures/files", {"slot": "other", "position": 0}, image.read(), "image/jpeg")
    print(status, result)
    file_token = (result.get("data") or {}).get("file_token", "")

    # 2. 提交签名申请：qualification_id 取「资质列表」中 usable_for_signature 为 true 的资质
    print(open_api_request("POST", "/sms/signatures", body=to_json({
        "qualification_id": 8,
        "content": "示例科技",
        "sign_source": 1,
        "scene": "用于向注册用户发送登录验证码与订单通知",
        "files": {"other": [file_token]},
    })))

    # 3. 提交模板申请：signature_id 可用本人已通过的签名或平台共享签名
    status, result = open_api_request("POST", "/sms/templates/applications", body=to_json({
        "name": "登录验证码",
        "channel_type": "CN_OTP",
        "signature_id": 23,
        "content": "您的验证码为${code}，5分钟内有效，请勿泄露给他人。",
    }))
    print(status, result)

    # 4. 查询模板审核结果：status 为 approved 后，send_options 给出发送用的 template_variant_id 与 signature_id
    if status == 201:
        print(open_api_request("GET", "/sms/templates/applications/%d" % result["data"]["id"]))

// 短信签名 / 模板申请示例（Java 11 及以上，只使用 JDK 标准库）
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.security.MessageDigest;
import java.security.SecureRandom;
import java.time.Duration;
import java.util.Map;
import java.util.TreeMap;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class SmsApplyDemo {
    static final String APP_ID = "你的 AppId";
    static final String APP_SECRET = "你的 AppSecret"; // 只保存在服务端，切勿写进网页、小程序或 App
    static final String API_ORIGIN = "https://am.siyun223.com";
    static final String API_PREFIX = "/api/open/v1";
    static final HttpClient CLIENT = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(5)).build();

    /** RFC 3986 编码：URLEncoder 把空格编码为 +，这里换成 %20，并保留 ~ */
    static String rfc3986(String value) {
        return URLEncoder.encode(value, StandardCharsets.UTF_8).replace("+", "%20").replace("%7E", "~").replace("*", "%2A");
    }

    /** 规范查询串：TreeMap 按参数名升序（参数名为 ASCII 时与字节序一致） */
    static String canonicalQuery(Map<String, String> query) {
        StringBuilder sb = new StringBuilder();
        for (Map.Entry<String, String> entry : new TreeMap<>(query).entrySet()) {
            if (sb.length() > 0) sb.append('&');
            sb.append(rfc3986(entry.getKey())).append('=').append(rfc3986(entry.getValue()));
        }
        return sb.toString();
    }

    /** 签名并发送请求，body 为原始请求体字节，返回 "HTTP 状态码 响应体" */
    static String request(String method, String path, Map<String, String> query, byte[] body, String contentType) throws Exception {
        String fullPath = API_PREFIX + path;
        String queryString = canonicalQuery(query);
        String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
        byte[] nonceBytes = new byte[16];
        new SecureRandom().nextBytes(nonceBytes);
        String nonce = hex(nonceBytes);

        String bodyHash = hex(MessageDigest.getInstance("SHA-256").digest(body));
        String stringToSign = String.join("\n", method, fullPath, queryString, timestamp, nonce, bodyHash);
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(APP_SECRET.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        String signature = hex(mac.doFinal(stringToSign.getBytes(StandardCharsets.UTF_8)));

        HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create(API_ORIGIN + fullPath + (queryString.isEmpty() ? "" : "?" + queryString)))
            .timeout(Duration.ofSeconds(30))
            .header("Accept", "application/json")
            .header("X-App-Id", APP_ID)
            .header("X-Timestamp", timestamp)
            .header("X-Nonce", nonce)
            .header("X-Signature", signature);
        if (body.length > 0) {
            builder.header("Content-Type", contentType).method(method, HttpRequest.BodyPublishers.ofByteArray(body));
        } else {
            builder.method(method, HttpRequest.BodyPublishers.noBody());
        }
        HttpResponse<String> response = CLIENT.send(builder.build(), HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        return response.statusCode() + " " + response.body();
    }

    static String hex(byte[] bytes) {
        StringBuilder hex = new StringBuilder();
        for (byte b : bytes) {
            hex.append(String.format("%02x", b));
        }
        return hex.toString();
    }

    static byte[] json(String text) {
        return text.getBytes(StandardCharsets.UTF_8);
    }

    static String extract(String response, String field) {
        Matcher matcher = Pattern.compile("\"" + field + "\":\"?([A-Za-z0-9]+)").matcher(response);
        return matcher.find() ? matcher.group(1) : "";
    }

    public static void main(String[] args) throws Exception {
        // 1. 上传签名证明材料：请求体为图片原始字节，slot / position 为查询参数并参与签名
        String upload = request("POST", "/sms/signatures/files", Map.of("slot", "other", "position", "0"),
            Files.readAllBytes(Path.of("proof.jpg")), "image/jpeg");
        System.out.println(upload);
        String fileToken = extract(upload, "file_token");

        // 2. 提交签名申请：qualification_id 取「资质列表」中 usable_for_signature 为 true 的资质
        System.out.println(request("POST", "/sms/signatures", Map.of(), json(
            "{\"qualification_id\":8,\"content\":\"示例科技\",\"sign_source\":1,"
            + "\"scene\":\"用于向注册用户发送登录验证码与订单通知\",\"files\":{\"other\":[\"" + fileToken + "\"]}}"), "application/json"));

        // 3. 提交模板申请：signature_id 可用本人已通过的签名或平台共享签名
        String template = request("POST", "/sms/templates/applications", Map.of(), json(
            "{\"name\":\"登录验证码\",\"channel_type\":\"CN_OTP\",\"signature_id\":23,"
            + "\"content\":\"您的验证码为${code}，5分钟内有效，请勿泄露给他人。\"}"), "application/json");
        System.out.println(template);

        // 4. 查询模板审核结果：status 为 approved 后，send_options 给出发送用的 template_variant_id 与 signature_id
        if (template.startsWith("201")) {
            System.out.println(request("GET", "/sms/templates/applications/" + extract(template, "id"), Map.of(), new byte[0], ""));
        }
    }
}

// 短信签名 / 模板申请示例（Node.js 18 及以上，无需安装依赖）
import { createHash, createHmac, randomBytes } from 'node:crypto';
import { readFileSync } from 'node:fs';

const APP_ID = '你的 AppId';
const APP_SECRET = '你的 AppSecret'; // 只保存在服务端，切勿写进网页、小程序或 App
const API_ORIGIN = 'https://am.siyun223.com';
const API_PREFIX = '/api/open/v1';

// RFC 3986 编码：encodeURIComponent 不编码 !'()*，需要补上
const rfc3986 = (value) => encodeURIComponent(String(value)).replace(/[!'()*]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase());

/** 规范查询串：按参数名字节序升序 */
function canonicalQuery(query = {}) {
  return Object.keys(query)
    .sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)))
    .map((key) => `${rfc3986(key)}=${rfc3986(query[key])}`)
    .join('&');
}

/** 签名并发送请求，body 为 Buffer（JSON 或图片字节），返回 [HTTP 状态码, 响应内容] */
async function openApiRequest(method, path, { query = {}, body = Buffer.alloc(0), contentType = 'application/json' } = {}) {
  method = method.toUpperCase();
  const fullPath = API_PREFIX + path;
  const queryString = canonicalQuery(query);
  const timestamp = String(Math.floor(Date.now() / 1000));
  const nonce = randomBytes(16).toString('hex');

  const stringToSign = [method, fullPath, queryString, timestamp, nonce, createHash('sha256').update(body).digest('hex')].join('\n');
  const headers = {
    Accept: 'application/json',
    'X-App-Id': APP_ID,
    'X-Timestamp': timestamp,
    'X-Nonce': nonce,
    'X-Signature': createHmac('sha256', APP_SECRET).update(stringToSign).digest('hex'),
  };
  if (body.length > 0) headers['Content-Type'] = contentType;

  const url = API_ORIGIN + fullPath + (queryString ? `?${queryString}` : '');
  const response = await fetch(url, { method, headers, body: body.length > 0 ? body : undefined });
  return [response.status, await response.json()];
}

const json = (data) => Buffer.from(JSON.stringify(data), 'utf8');

// 1. 上传签名证明材料：请求体为图片原始字节，slot / position 为查询参数并参与签名
let [status, result] = await openApiRequest('POST', '/sms/signatures/files', {
  query: { slot: 'other', position: 0 },
  body: readFileSync('proof.jpg'),
  contentType: 'image/jpeg',
});
console.log(status, result);
const fileToken = result?.data?.file_token ?? '';

// 2. 提交签名申请：qualification_id 取「资质列表」中 usable_for_signature 为 true 的资质
console.log(await openApiRequest('POST', '/sms/signatures', { body: json({
  qualification_id: 8,
  content: '示例科技',
  sign_source: 1,
  scene: '用于向注册用户发送登录验证码与订单通知',
  files: { other: [fileToken] },
}) }));

// 3. 提交模板申请：signature_id 可用本人已通过的签名或平台共享签名
[status, result] = await openApiRequest('POST', '/sms/templates/applications', { body: json({
  name: '登录验证码',
  channel_type: 'CN_OTP',
  signature_id: 23,
  content: '您的验证码为${code}，5分钟内有效，请勿泄露给他人。',
}) });
console.log(status, result);

// 4. 查询模板审核结果：status 为 approved 后，send_options 给出发送用的 template_variant_id 与 signature_id
if (status === 201) {
  console.log(await openApiRequest('GET', `/sms/templates/applications/${result.data.id}`));
}

#!/usr/bin/env bash
# 短信签名 / 模板申请示例（bash、curl、openssl）
set -euo pipefail

APP_ID='你的 AppId'
APP_SECRET='你的 AppSecret' # 只保存在服务端，切勿写进网页、小程序或 App
API_ORIGIN='https://am.siyun223.com'
API_PREFIX='/api/open/v1'

# 签名并发送请求：open_api_request 方法 路径 规范查询串 请求体文件 Content-Type
# 规范查询串需按参数名升序、RFC 3986 编码后传入；请求体放在文件中，按原始字节计算 SHA256
open_api_request() {
  local method="$1" path="$2" query="${3:-}" body_file="${4:-}" content_type="${5:-application/json}"
  local full_path="${API_PREFIX}${path}"
  local timestamp nonce body_hash signature url
  timestamp="$(date +%s)"
  nonce="$(openssl rand -hex 16)"
  if [ -n "$body_file" ]; then
    body_hash="$(openssl dgst -sha256 -hex < "$body_file" | sed 's/^.* //')"
  else
    body_hash="$(printf '' | openssl dgst -sha256 -hex | sed 's/^.* //')"
  fi
  signature="$(printf '%s\n%s\n%s\n%s\n%s\n%s' "$method" "$full_path" "$query" "$timestamp" "$nonce" "$body_hash" \
    | openssl dgst -sha256 -hmac "$APP_SECRET" -hex | sed 's/^.* //')"
  url="${API_ORIGIN}${full_path}${query:+?$query}"

  local args=(-sS -X "$method" "$url"
    -H 'Accept: application/json'
    -H "X-App-Id: ${APP_ID}" -H "X-Timestamp: ${timestamp}" -H "X-Nonce: ${nonce}" -H "X-Signature: ${signature}")
  if [ -n "$body_file" ]; then
    args+=(-H "Content-Type: ${content_type}" --data-binary "@${body_file}")
  fi
  curl "${args[@]}"
  echo
}

# 1. 上传签名证明材料：请求体为图片原始字节，slot / position 为查询参数并参与签名
open_api_request POST /sms/signatures/files 'position=0&slot=other' proof.jpg image/jpeg

# 2. 提交签名申请：把上一步返回的 file_token 填到 files.other 中
cat > signature.json <<'JSON'
{"qualification_id":8,"content":"示例科技","sign_source":1,"scene":"用于向注册用户发送登录验证码与订单通知","files":{"other":["上一步返回的 file_token"]}}
JSON
open_api_request POST /sms/signatures '' signature.json

# 3. 提交模板申请：signature_id 可用本人已通过的签名或平台共享签名
cat > template.json <<'JSON'
{"name":"登录验证码","channel_type":"CN_OTP","signature_id":23,"content":"您的验证码为${code}，5分钟内有效，请勿泄露给他人。"}
JSON
open_api_request POST /sms/templates/applications '' template.json

# 4. 查询模板审核结果：把 70 换成上一步返回的 data.id
open_api_request GET /sms/templates/applications/70

<?php
// 人脸实名认证（基础版）调用示例（PHP 7.4 及以上，需要 curl 扩展）
// 使用「人脸实名认证服务 › 我的应用」中创建的基础版应用；签名方式与短信服务完全相同

const APP_ID = '你的 AppId';
const APP_SECRET = '你的 AppSecret'; // 只保存在服务端，切勿写进网页、小程序或 App
const API_ORIGIN = 'https://am.siyun223.com';
const API_PREFIX = '/api/open/v1';

/**
 * 签名并发送请求，返回 [HTTP 状态码, 响应数组]
 */
function openApiRequest(string $method, string $path, ?array $payload = null): array
{
    $method = strtoupper($method);
    $fullPath = API_PREFIX . $path;
    $body = $payload === null ? '' : json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
    $timestamp = (string) time();
    $nonce = bin2hex(random_bytes(16));

    // 待签名串：方法、路径、规范查询串（无查询参数时为空）、时间戳、随机串、请求体 SHA256，用 \n 连接
    $stringToSign = implode("\n", [$method, $fullPath, '', $timestamp, $nonce, hash('sha256', $body)]);
    $signature = hash_hmac('sha256', $stringToSign, APP_SECRET);

    $headers = [
        'Accept: application/json',
        'X-App-Id: ' . APP_ID,
        'X-Timestamp: ' . $timestamp,
        'X-Nonce: ' . $nonce,
        'X-Signature: ' . $signature,
    ];

    $ch = curl_init(API_ORIGIN . $fullPath);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
    curl_setopt($ch, CURLOPT_TIMEOUT, 20); // 人脸认证需要调用权威库，超时时间建议不少于 15 秒
    if ($payload !== null) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POSTFIELDS, $body); // 发送的必须是参与签名的同一个字符串
    }
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

    $response = curl_exec($ch);
    if ($response === false) {
        throw new RuntimeException('请求失败：' . curl_error($ch));
    }

    return [(int) curl_getinfo($ch, CURLINFO_HTTP_CODE), json_decode($response, true)];
}

// 1. 查询余额与可用次数
[$status, $result] = openApiRequest('GET', '/face/basic/account/balance');
echo $status, ' ', json_encode($result, JSON_UNESCAPED_UNICODE), PHP_EOL;

// 2. 发起认证：图片建议先压缩到约 1280×720 的 JPEG；biz_no 建议使用业务单号，重试时保持不变
[$status, $result] = openApiRequest('POST', '/face/basic/verify', [
    'name' => '张三',
    'id_card_number' => '11010519491231002X',
    'image' => base64_encode(file_get_contents(__DIR__ . '/face.jpg')), // 不带 data:image 前缀
    'biz_no' => 'kyc-20261008-0001',
    'liveness_control' => 'NORMAL',
    'spoofing_control' => 'NORMAL',
]);
echo $status, ' ', json_encode($result, JSON_UNESCAPED_UNICODE), PHP_EOL;

if ($status === 200) {
    // 是否通过以 data.passed 为准，未通过的原因见 data.result_code 与 data.result_msg
    echo $result['data']['passed'] ? '认证通过' : '认证未通过：' . $result['data']['result_msg'], PHP_EOL;

    // 3. 按平台流水号查询认证结果
    [$status, $result] = openApiRequest('GET', '/face/basic/verifications/' . $result['data']['verify_no']);
    echo $status, ' ', json_encode($result, JSON_UNESCAPED_UNICODE), PHP_EOL;
}

# 人脸实名认证（基础版）调用示例（Python 3.6 及以上，只使用标准库）
# 使用「人脸实名认证服务 › 我的应用」中创建的基础版应用；签名方式与短信服务完全相同
import base64
import hashlib
import hmac
import json
import secrets
import time
import urllib.error
import urllib.request

APP_ID = "你的 AppId"
APP_SECRET = "你的 AppSecret"  # 只保存在服务端，切勿写进网页、小程序或 App
API_ORIGIN = "https://am.siyun223.com"
API_PREFIX = "/api/open/v1"


def open_api_request(method, path, payload=None):
    """签名并发送请求，返回 (HTTP 状态码, 响应内容)"""
    method = method.upper()
    full_path = API_PREFIX + path
    body = b"" if payload is None else json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
    timestamp = str(int(time.time()))
    nonce = secrets.token_hex(16)

    # 待签名串：方法、路径、规范查询串（无查询参数时为空）、时间戳、随机串、请求体 SHA256，用 \n 连接
    string_to_sign = "\n".join([method, full_path, "", timestamp, nonce, hashlib.sha256(body).hexdigest()])
    signature = hmac.new(APP_SECRET.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()

    headers = {
        "Accept": "application/json",
        "X-App-Id": APP_ID,
        "X-Timestamp": timestamp,
        "X-Nonce": nonce,
        "X-Signature": signature,
    }
    if payload is not None:
        headers["Content-Type"] = "application/json"

    request = urllib.request.Request(
        API_ORIGIN + full_path,
        data=body if payload is not None else None,  # 发送的必须是参与签名的同一份字节
        headers=headers,
        method=method,
    )
    try:
        # 人脸认证需要调用权威库，超时时间建议不少于 15 秒
        with urllib.request.urlopen(request, timeout=20) as response:
            return response.status, _parse(response.read())
    except urllib.error.HTTPError as error:
        return error.code, _parse(error.read())


def _parse(raw):
    try:
        return json.loads(raw.decode("utf-8"))
    except ValueError:
        return raw.decode("utf-8", "replace")


if __name__ == "__main__":
    # 1. 查询余额与可用次数
    print(open_api_request("GET", "/face/basic/account/balance"))

    # 2. 发起认证：图片建议先压缩到约 1280×720 的 JPEG；biz_no 建议使用业务单号，重试时保持不变
    with open("face.jpg", "rb") as image_file:
        image = base64.b64encode(image_file.read()).decode("ascii")  # 不带 data:image 前缀

    status, result = open_api_request("POST", "/face/basic/verify", {
        "name": "张三",
        "id_card_number": "11010519491231002X",
        "image": image,
        "biz_no": "kyc-20261008-0001",
        "liveness_control": "NORMAL",
        "spoofing_control": "NORMAL",
    })
    print(status, result)

    if status == 200 and isinstance(result, dict):
        data = result["data"]
        # 是否通过以 data.passed 为准，未通过的原因见 data.result_code 与 data.result_msg
        print("认证通过" if data["passed"] else "认证未通过：" + data["result_msg"])

        # 3. 按平台流水号查询认证结果
        print(open_api_request("GET", "/face/basic/verifications/" + data["verify_no"]))

// 人脸实名认证（基础版）调用示例（Java 11 及以上，只使用 JDK 标准库）
// 使用「人脸实名认证服务 › 我的应用」中创建的基础版应用；签名方式与短信服务完全相同
// 保存为 FaceVerifyDemo.java，执行：javac -encoding UTF-8 FaceVerifyDemo.java && java FaceVerifyDemo
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.security.MessageDigest;
import java.security.SecureRandom;
import java.time.Duration;
import java.util.Base64;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class FaceVerifyDemo {
    private static final String APP_ID = "你的 AppId";
    private static final String APP_SECRET = "你的 AppSecret"; // 只保存在服务端，切勿写进网页、小程序或 App
    private static final String API_ORIGIN = "https://am.siyun223.com";
    private static final String API_PREFIX = "/api/open/v1";
    private static final HttpClient CLIENT = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(5)).build();
    private static final SecureRandom RANDOM = new SecureRandom();

    public static void main(String[] args) throws Exception {
        // 1. 查询余额与可用次数
        HttpResponse<String> balance = request("GET", "/face/basic/account/balance", null);
        System.out.println(balance.statusCode() + " " + balance.body());

        // 2. 发起认证：图片建议先压缩到约 1280×720 的 JPEG；biz_no 建议使用业务单号，重试时保持不变
        // 请求体可以用 Jackson、Gson 等生成，签名与发送必须使用同一个字符串
        String image = Base64.getEncoder().encodeToString(Files.readAllBytes(Path.of("face.jpg"))); // 不带 data:image 前缀
        String body = "{\"name\":\"张三\",\"id_card_number\":\"11010519491231002X\","
                + "\"image\":\"" + image + "\",\"biz_no\":\"kyc-20261008-0001\","
                + "\"liveness_control\":\"NORMAL\",\"spoofing_control\":\"NORMAL\"}";
        HttpResponse<String> verified = request("POST", "/face/basic/verify", body);
        System.out.println(verified.statusCode() + " " + verified.body());

        // 3. 按平台流水号查询认证结果（示例用正则提取 verify_no，生产代码请用 JSON 库解析，并以 data.passed 判断是否通过）
        Matcher matcher = Pattern.compile("\"verify_no\":\"(FV\\d{22})\"").matcher(verified.body());
        if (verified.statusCode() == 200 && matcher.find()) {
            HttpResponse<String> record = request("GET", "/face/basic/verifications/" + matcher.group(1), null);
            System.out.println(record.statusCode() + " " + record.body());
        }
    }

    /** 签名并发送请求 */
    static HttpResponse<String> request(String method, String path, String body) throws Exception {
        String fullPath = API_PREFIX + path;
        String payload = body == null ? "" : body;
        String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
        String nonce = randomHex(16);

        // 待签名串：方法、路径、规范查询串（无查询参数时为空）、时间戳、随机串、请求体 SHA256，用 \n 连接
        String stringToSign = String.join("\n", method, fullPath, "", timestamp, nonce, sha256Hex(payload));

        HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create(API_ORIGIN + fullPath))
                .timeout(Duration.ofSeconds(20)) // 人脸认证需要调用权威库，超时时间建议不少于 15 秒
                .header("Accept", "application/json")
                .header("X-App-Id", APP_ID)
                .header("X-Timestamp", timestamp)
                .header("X-Nonce", nonce)
                .header("X-Signature", hmacSha256Hex(APP_SECRET, stringToSign));
        if (body == null) {
            builder.method(method, HttpRequest.BodyPublishers.noBody());
        } else {
            builder.header("Content-Type", "application/json")
                    .method(method, HttpRequest.BodyPublishers.ofString(payload, StandardCharsets.UTF_8));
        }

        return CLIENT.send(builder.build(), HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
    }

    static String sha256Hex(String value) throws Exception {
        return toHex(MessageDigest.getInstance("SHA-256").digest(value.getBytes(StandardCharsets.UTF_8)));
    }

    static String hmacSha256Hex(String secret, String value) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        return toHex(mac.doFinal(value.getBytes(StandardCharsets.UTF_8)));
    }

    static String randomHex(int bytes) {
        byte[] buffer = new byte[bytes];
        RANDOM.nextBytes(buffer);
        return toHex(buffer);
    }

    static String toHex(byte[] bytes) {
        StringBuilder hex = new StringBuilder(bytes.length * 2);
        for (byte b : bytes) {
            hex.append(String.format("%02x", b));
        }
        return hex.toString();
    }
}

// 人脸实名认证（基础版）调用示例（Node.js 18 及以上，使用内置 fetch 与 crypto，无需安装依赖）
// 使用「人脸实名认证服务 › 我的应用」中创建的基础版应用；签名方式与短信服务完全相同
// 保存为 face-verify-demo.mjs，执行：node face-verify-demo.mjs
import { createHash, createHmac, randomBytes } from 'node:crypto';
import { readFileSync } from 'node:fs';

const APP_ID = '你的 AppId';
const APP_SECRET = '你的 AppSecret'; // 只保存在服务端，切勿写进网页、小程序或 App
const API_ORIGIN = 'https://am.siyun223.com';
const API_PREFIX = '/api/open/v1';

/** 签名并发送请求，返回 { status, data } */
async function openApiRequest(method, path, payload = null) {
  const fullPath = API_PREFIX + path;
  const body = payload === null ? '' : JSON.stringify(payload);
  const timestamp = String(Math.floor(Date.now() / 1000));
  const nonce = randomBytes(16).toString('hex');

  // 待签名串：方法、路径、规范查询串（无查询参数时为空）、时间戳、随机串、请求体 SHA256，用 \n 连接
  const bodyHash = createHash('sha256').update(body, 'utf8').digest('hex');
  const stringToSign = [method, fullPath, '', timestamp, nonce, bodyHash].join('\n');
  const signature = createHmac('sha256', APP_SECRET).update(stringToSign, 'utf8').digest('hex');

  const headers = {
    Accept: 'application/json',
    'X-App-Id': APP_ID,
    'X-Timestamp': timestamp,
    'X-Nonce': nonce,
    'X-Signature': signature,
  };
  if (payload !== null) {
    headers['Content-Type'] = 'application/json';
  }

  const response = await fetch(API_ORIGIN + fullPath, {
    method,
    headers,
    body: payload === null ? undefined : body, // 发送的必须是参与签名的同一个字符串
    signal: AbortSignal.timeout(20000), // 人脸认证需要调用权威库，超时时间建议不少于 15 秒
  });
  const text = await response.text();
  let data = text;
  try {
    data = JSON.parse(text);
  } catch {
    // 非 JSON 响应原样返回
  }
  return { status: response.status, data };
}

// 1. 查询余额与可用次数
console.log(JSON.stringify(await openApiRequest('GET', '/face/basic/account/balance')));

// 2. 发起认证：图片建议先压缩到约 1280×720 的 JPEG；biz_no 建议使用业务单号，重试时保持不变
const verified = await openApiRequest('POST', '/face/basic/verify', {
  name: '张三',
  id_card_number: '11010519491231002X',
  image: readFileSync('face.jpg').toString('base64'), // 不带 data:image 前缀
  biz_no: 'kyc-20261008-0001',
  liveness_control: 'NORMAL',
  spoofing_control: 'NORMAL',
});
console.log(JSON.stringify(verified));

if (verified.status === 200 && verified.data?.data) {
  const result = verified.data.data;
  // 是否通过以 data.passed 为准，未通过的原因见 data.result_code 与 data.result_msg
  console.log(result.passed ? '认证通过' : `认证未通过：${result.result_msg}`);

  // 3. 按平台流水号查询认证结果
  console.log(JSON.stringify(await openApiRequest('GET', `/face/basic/verifications/${result.verify_no}`)));
}

#!/usr/bin/env bash
# 人脸实名认证（基础版）调用示例（bash、curl、openssl 与 base64）
# 使用「人脸实名认证服务 › 我的应用」中创建的基础版应用；签名方式与短信服务完全相同
# 保存为 face-verify-demo.sh，执行：bash face-verify-demo.sh
set -euo pipefail

APP_ID='你的 AppId'
APP_SECRET='你的 AppSecret'   # 只保存在服务端，切勿写进网页、小程序或 App
API_ORIGIN='https://am.siyun223.com'
API_PREFIX='/api/open/v1'

# 用法：open_api_request 方法 路径 [JSON 请求体文件]
# 图片的 Base64 较长，请求体写入文件后再签名和发送，避免超出命令行参数长度
open_api_request() {
  local method="$1" path="${API_PREFIX}$2" body_file="${3:-}"
  local timestamp nonce body_hash signature
  timestamp=$(date +%s)
  nonce=$(openssl rand -hex 16)
  if [ -n "$body_file" ]; then
    body_hash=$(openssl dgst -sha256 -hex < "$body_file" | awk '{print $NF}')
  else
    body_hash=$(printf '' | openssl dgst -sha256 -hex | awk '{print $NF}')
  fi
  # 待签名串：方法、路径、规范查询串（无查询参数时为空行）、时间戳、随机串、请求体 SHA256
  signature=$(printf '%s\n%s\n\n%s\n%s\n%s' "$method" "$path" "$timestamp" "$nonce" "$body_hash" \
    | openssl dgst -sha256 -hmac "$APP_SECRET" -hex | awk '{print $NF}')

  # 人脸认证需要调用权威库，超时时间建议不少于 15 秒
  local args=(-sS -X "$method" "${API_ORIGIN}${path}" --max-time 20
    -H 'Accept: application/json'
    -H "X-App-Id: ${APP_ID}"
    -H "X-Timestamp: ${timestamp}"
    -H "X-Nonce: ${nonce}"
    -H "X-Signature: ${signature}"
    -w '\nHTTP %{http_code}\n')
  if [ -n "$body_file" ]; then
    args+=(-H 'Content-Type: application/json' --data-binary "@${body_file}")
  fi
  curl "${args[@]}"
}

# 1. 查询余额与可用次数
open_api_request GET /face/basic/account/balance

# 2. 发起认证：图片建议先压缩到约 1280×720 的 JPEG；biz_no 建议使用业务单号，重试时保持不变
body_file=$(mktemp)
trap 'rm -f "$body_file"' EXIT
image=$(base64 < face.jpg | tr -d '\n')   # 不带 data:image 前缀
printf '{"name":"%s","id_card_number":"%s","image":"%s","biz_no":"%s","liveness_control":"NORMAL","spoofing_control":"NORMAL"}' \
  '张三' '11010519491231002X' "$image" 'kyc-20261008-0001' > "$body_file"
open_api_request POST /face/basic/verify "$body_file"

# 3. 按平台流水号查询认证结果：把认证接口返回的 data.verify_no 填到路径末尾
# open_api_request GET /face/basic/verifications/替换为verify_no

<?php
// 人脸实名认证（基础版）H5 采集页示例（PHP 7.4 及以上，需要 curl 扩展）
// 一、创建认证会话，把 h5_url 交给用户打开；二、在 notify_url 对应的接口中验签异步通知

const APP_ID = '你的 AppId';
const APP_SECRET = '你的 AppSecret'; // 只保存在服务端，切勿写进网页、小程序或 App
const API_ORIGIN = 'https://am.siyun223.com';
const API_PREFIX = '/api/open/v1';

/** 签名并发送请求，返回 [HTTP 状态码, 响应数组]（与人脸实名认证示例相同） */
function openApiRequest(string $method, string $path, ?array $payload = null): array
{
    $fullPath = API_PREFIX . $path;
    $body = $payload === null ? '' : json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
    $timestamp = (string) time();
    $nonce = bin2hex(random_bytes(16));
    $stringToSign = implode("\n", [$method, $fullPath, '', $timestamp, $nonce, hash('sha256', $body)]);

    $headers = [
        'Accept: application/json',
        'Content-Type: application/json',
        'X-App-Id: ' . APP_ID,
        'X-Timestamp: ' . $timestamp,
        'X-Nonce: ' . $nonce,
        'X-Signature: ' . hash_hmac('sha256', $stringToSign, APP_SECRET),
    ];
    $ch = curl_init(API_ORIGIN . $fullPath);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 15,
        CURLOPT_HTTPHEADER => $headers,
    ]);
    if ($payload !== null) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
    }
    $response = curl_exec($ch);
    if ($response === false) {
        throw new RuntimeException('请求失败：' . curl_error($ch));
    }

    return [(int) curl_getinfo($ch, CURLINFO_HTTP_CODE), json_decode($response, true)];
}

// ==================== 一、创建认证会话 ====================
// return_url、notify_url 的域名必须是应用登记的业务域名或其子域名
[$status, $result] = openApiRequest('POST', '/face/basic/sessions', [
    'name' => '张三',
    'id_card_number' => '11010519491231002X',
    'biz_no' => 'kyc-20261008-0101',       // 每个会话使用新的业务单号
    'return_url' => 'https://www.example.com/kyc/return',
    'notify_url' => 'https://api.example.com/kyc/notify',
    'max_attempts' => 3,
]);
if ($status === 201) {
    // 把 h5_url 交给用户打开（跳转、短信或二维码），保存 session_no 用于查询
    echo $result['data']['session_no'], ' ', $result['data']['h5_url'], PHP_EOL;
} else {
    echo $status, ' ', $result['error_code'] ?? '', ' ', $result['message'] ?? '', PHP_EOL;
}

// ==================== 二、验签异步通知（notify_url 对应的接口） ====================
/**
 * 校验平台发来的通知，通过返回解析后的数组，失败返回 null。
 * 路径取 notify_url 的 path；notify_url 带查询参数时，按规范查询串参与签名（见「签名方法」），这里假设不带。
 */
function verifyFaceNotify(string $path, array $headers, string $rawBody): ?array
{
    $timestamp = $headers['x-timestamp'] ?? '';
    $nonce = $headers['x-nonce'] ?? '';
    $signature = $headers['x-signature'] ?? '';
    if (($headers['x-app-id'] ?? '') !== APP_ID || abs(time() - (int) $timestamp) > 300) {
        return null;
    }
    $stringToSign = implode("\n", ['POST', $path, '', $timestamp, $nonce, hash('sha256', $rawBody)]);
    if (!hash_equals(hash_hmac('sha256', $stringToSign, APP_SECRET), $signature)) {
        return null;
    }
    // 建议再用 Redis 等记录 nonce，5 分钟内重复的直接拒绝，防止重放

    return json_decode($rawBody, true);
}

// 在通知接口中：
// $headers = array_change_key_case(getallheaders(), CASE_LOWER);
// $notice = verifyFaceNotify('/kyc/notify', $headers, file_get_contents('php://input'));
// if ($notice === null) { http_response_code(401); exit; }
// $data = $notice['data'];   // 按 session_no 去重；data.passed 为 true 表示认证通过
// http_response_code(200);   // 返回任意 2xx 即视为通知成功

# 人脸实名认证（基础版）H5 采集页示例（Python 3.6 及以上，只使用标准库）
# 一、创建认证会话，把 h5_url 交给用户打开；二、在 notify_url 对应的接口中验签异步通知
import hashlib
import hmac
import json
import secrets
import time
import urllib.error
import urllib.request

APP_ID = "你的 AppId"
APP_SECRET = "你的 AppSecret"  # 只保存在服务端，切勿写进网页、小程序或 App
API_ORIGIN = "https://am.siyun223.com"
API_PREFIX = "/api/open/v1"


def sign(method, path, timestamp, nonce, body):
    """待签名串：方法、路径、规范查询串（无查询参数时为空）、时间戳、随机串、请求体 SHA256"""
    string_to_sign = "\n".join([method, path, "", timestamp, nonce, hashlib.sha256(body).hexdigest()])
    return hmac.new(APP_SECRET.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()


def open_api_request(method, path, payload=None):
    full_path = API_PREFIX + path
    body = b"" if payload is None else json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
    timestamp = str(int(time.time()))
    nonce = secrets.token_hex(16)
    request = urllib.request.Request(API_ORIGIN + full_path, data=body if payload is not None else None, method=method, headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "X-App-Id": APP_ID,
        "X-Timestamp": timestamp,
        "X-Nonce": nonce,
        "X-Signature": sign(method, full_path, timestamp, nonce, body),
    })
    try:
        with urllib.request.urlopen(request, timeout=15) as response:
            return response.status, json.loads(response.read().decode("utf-8"))
    except urllib.error.HTTPError as error:
        return error.code, json.loads(error.read().decode("utf-8"))


def verify_notify(path, headers, raw_body):
    """校验平台发来的通知（headers 的键为小写），通过返回解析后的 dict，失败返回 None。
    路径取 notify_url 的 path；notify_url 带查询参数时按规范查询串参与签名，这里假设不带。"""
    timestamp = headers.get("x-timestamp", "")
    if headers.get("x-app-id") != APP_ID or not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
        return None
    expected = sign("POST", path, timestamp, headers.get("x-nonce", ""), raw_body)
    if not hmac.compare_digest(expected, headers.get("x-signature", "")):
        return None
    # 建议再记录 nonce，5 分钟内重复的直接拒绝，防止重放
    return json.loads(raw_body.decode("utf-8"))


if __name__ == "__main__":
    # 一、创建认证会话：return_url、notify_url 的域名必须是应用登记的业务域名或其子域名
    status, result = open_api_request("POST", "/face/basic/sessions", {
        "name": "张三",
        "id_card_number": "11010519491231002X",
        "biz_no": "kyc-20261008-0101",
        "return_url": "https://www.example.com/kyc/return",
        "notify_url": "https://api.example.com/kyc/notify",
        "max_attempts": 3,
    })
    if status == 201:
        print(result["data"]["session_no"], result["data"]["h5_url"])  # 把 h5_url 交给用户打开
    else:
        print(status, result.get("error_code"), result.get("message"))

# 二、在通知接口中（以 Flask 为例）：
# notice = verify_notify("/kyc/notify", {k.lower(): v for k, v in request.headers.items()}, request.get_data())
# if notice is None: return "", 401
# data = notice["data"]  # 按 session_no 去重；data["passed"] 为 True 表示认证通过
# return "", 200        # 返回任意 2xx 即视为通知成功

// 人脸实名认证（基础版）H5 采集页示例（Java 11 及以上，只使用 JDK 标准库）
// 一、创建认证会话，把 h5_url 交给用户打开；二、在 8080 端口接收异步通知并验签
// 保存为 FaceH5Demo.java，执行：javac -encoding UTF-8 FaceH5Demo.java && java FaceH5Demo
import com.sun.net.httpserver.Headers;
import com.sun.net.httpserver.HttpServer;
import java.net.InetSocketAddress;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.SecureRandom;
import java.time.Duration;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class FaceH5Demo {
    static final String APP_ID = "你的 AppId";
    static final String APP_SECRET = "你的 AppSecret"; // 只保存在服务端，切勿写进网页、小程序或 App
    static final String API_ORIGIN = "https://am.siyun223.com";
    static final String API_PREFIX = "/api/open/v1";

    static String hex(byte[] bytes) {
        StringBuilder sb = new StringBuilder(bytes.length * 2);
        for (byte b : bytes) {
            sb.append(Character.forDigit((b >> 4) & 0xF, 16)).append(Character.forDigit(b & 0xF, 16));
        }
        return sb.toString();
    }

    // 待签名串：方法、路径、规范查询串（无查询参数时为空）、时间戳、随机串、请求体 SHA256
    static String sign(String method, String path, String timestamp, String nonce, byte[] body) throws Exception {
        String bodyHash = hex(MessageDigest.getInstance("SHA-256").digest(body));
        String stringToSign = String.join("\n", method, path, "", timestamp, nonce, bodyHash);
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(APP_SECRET.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        return hex(mac.doFinal(stringToSign.getBytes(StandardCharsets.UTF_8)));
    }

    // 校验平台发来的通知；路径取 notify_url 的 path，notify_url 带查询参数时按规范查询串参与签名，这里假设不带
    static boolean verifyNotify(String path, Headers headers, byte[] rawBody) throws Exception {
        String timestamp = headers.getFirst("X-Timestamp");
        String nonce = headers.getFirst("X-Nonce");
        String signature = headers.getFirst("X-Signature");
        if (!APP_ID.equals(headers.getFirst("X-App-Id")) || timestamp == null || !timestamp.matches("\\d{1,12}")
                || Math.abs(System.currentTimeMillis() / 1000 - Long.parseLong(timestamp)) > 300
                || nonce == null || signature == null) {
            return false;
        }
        byte[] expected = sign("POST", path, timestamp, nonce, rawBody).getBytes(StandardCharsets.UTF_8);
        // 常量时间比较；建议再记录 nonce，5 分钟内重复的直接拒绝，防止重放
        return MessageDigest.isEqual(expected, signature.getBytes(StandardCharsets.UTF_8));
    }

    public static void main(String[] args) throws Exception {
        // ==================== 一、创建认证会话 ====================
        // return_url、notify_url 的域名必须是应用登记的业务域名或其子域名；biz_no 每个会话使用新的业务单号
        String path = API_PREFIX + "/face/basic/sessions";
        String json = "{\"name\":\"张三\",\"id_card_number\":\"11010519491231002X\",\"biz_no\":\"kyc-20261008-0101\","
                + "\"return_url\":\"https://www.example.com/kyc/return\","
                + "\"notify_url\":\"https://api.example.com/kyc/notify\",\"max_attempts\":3}";
        byte[] body = json.getBytes(StandardCharsets.UTF_8);
        String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
        byte[] random = new byte[16];
        new SecureRandom().nextBytes(random);
        String nonce = hex(random);

        HttpRequest request = HttpRequest.newBuilder(URI.create(API_ORIGIN + path))
                .timeout(Duration.ofSeconds(15))
                .header("Accept", "application/json")
                .header("Content-Type", "application/json")
                .header("X-App-Id", APP_ID)
                .header("X-Timestamp", timestamp)
                .header("X-Nonce", nonce)
                .header("X-Signature", sign("POST", path, timestamp, nonce, body))
                .POST(HttpRequest.BodyPublishers.ofByteArray(body))
                .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
                .send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        // HTTP 201 时 data.h5_url 为采集页链接，交给用户打开；保存 data.session_no 用于查询
        System.out.println(response.statusCode() + " " + response.body());

        // ==================== 二、接收异步通知并验签 ====================
        HttpServer server = HttpServer.create(new InetSocketAddress(8080), 0);
        server.createContext("/kyc/notify", exchange -> {
            byte[] raw = exchange.getRequestBody().readAllBytes();
            boolean ok;
            try {
                ok = "POST".equals(exchange.getRequestMethod())
                        && verifyNotify("/kyc/notify", exchange.getRequestHeaders(), raw);
            } catch (Exception e) {
                ok = false;
            }
            if (ok) {
                // 按 session_no 去重；解析 JSON 后 data.passed 为 true 表示认证通过
                System.out.println(new String(raw, StandardCharsets.UTF_8));
            }
            exchange.sendResponseHeaders(ok ? 200 : 401, -1); // 返回任意 2xx 即视为通知成功
            exchange.close();
        });
        server.start();
    }
}

// 人脸实名认证（基础版）H5 采集页示例（Node.js 18 及以上，使用内置 fetch、crypto 与 http，无需安装依赖）
// 一、创建认证会话，把 h5_url 交给用户打开；二、在 notify_url 对应的接口中验签异步通知
import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
import { createServer } from 'node:http';

const APP_ID = '你的 AppId';
const APP_SECRET = '你的 AppSecret'; // 只保存在服务端，切勿写进网页、小程序或 App
const API_ORIGIN = 'https://am.siyun223.com';
const API_PREFIX = '/api/open/v1';

// 待签名串：方法、路径、规范查询串（无查询参数时为空）、时间戳、随机串、请求体 SHA256
function sign(method, path, timestamp, nonce, body) {
  const bodyHash = createHash('sha256').update(body).digest('hex');
  const stringToSign = [method, path, '', timestamp, nonce, bodyHash].join('\n');
  return createHmac('sha256', APP_SECRET).update(stringToSign, 'utf8').digest('hex');
}

// ==================== 一、创建认证会话 ====================
const path = API_PREFIX + '/face/basic/sessions';
const body = JSON.stringify({
  name: '张三',
  id_card_number: '11010519491231002X',
  biz_no: 'kyc-20261008-0101',
  return_url: 'https://www.example.com/kyc/return', // 域名必须是应用登记的业务域名或其子域名
  notify_url: 'https://api.example.com/kyc/notify',
  max_attempts: 3,
});
const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = randomBytes(16).toString('hex');
const response = await fetch(API_ORIGIN + path, {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    'X-App-Id': APP_ID,
    'X-Timestamp': timestamp,
    'X-Nonce': nonce,
    'X-Signature': sign('POST', path, timestamp, nonce, body),
  },
  body,
  signal: AbortSignal.timeout(15000),
});
const created = await response.json();
console.log(response.status, response.status === 201 ? created.data.h5_url : created); // 把 h5_url 交给用户打开

// ==================== 二、验签异步通知 ====================
// 路径取 notify_url 的 path；notify_url 带查询参数时按规范查询串参与签名，这里假设不带
function verifyNotify(notifyPath, headers, rawBody) {
  const ts = String(headers['x-timestamp'] || '');
  if (headers['x-app-id'] !== APP_ID || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
    return null;
  }
  const expected = Buffer.from(sign('POST', notifyPath, ts, String(headers['x-nonce'] || ''), rawBody));
  const actual = Buffer.from(String(headers['x-signature'] || ''));
  if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) {
    return null;
  }
  return JSON.parse(rawBody.toString('utf8')); // 建议再记录 nonce 防止重放
}

createServer((req, res) => {
  const chunks = [];
  req.on('data', (chunk) => chunks.push(chunk));
  req.on('end', () => {
    const notice = req.method === 'POST' && req.url === '/kyc/notify'
      ? verifyNotify('/kyc/notify', req.headers, Buffer.concat(chunks))
      : null;
    if (notice === null) {
      res.writeHead(401).end();
      return;
    }
    // 按 session_no 去重；notice.data.passed 为 true 表示认证通过
    console.log(notice.event, notice.data.session_no, notice.data.status);
    res.writeHead(200).end('ok'); // 返回任意 2xx 即视为通知成功
  });
}).listen(8080);

#!/usr/bin/env bash
# 人脸实名认证（基础版）H5 采集页示例（bash、curl 与 openssl）
# 一、创建认证会话，把 h5_url 交给用户打开；二、verify_notify 演示通知接口如何验签
# 保存为 face-h5-demo.sh，执行：bash face-h5-demo.sh
set -euo pipefail

APP_ID='你的 AppId'
APP_SECRET='你的 AppSecret'   # 只保存在服务端，切勿写进网页、小程序或 App
API_ORIGIN='https://am.siyun223.com'
API_PREFIX='/api/open/v1'

# 用法：sign 方法 路径 时间戳 随机串 请求体文件
# 待签名串：方法、路径、规范查询串（无查询参数时为空行）、时间戳、随机串、请求体 SHA256
sign() {
  local body_hash
  body_hash=$(openssl dgst -sha256 -hex < "$5" | awk '{print $NF}')
  printf '%s\n%s\n\n%s\n%s\n%s' "$1" "$2" "$3" "$4" "$body_hash" \
    | openssl dgst -sha256 -hmac "$APP_SECRET" -hex | awk '{print $NF}'
}

# ==================== 一、创建认证会话 ====================
# return_url、notify_url 的域名必须是应用登记的业务域名或其子域名；biz_no 每个会话使用新的业务单号
body_file=$(mktemp)
trap 'rm -f "$body_file"' EXIT
printf '{"name":"%s","id_card_number":"%s","biz_no":"%s","return_url":"%s","notify_url":"%s","max_attempts":3}' \
  '张三' '11010519491231002X' 'kyc-20261008-0101' \
  'https://www.example.com/kyc/return' 'https://api.example.com/kyc/notify' > "$body_file"

path="${API_PREFIX}/face/basic/sessions"
timestamp=$(date +%s)
nonce=$(openssl rand -hex 16)
# HTTP 201 时 data.h5_url 为采集页链接，交给用户打开；保存 data.session_no 用于查询
curl -sS -X POST "${API_ORIGIN}${path}" --max-time 15 \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "X-App-Id: ${APP_ID}" \
  -H "X-Timestamp: ${timestamp}" \
  -H "X-Nonce: ${nonce}" \
  -H "X-Signature: $(sign POST "$path" "$timestamp" "$nonce" "$body_file")" \
  --data-binary "@${body_file}" \
  -w '\nHTTP %{http_code}\n'

# ==================== 二、验签异步通知 ====================
# 用法：verify_notify 通知路径 X-App-Id X-Timestamp X-Nonce X-Signature 原始请求体文件
# 通过返回 0，失败返回 1；路径取 notify_url 的 path，这里假设不带查询参数
verify_notify() {
  local now expected
  now=$(date +%s)
  [ "$2" = "$APP_ID" ] || return 1
  [[ "$3" =~ ^[0-9]{1,12}$ ]] || return 1
  [ $(( now > $3 ? now - $3 : $3 - now )) -le 300 ] || return 1
  expected=$(sign POST "$1" "$3" "$4" "$6")
  [ "$expected" = "$5" ]   # 建议再记录 nonce，5 分钟内重复的直接拒绝，防止重放
}

# 在通知接口中（请求头与原始请求体由你的 Web 服务提供），通过后返回任意 2xx 即视为通知成功：
# if verify_notify /kyc/notify "$HDR_APP_ID" "$HDR_TIMESTAMP" "$HDR_NONCE" "$HDR_SIGNATURE" notify_body.json; then
#   echo '验签通过：按 session_no 去重，data.passed 为 true 表示认证通过'
# fi

<?php
// 人脸实名认证（增强版）H5 采集页示例（PHP 7.4 及以上，需要 curl 扩展）
// 一、创建认证会话，把 h5_url 交给用户打开；二、在 notify_url 对应的接口中验签异步通知

const APP_ID = '你的 AppId';
const APP_SECRET = '你的 AppSecret'; // 只保存在服务端，切勿写进网页、小程序或 App
const API_ORIGIN = 'https://am.siyun223.com';
const API_PREFIX = '/api/open/v1';

/** 签名并发送请求，返回 [HTTP 状态码, 响应数组]（与人脸实名认证示例相同） */
function openApiRequest(string $method, string $path, ?array $payload = null): array
{
    $fullPath = API_PREFIX . $path;
    $body = $payload === null ? '' : json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
    $timestamp = (string) time();
    $nonce = bin2hex(random_bytes(16));
    $stringToSign = implode("\n", [$method, $fullPath, '', $timestamp, $nonce, hash('sha256', $body)]);

    $headers = [
        'Accept: application/json',
        'Content-Type: application/json',
        'X-App-Id: ' . APP_ID,
        'X-Timestamp: ' . $timestamp,
        'X-Nonce: ' . $nonce,
        'X-Signature: ' . hash_hmac('sha256', $stringToSign, APP_SECRET),
    ];
    $ch = curl_init(API_ORIGIN . $fullPath);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 15,
        CURLOPT_HTTPHEADER => $headers,
    ]);
    if ($payload !== null) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
    }
    $response = curl_exec($ch);
    if ($response === false) {
        throw new RuntimeException('请求失败：' . curl_error($ch));
    }

    return [(int) curl_getinfo($ch, CURLINFO_HTTP_CODE), json_decode($response, true)];
}

// ==================== 一、创建认证会话 ====================
// return_url、notify_url 的域名必须是应用登记的业务域名或其子域名
[$status, $result] = openApiRequest('POST', '/face/enhanced/sessions', [
    'name' => '张三',
    'id_card_number' => '11010519491231002X',
    'biz_no' => 'kyc-20261008-0101',       // 每个会话使用新的业务单号
    'return_url' => 'https://www.example.com/kyc/return',
    'notify_url' => 'https://api.example.com/kyc/notify',
    'max_attempts' => 3,
]);
if ($status === 201) {
    // 把 h5_url 交给用户打开（跳转、短信或二维码），保存 session_no 用于查询
    echo $result['data']['session_no'], ' ', $result['data']['h5_url'], PHP_EOL;
} else {
    echo $status, ' ', $result['error_code'] ?? '', ' ', $result['message'] ?? '', PHP_EOL;
}

// ==================== 二、验签异步通知（notify_url 对应的接口） ====================
/**
 * 校验平台发来的通知，通过返回解析后的数组，失败返回 null。
 * 路径取 notify_url 的 path；notify_url 带查询参数时，按规范查询串参与签名（见「签名方法」），这里假设不带。
 */
function verifyFaceNotify(string $path, array $headers, string $rawBody): ?array
{
    $timestamp = $headers['x-timestamp'] ?? '';
    $nonce = $headers['x-nonce'] ?? '';
    $signature = $headers['x-signature'] ?? '';
    if (($headers['x-app-id'] ?? '') !== APP_ID || abs(time() - (int) $timestamp) > 300) {
        return null;
    }
    $stringToSign = implode("\n", ['POST', $path, '', $timestamp, $nonce, hash('sha256', $rawBody)]);
    if (!hash_equals(hash_hmac('sha256', $stringToSign, APP_SECRET), $signature)) {
        return null;
    }
    // 建议再用 Redis 等记录 nonce，5 分钟内重复的直接拒绝，防止重放

    return json_decode($rawBody, true);
}

// 在通知接口中：
// $headers = array_change_key_case(getallheaders(), CASE_LOWER);
// $notice = verifyFaceNotify('/kyc/notify', $headers, file_get_contents('php://input'));
// if ($notice === null) { http_response_code(401); exit; }
// $data = $notice['data'];   // 按 session_no 去重；data.passed 为 true 表示认证通过
// http_response_code(200);   // 返回任意 2xx 即视为通知成功

# 人脸实名认证（增强版）H5 采集页示例（Python 3.6 及以上，只使用标准库）
# 一、创建认证会话，把 h5_url 交给用户打开；二、在 notify_url 对应的接口中验签异步通知
import hashlib
import hmac
import json
import secrets
import time
import urllib.error
import urllib.request

APP_ID = "你的 AppId"
APP_SECRET = "你的 AppSecret"  # 只保存在服务端，切勿写进网页、小程序或 App
API_ORIGIN = "https://am.siyun223.com"
API_PREFIX = "/api/open/v1"


def sign(method, path, timestamp, nonce, body):
    """待签名串：方法、路径、规范查询串（无查询参数时为空）、时间戳、随机串、请求体 SHA256"""
    string_to_sign = "\n".join([method, path, "", timestamp, nonce, hashlib.sha256(body).hexdigest()])
    return hmac.new(APP_SECRET.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()


def open_api_request(method, path, payload=None):
    full_path = API_PREFIX + path
    body = b"" if payload is None else json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
    timestamp = str(int(time.time()))
    nonce = secrets.token_hex(16)
    request = urllib.request.Request(API_ORIGIN + full_path, data=body if payload is not None else None, method=method, headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "X-App-Id": APP_ID,
        "X-Timestamp": timestamp,
        "X-Nonce": nonce,
        "X-Signature": sign(method, full_path, timestamp, nonce, body),
    })
    try:
        with urllib.request.urlopen(request, timeout=15) as response:
            return response.status, json.loads(response.read().decode("utf-8"))
    except urllib.error.HTTPError as error:
        return error.code, json.loads(error.read().decode("utf-8"))


def verify_notify(path, headers, raw_body):
    """校验平台发来的通知（headers 的键为小写），通过返回解析后的 dict，失败返回 None。
    路径取 notify_url 的 path；notify_url 带查询参数时按规范查询串参与签名，这里假设不带。"""
    timestamp = headers.get("x-timestamp", "")
    if headers.get("x-app-id") != APP_ID or not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
        return None
    expected = sign("POST", path, timestamp, headers.get("x-nonce", ""), raw_body)
    if not hmac.compare_digest(expected, headers.get("x-signature", "")):
        return None
    # 建议再记录 nonce，5 分钟内重复的直接拒绝，防止重放
    return json.loads(raw_body.decode("utf-8"))


if __name__ == "__main__":
    # 一、创建认证会话：return_url、notify_url 的域名必须是应用登记的业务域名或其子域名
    status, result = open_api_request("POST", "/face/enhanced/sessions", {
        "name": "张三",
        "id_card_number": "11010519491231002X",
        "biz_no": "kyc-20261008-0101",
        "return_url": "https://www.example.com/kyc/return",
        "notify_url": "https://api.example.com/kyc/notify",
        "max_attempts": 3,
    })
    if status == 201:
        print(result["data"]["session_no"], result["data"]["h5_url"])  # 把 h5_url 交给用户打开
    else:
        print(status, result.get("error_code"), result.get("message"))

# 二、在通知接口中（以 Flask 为例）：
# notice = verify_notify("/kyc/notify", {k.lower(): v for k, v in request.headers.items()}, request.get_data())
# if notice is None: return "", 401
# data = notice["data"]  # 按 session_no 去重；data["passed"] 为 True 表示认证通过
# return "", 200        # 返回任意 2xx 即视为通知成功

// 人脸实名认证（增强版）H5 采集页示例（Java 11 及以上，只使用 JDK 标准库）
// 一、创建认证会话，把 h5_url 交给用户打开；二、在 8080 端口接收异步通知并验签
// 保存为 FaceH5Demo.java，执行：javac -encoding UTF-8 FaceH5Demo.java && java FaceH5Demo
import com.sun.net.httpserver.Headers;
import com.sun.net.httpserver.HttpServer;
import java.net.InetSocketAddress;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.SecureRandom;
import java.time.Duration;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class FaceH5Demo {
    static final String APP_ID = "你的 AppId";
    static final String APP_SECRET = "你的 AppSecret"; // 只保存在服务端，切勿写进网页、小程序或 App
    static final String API_ORIGIN = "https://am.siyun223.com";
    static final String API_PREFIX = "/api/open/v1";

    static String hex(byte[] bytes) {
        StringBuilder sb = new StringBuilder(bytes.length * 2);
        for (byte b : bytes) {
            sb.append(Character.forDigit((b >> 4) & 0xF, 16)).append(Character.forDigit(b & 0xF, 16));
        }
        return sb.toString();
    }

    // 待签名串：方法、路径、规范查询串（无查询参数时为空）、时间戳、随机串、请求体 SHA256
    static String sign(String method, String path, String timestamp, String nonce, byte[] body) throws Exception {
        String bodyHash = hex(MessageDigest.getInstance("SHA-256").digest(body));
        String stringToSign = String.join("\n", method, path, "", timestamp, nonce, bodyHash);
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(APP_SECRET.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        return hex(mac.doFinal(stringToSign.getBytes(StandardCharsets.UTF_8)));
    }

    // 校验平台发来的通知；路径取 notify_url 的 path，notify_url 带查询参数时按规范查询串参与签名，这里假设不带
    static boolean verifyNotify(String path, Headers headers, byte[] rawBody) throws Exception {
        String timestamp = headers.getFirst("X-Timestamp");
        String nonce = headers.getFirst("X-Nonce");
        String signature = headers.getFirst("X-Signature");
        if (!APP_ID.equals(headers.getFirst("X-App-Id")) || timestamp == null || !timestamp.matches("\\d{1,12}")
                || Math.abs(System.currentTimeMillis() / 1000 - Long.parseLong(timestamp)) > 300
                || nonce == null || signature == null) {
            return false;
        }
        byte[] expected = sign("POST", path, timestamp, nonce, rawBody).getBytes(StandardCharsets.UTF_8);
        // 常量时间比较；建议再记录 nonce，5 分钟内重复的直接拒绝，防止重放
        return MessageDigest.isEqual(expected, signature.getBytes(StandardCharsets.UTF_8));
    }

    public static void main(String[] args) throws Exception {
        // ==================== 一、创建认证会话 ====================
        // return_url、notify_url 的域名必须是应用登记的业务域名或其子域名；biz_no 每个会话使用新的业务单号
        String path = API_PREFIX + "/face/enhanced/sessions";
        String json = "{\"name\":\"张三\",\"id_card_number\":\"11010519491231002X\",\"biz_no\":\"kyc-20261008-0101\","
                + "\"return_url\":\"https://www.example.com/kyc/return\","
                + "\"notify_url\":\"https://api.example.com/kyc/notify\",\"max_attempts\":3}";
        byte[] body = json.getBytes(StandardCharsets.UTF_8);
        String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
        byte[] random = new byte[16];
        new SecureRandom().nextBytes(random);
        String nonce = hex(random);

        HttpRequest request = HttpRequest.newBuilder(URI.create(API_ORIGIN + path))
                .timeout(Duration.ofSeconds(15))
                .header("Accept", "application/json")
                .header("Content-Type", "application/json")
                .header("X-App-Id", APP_ID)
                .header("X-Timestamp", timestamp)
                .header("X-Nonce", nonce)
                .header("X-Signature", sign("POST", path, timestamp, nonce, body))
                .POST(HttpRequest.BodyPublishers.ofByteArray(body))
                .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
                .send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        // HTTP 201 时 data.h5_url 为采集页链接，交给用户打开；保存 data.session_no 用于查询
        System.out.println(response.statusCode() + " " + response.body());

        // ==================== 二、接收异步通知并验签 ====================
        HttpServer server = HttpServer.create(new InetSocketAddress(8080), 0);
        server.createContext("/kyc/notify", exchange -> {
            byte[] raw = exchange.getRequestBody().readAllBytes();
            boolean ok;
            try {
                ok = "POST".equals(exchange.getRequestMethod())
                        && verifyNotify("/kyc/notify", exchange.getRequestHeaders(), raw);
            } catch (Exception e) {
                ok = false;
            }
            if (ok) {
                // 按 session_no 去重；解析 JSON 后 data.passed 为 true 表示认证通过
                System.out.println(new String(raw, StandardCharsets.UTF_8));
            }
            exchange.sendResponseHeaders(ok ? 200 : 401, -1); // 返回任意 2xx 即视为通知成功
            exchange.close();
        });
        server.start();
    }
}

// 人脸实名认证（增强版）H5 采集页示例（Node.js 18 及以上，使用内置 fetch、crypto 与 http，无需安装依赖）
// 一、创建认证会话，把 h5_url 交给用户打开；二、在 notify_url 对应的接口中验签异步通知
import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
import { createServer } from 'node:http';

const APP_ID = '你的 AppId';
const APP_SECRET = '你的 AppSecret'; // 只保存在服务端，切勿写进网页、小程序或 App
const API_ORIGIN = 'https://am.siyun223.com';
const API_PREFIX = '/api/open/v1';

// 待签名串：方法、路径、规范查询串（无查询参数时为空）、时间戳、随机串、请求体 SHA256
function sign(method, path, timestamp, nonce, body) {
  const bodyHash = createHash('sha256').update(body).digest('hex');
  const stringToSign = [method, path, '', timestamp, nonce, bodyHash].join('\n');
  return createHmac('sha256', APP_SECRET).update(stringToSign, 'utf8').digest('hex');
}

// ==================== 一、创建认证会话 ====================
const path = API_PREFIX + '/face/enhanced/sessions';
const body = JSON.stringify({
  name: '张三',
  id_card_number: '11010519491231002X',
  biz_no: 'kyc-20261008-0101',
  return_url: 'https://www.example.com/kyc/return', // 域名必须是应用登记的业务域名或其子域名
  notify_url: 'https://api.example.com/kyc/notify',
  max_attempts: 3,
});
const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = randomBytes(16).toString('hex');
const response = await fetch(API_ORIGIN + path, {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    'X-App-Id': APP_ID,
    'X-Timestamp': timestamp,
    'X-Nonce': nonce,
    'X-Signature': sign('POST', path, timestamp, nonce, body),
  },
  body,
  signal: AbortSignal.timeout(15000),
});
const created = await response.json();
console.log(response.status, response.status === 201 ? created.data.h5_url : created); // 把 h5_url 交给用户打开

// ==================== 二、验签异步通知 ====================
// 路径取 notify_url 的 path；notify_url 带查询参数时按规范查询串参与签名，这里假设不带
function verifyNotify(notifyPath, headers, rawBody) {
  const ts = String(headers['x-timestamp'] || '');
  if (headers['x-app-id'] !== APP_ID || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
    return null;
  }
  const expected = Buffer.from(sign('POST', notifyPath, ts, String(headers['x-nonce'] || ''), rawBody));
  const actual = Buffer.from(String(headers['x-signature'] || ''));
  if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) {
    return null;
  }
  return JSON.parse(rawBody.toString('utf8')); // 建议再记录 nonce 防止重放
}

createServer((req, res) => {
  const chunks = [];
  req.on('data', (chunk) => chunks.push(chunk));
  req.on('end', () => {
    const notice = req.method === 'POST' && req.url === '/kyc/notify'
      ? verifyNotify('/kyc/notify', req.headers, Buffer.concat(chunks))
      : null;
    if (notice === null) {
      res.writeHead(401).end();
      return;
    }
    // 按 session_no 去重；notice.data.passed 为 true 表示认证通过
    console.log(notice.event, notice.data.session_no, notice.data.status);
    res.writeHead(200).end('ok'); // 返回任意 2xx 即视为通知成功
  });
}).listen(8080);

#!/usr/bin/env bash
# 人脸实名认证（增强版）H5 采集页示例（bash、curl 与 openssl）
# 一、创建认证会话，把 h5_url 交给用户打开；二、verify_notify 演示通知接口如何验签
# 保存为 face-h5-demo.sh，执行：bash face-h5-demo.sh
set -euo pipefail

APP_ID='你的 AppId'
APP_SECRET='你的 AppSecret'   # 只保存在服务端，切勿写进网页、小程序或 App
API_ORIGIN='https://am.siyun223.com'
API_PREFIX='/api/open/v1'

# 用法：sign 方法 路径 时间戳 随机串 请求体文件
# 待签名串：方法、路径、规范查询串（无查询参数时为空行）、时间戳、随机串、请求体 SHA256
sign() {
  local body_hash
  body_hash=$(openssl dgst -sha256 -hex < "$5" | awk '{print $NF}')
  printf '%s\n%s\n\n%s\n%s\n%s' "$1" "$2" "$3" "$4" "$body_hash" \
    | openssl dgst -sha256 -hmac "$APP_SECRET" -hex | awk '{print $NF}'
}

# ==================== 一、创建认证会话 ====================
# return_url、notify_url 的域名必须是应用登记的业务域名或其子域名；biz_no 每个会话使用新的业务单号
body_file=$(mktemp)
trap 'rm -f "$body_file"' EXIT
printf '{"name":"%s","id_card_number":"%s","biz_no":"%s","return_url":"%s","notify_url":"%s","max_attempts":3}' \
  '张三' '11010519491231002X' 'kyc-20261008-0101' \
  'https://www.example.com/kyc/return' 'https://api.example.com/kyc/notify' > "$body_file"

path="${API_PREFIX}/face/enhanced/sessions"
timestamp=$(date +%s)
nonce=$(openssl rand -hex 16)
# HTTP 201 时 data.h5_url 为采集页链接，交给用户打开；保存 data.session_no 用于查询
curl -sS -X POST "${API_ORIGIN}${path}" --max-time 15 \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "X-App-Id: ${APP_ID}" \
  -H "X-Timestamp: ${timestamp}" \
  -H "X-Nonce: ${nonce}" \
  -H "X-Signature: $(sign POST "$path" "$timestamp" "$nonce" "$body_file")" \
  --data-binary "@${body_file}" \
  -w '\nHTTP %{http_code}\n'

# ==================== 二、验签异步通知 ====================
# 用法：verify_notify 通知路径 X-App-Id X-Timestamp X-Nonce X-Signature 原始请求体文件
# 通过返回 0，失败返回 1；路径取 notify_url 的 path，这里假设不带查询参数
verify_notify() {
  local now expected
  now=$(date +%s)
  [ "$2" = "$APP_ID" ] || return 1
  [[ "$3" =~ ^[0-9]{1,12}$ ]] || return 1
  [ $(( now > $3 ? now - $3 : $3 - now )) -le 300 ] || return 1
  expected=$(sign POST "$1" "$3" "$4" "$6")
  [ "$expected" = "$5" ]   # 建议再记录 nonce，5 分钟内重复的直接拒绝，防止重放
}

# 在通知接口中（请求头与原始请求体由你的 Web 服务提供），通过后返回任意 2xx 即视为通知成功：
# if verify_notify /kyc/notify "$HDR_APP_ID" "$HDR_TIMESTAMP" "$HDR_NONCE" "$HDR_SIGNATURE" notify_body.json; then
#   echo '验签通过：按 session_no 去重，data.passed 为 true 表示认证通过'
# fi