API 接口文档

发卡宝 API v1 只有两个接口：幂等核销（consume）与对账查询（query）。核销为不可自动回退的资产消耗，跨系统一致性靠「幂等单号 + 可查询 + 接入方本地订单」保证，可彻底解决“卡已烧、权益未到账”的掉单问题。

签名规则

POST: Sign = HMAC_SHA256( Secret, Timestamp + "." + 请求体原文(raw body) )
GET : Sign = HMAC_SHA256( Secret, Timestamp + "." + URL查询串原文(QUERY_STRING) )

要点：
1. POST 参与签名的是"实际发出的字节"——先 json_encode 得到 $body，签名用 $body，发送也用 $body，中间不得重排/格式化；
2. GET 的查询串自行拼接（如 http_build_query 的结果），签什么就发什么，避免 curl/代理二次编码改变顺序；
3. 签名失败返回 401 INVALID_SIGN，可用示例 Demo 对照排查。

行锁原子操作：校验 + 登记台账 + 标记已用一次完成，是整条链路唯一需要同步等待的调用（建议连接 3s / 总 6s 超时）。幂等：同 clientTxnId 重放返回相同结果。

请求参数（JSON Body）

POST /api/index.php
Content-Type: application/json
X-API-Key: 9ffa60a9c4aa4eb512312d680e2974dc
X-Timestamp: 1789502400
X-Sign: hmac_sha256(secret, "1789502400." + 请求体原文)

{"method":"consume","cardNo":"BQ7WK-T9U4W-NGRTJ","clientTxnId":"m51_20260916_3f9a27de01c8b4f5"}

查询核销台账，供超时收敛、定时对账、人工补单前核对。先按 clientTxnId 查，未命中自动回落按 cardNo 查（并可追溯卡表兜底），单参数也可查，两个都带最稳。

GET /api/index.php?clientTxnId=m51_20260916_3f9a27de01c8b4f5
（签名原文 = Timestamp + "." + "clientTxnId=m51_20260916_3f9a27de01c8b4f5"）

已核销：{"code":1,"data":{"used":true, "pid":38,"usedTxn":"m51_20260916_3f9a27de01c8b4f5","usedAt":"2026-09-16 03:21:56"}}
未核销：{"code":1,"data":{"used":false,"pid":0, "usedTxn":"","usedAt":""}}

平台不提供自动回滚（卡状态单调向前）。“本地没办成”的兜底不是退卡，而是本地重试发放。

1 本地落单 pending（生成 clientTxnId，落库成功后才发请求）
2 POST consume（唯一同步阻塞，1 次 HTTP）
   ├─ code=1 → 3
   ├─ NOT_FOUND / ALREADY_USED / REFUNDED → 订单 failed，提示换卡
   └─ 超时 / 429 / BUSY / 5xx / 鉴权错 → 保持 pending，返回"处理中"
3 本地事务：按 pid 发放权益 + 订单翻 success（同一事务，原子只翻转一次）
4 定时任务（每分钟）：扫 pending 超时单 → GET query
   ├─ used=false 超30分钟 → failed（用户可复用原单号重提）
   ├─ used=true  usedTxn==本单 → 补执行第3步（自愈）
   └─ used=true  usedTxn!=本单 → 转人工，禁止发放
5 客服通道：误核销人工 refund，卡恢复可用；你的历史单号再重放会收到 REFUNDED

<?php
class FakabaoAPI
{
    public function __construct(
        private string $baseUrl,    // 例 https://fakabao.net
        private string $apiKey,
        private string $secret,
        private int $connTimeout = 3,
        private int $timeout = 6
    ) {}

    /** 核销：['ok'=>bool,'pid'=>int,'replay'=>bool] 或 ['ok'=>false,'err'=>..,'msg'=>..] */
    public function consume(string $cardNo, string $clientTxnId): array
    {
        $body = json_encode(
            ['method' => 'consume', 'cardNo' => $cardNo, 'clientTxnId' => $clientTxnId],
            JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
        );
        return $this->request('POST', '/api/index.php', $body);
    }

