IBAN新增接口

说明：新增一条 IBAN 账户记录。若请求中传了 iban 则使用指定 IBAN（需校验格式和唯一性）；若未传 iban 则从预生成的号码池中自动分配一个，并关联当前 api_account。

生产环境API URL：#/api/iban/add 测试环境API URL：https://ibantest.yabandpay.com/api/iban/add

Method：POST

Header：

Authorization: Bearer {api_account_token}
Content-Type: application/json

一、请求格式（统一）

1.1 data 对象（业务参数）

1.2 签名算法（HMAC-SHA256）

调用端计算步骤（必须严格按顺序）：

1. 原始请求参数（Body JSON）里移除 sign 字段（role 也不参与签名，若有的话）。
2. 把 data 对象内所有字段提升到外层，和 uid / timestamp / nonce 放在同一个平铺数组里。
3. 对平铺后的数组按 key 做字典序 ksort()。
4. 拼成 k1=v1&k2=v2&k3=v3 形式的字符串。
5. 用该账户的 secret_key 作为密钥，用 HMAC-SHA256 计算签名，结果转小写就是 sign。

签名公式：
sign = hash_hmac('sha256', implode('&', ksort(merge(data, {uid,timestamp,nonce})) ), secret_key)

签名示例（PHP 版本）：

$secretKey = '你的账户 secret_key';
$body = [
    'uid'       => '900001',
    'timestamp' => 1731926400,
    'nonce'     => 'Qe3CkH2xP8',
    'data'      => [
        'request_id'  => 'req_202411180049',
        'customer_id' => 'CUST20260001',
        'timezone'    => 'Asia/Shanghai',
        'customer_type' => 'legal_entity',
        'holder_name' => 'Yabandpay B.V.',
    ],
];
$sign = getSignByYabandPayV3($body, $secretKey);
$body['sign'] = $sign;

二、请求示例

{
    "uid": "900001",
    "timestamp": 1731926400,
    "nonce": "Qe3CkH2xP8",
    "sign": "A1AC665F9B40F7C51212BCE080F5B987",
    "data": {
        "request_id": "req_202411180049",
        "customer_id": "CUST20260001",
        "customer_type": "legal_entity",
        "holder_name": "Yabandpay B.V.",
        "alternative_name": "YB HQ",
        "creditor_identifier": "YABAND001",
        "access": 1,
        "status": 1,
        "remark": "荷兰总部对公账户"
    }
}

三、返回示例

成功（200）

{
    "status": true,
    "code": "200",
    "data": {
        "id": 1001,
        "customer_type": "legal_entity",
        "customer_id": "CUST20260001",
        "holder_name": "Yabandpay B.V.",
        "alternative_name": "YB HQ",
        "creditor_identifier": "YABAND001",
        "bic": "YABNNL22",
        "iban": "NL08YABN0187654321",
        "currency": "EUR",
        "balance": "0.00",
        "access": 1,
        "access_label": "full",
        "status": 1,
        "status_label": "active",
        "remark": "荷兰总部对公账户",
        "api_account_id": 1,
        "created_at": 1784851200,
        "updated_at": 1784851200,
        "request_id": "req_202411180049",
        "response_id": "TRADE20260819XXXXXX"
    },
    "message": ""
}

失败示例（部分常见）

参数错误示例：

{
    "status": false,
    "code": "-3002",
    "message": "The given data was invalid.",
    "data": {}
}

IBAN 格式错误示例：

{
    "status": false,
    "code": "-3004",
    "message": "invalid NL IBAN",
    "data": {}
}

四、特殊说明

1. 关于 verify.api.sign 中间件：
   • 会验证 Header Authorization: Bearer {token} 是否与 uid 匹配；
   • 会校验 IP 白名单；
   • 会重算签名并对比；
   • 通过后会把 data 中所有业务字段展开到 Request 顶层，并注入 iban_api_user_info（账户详情数组）。
2. 关于自动分配 IBAN：
   • 若不传 data.iban，接口会从 iban_generated 号码池中并发安全地取一条（FOR UPDATE SKIP LOCKED + 事务 + UPDATE 条件三重保险，保证不同账户不会拿到同一个）；
   • 分配后立刻在 iban.api_account_id 和 iban_generated.api_account_id 上都标记为当前 API 账户持有；
   • 号码池分配默认锁定 1800 秒（30 分钟），超时未使用会被定时任务释放。
3. 关于 NL IBAN 格式（显式指定时）：
   • 校验规则：必须 NL 开头，整体 Mod97-10 余数为 1；
   • 当前默认要求 YABN 后面为 01 + 8位数字（账号段总长度 10 位）。
4. 调用方可通过 request_id 做幂等：我们会在响应中原样回传，方便双方关联。