    /** 对账查询：主查单号，可带卡号回落 */
    public function query(string $clientTxnId, string $cardNo = ''): array
    {
        $qs = http_build_query(array_filter(
            ['clientTxnId' => $clientTxnId, 'cardNo' => $cardNo],
            function ($v) { return $v !== '' && $v !== null; }
        ));
        // GET 签名原文 = 实际发出的 QUERY_STRING，自行拼接保证一致
        return $this->request('GET', '/api/index.php?' . $qs, null, $qs);
    }

    private function request(string $method, string $path, ?string $body, ?string $signBase = null): array
    {
        $ts = (string)time();                    // 只取一次，签名/发送同值
        $signBase = $body ?? $signBase;
        $ch = curl_init($this->baseUrl . $path);
        $headers = [
            'X-API-Key: ' . $this->apiKey,
            'X-Timestamp: ' . $ts,
            'X-Sign: ' . hash_hmac('sha256', $ts . '.' . $signBase, $this->secret),
        ];
        if ($method === 'POST') {
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
            $headers[] = 'Content-Type: application/json';
        }
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CONNECTTIMEOUT => $this->connTimeout,
            CURLOPT_TIMEOUT        => $this->timeout,
            CURLOPT_SSL_VERIFYPEER => true,      // 生产严禁关闭
            CURLOPT_SSL_VERIFYHOST => 2,
            CURLOPT_HTTPHEADER     => $headers,
        ]);
        $raw   = curl_exec($ch);
        $errno = curl_errno($ch);
        curl_close($ch);

        if ($errno !== 0 || $raw === false || $raw === '') {
            return ['ok' => false, 'err' => 'TIMEOUT',
                    'msg' => '结果未知：订单保持pending，稍后用同一clientTxnId调query收敛'];
        }
        $j = json_decode($raw, true);
        if (!is_array($j)) {
            return ['ok' => false, 'err' => 'BAD_RESPONSE', 'msg' => '响应不可解析，按未知结果处理'];
        }
        if ((int)($j['code'] ?? 0) === 1) {
            $d = $j['data'];
            if (isset($d['used'])) {
                return ['ok' => true, 'used' => (bool)$d['used'], 'pid' => (int)$d['pid'],
                        'usedTxn' => (string)$d['usedTxn'], 'usedAt' => (string)$d['usedAt']];
            }
            return ['ok' => true, 'pid' => (int)$d['pid'], 'replay' => (bool)$d['replay']];
        }
        return ['ok' => false, 'err' => (string)($j['err'] ?? 'BUSY'), 'msg' => (string)($j['msg'] ?? '')];
    }
}

// ============ 使用 ============
$api  = new FakabaoAPI('https://fakabao.net', '你的KEY', '你的SECRET');
$card = 'ABCDE-FGHIJ-KLMNO';
$txn  = 'm51_' . date('YmdHis') . '_' . bin2hex(random_bytes(8));
// TODO 先把 $txn 以 pending 写入你自己的订单表，再发起核销

$r = $api->consume($card, $txn);
if ($r['ok']) {
    // TODO 本地事务：按 $r['pid'] 发放权益 + 订单翻 success（同一事务，只翻转一次）
} elseif (in_array($r['err'], ['NOT_FOUND', 'ALREADY_USED', 'REFUNDED'], true)) {
    // 终态失败：订单置 failed，提示换卡
} else {
    // TIMEOUT/BUSY/RATE_LIMITED/BAD_RESPONSE/鉴权错：
    // 保持 pending，前端文案"处理中，1分钟后自动到账"，定时任务调 query 收敛
}
?>

已封装签名、超时语义、错误分类与补发核对，含充值闭环 + reconcile 模板。

⬇ 下载 PHP SDK fakabao-sdk-php.zip · 约 6 KB · 内含 FakabaoClient.php / example.php / README.md

require 'FakabaoClient.php';
$c = new FakabaoClient('https://fakabao.net', 'API_KEY', 'API_SECRET');

try {
    $r = $c->consume($cardNo, $txn);            // ['pid'=>38,'replay'=>false]
} catch (FakabaoException $e) {
    if ($e->isRetryable()) { /* 保持pending，query收敛 */ }
    /* 否则 NOT_FOUND / ALREADY_USED / REFUNDED 终态失败 */
}

$q = $c->query($cardNo, $txn);                   // ['used','pid','usedTxn','usedAt']
if ($c->isUsedByMe($cardNo, $txn)) { /* 唯一允许自动补发的情况 */ }