查询钱包

Quick Reference

What通过 UUID、邮箱或客户 ID 查询钱包详情

Why余额验证、对账和多币种报表

Reading Time3 分钟

Difficulty初级

Prerequisites身份验证 → 钱包 UUID 或邮箱或 customer_id

GET/api/v1/bank/wallet/Bearer Token查询钱包

何时使用此端点

没有钱包查询	有钱包查询
只能猜测资金是否到账	在创建收费前精确验证余额
无法了解钱包状态	查看钱包状态、货币和创建日期
用电子表格手动对账	自动对账——比较预期值与实际值
到处硬编码钱包 UUID	通过邮箱或 customer_id 动态查询
无法构建多币种仪表板	查询各货币钱包并汇总生成报表

对账流程

身份验证

需要 Bearer 令牌。请参阅身份验证。

查询参数

字段	类型	必填	说明
`wallet_uuid`	string (UUID)	至少提供一个	通过 UUID 直接查询钱包
`email`	string	至少提供一个	通过关联邮箱查找钱包
`customer_id`	string	至少提供一个	通过您的内部客户 ID 查找钱包

灵活查询

至少提供一个参数。您可以组合多个参数来缩小结果范围——例如 ?customer_id=cust_12345&currency=BRL 可以查找该客户的 BRL 钱包。

代码示例

通过钱包 UUID 查询

cURL
Python
JavaScript

curl -s -G https://core-manager.a55.tech/api/v1/bank/wallet/ \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "wallet_uuid=f47ac10b-58cc-4372-a567-0e02b2c3d479"

import requests
import os

token = os.environ["A55_API_TOKEN"]

wallet = requests.get(
    "https://core-manager.a55.tech/api/v1/bank/wallet/",
    params={"wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479"},
    headers={"Authorization": f"Bearer {token}"},
).json()

print(f"钱包：{wallet['wallet_uuid']}")
print(f"币种：{wallet['currency']}")
print(f"邮箱：{wallet['email']}")

const token = process.env.A55_API_TOKEN;

const params = new URLSearchParams({
  wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
});

const wallet = await fetch(
  `https://core-manager.a55.tech/api/v1/bank/wallet/?${params}`,
  { headers: { Authorization: `Bearer ${token}` } }
).then((r) => r.json());

console.log(`钱包：${wallet.wallet_uuid}`);
console.log(`币种：${wallet.currency}`);
console.log(`邮箱：${wallet.email}`);

通过邮箱查询

cURL
Python
JavaScript

curl -s -G https://core-manager.a55.tech/api/v1/bank/wallet/ \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "email=financeiro@loja-sp.com.br"

wallet = requests.get(
    "https://core-manager.a55.tech/api/v1/bank/wallet/",
    params={"email": "financeiro@loja-sp.com.br"},
    headers={"Authorization": f"Bearer {token}"},
).json()
print(f"已找到钱包：{wallet['wallet_uuid']} ({wallet['currency']})")

const params = new URLSearchParams({ email: "financeiro@loja-sp.com.br" });

const wallet = await fetch(
  `https://core-manager.a55.tech/api/v1/bank/wallet/?${params}`,
  { headers: { Authorization: `Bearer ${token}` } }
).then((r) => r.json());

console.log(`已找到钱包：${wallet.wallet_uuid} (${wallet.currency})`);

通过客户 ID 查询

cURL
Python
JavaScript

curl -s -G https://core-manager.a55.tech/api/v1/bank/wallet/ \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "customer_id=cust_12345"

wallet = requests.get(
    "https://core-manager.a55.tech/api/v1/bank/wallet/",
    params={"customer_id": "cust_12345"},
    headers={"Authorization": f"Bearer {token}"},
).json()
print(f"已找到钱包：{wallet['wallet_uuid']} ({wallet['currency']})")

const params = new URLSearchParams({ customer_id: "cust_12345" });

const wallet = await fetch(
  `https://core-manager.a55.tech/api/v1/bank/wallet/?${params}`,
  { headers: { Authorization: `Bearer ${token}` } }
).then((r) => r.json());

console.log(`已找到钱包：${wallet.wallet_uuid} (${wallet.currency})`);

响应

成功 (200 OK)

{
  "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "email": "financeiro@loja-sp.com.br",
  "customer_id": "cust_12345",
  "currency": "BRL",
  "date": "2026-03-15T10:30:00-03:00"
}

响应字段

字段	类型	说明
`wallet_uuid`	string (UUID)	钱包唯一标识符
`email`	string	与钱包关联的邮箱
`customer_id`	string	您的内部客户 ID
`currency`	string	ISO 4217 货币代码（`BRL`、`MXN`、`CLP`、`ARS`）
`date`	string (ISO 8601)	钱包创建时间戳

错误响应

{
  "error": "not_found",
  "message": "Wallet not found",
  "code": "errors.wallet.not_found"
}

状态码	错误码	说明	解决方法
400	`validation_error`	未提供查询参数	至少提供 `wallet_uuid`、`email` 或 `customer_id` 中的一个
401	`unauthorized`	无效或过期的 Bearer 令牌	刷新您的访问令牌
404	`errors.wallet.not_found`	没有匹配查询的钱包	验证标识符或先创建钱包

完整示例——每日对账脚本

一个实用脚本，检查钱包状态并与您的预期记录进行比较：

cURL
Python
JavaScript

#!/bin/bash
# 每日钱包对账——通过 cron 运行
TOKEN="$A55_API_TOKEN"
BASE="https://core-manager.a55.tech/api/v1/bank/wallet/"

WALLETS=("cust_12345" "cust_67890" "cust_24680")

for CUST_ID in "${WALLETS[@]}"; do
  RESPONSE=$(curl -s -G "$BASE" \
    -H "Authorization: Bearer $TOKEN" \
    --data-urlencode "customer_id=$CUST_ID")

  WALLET_UUID=$(echo "$RESPONSE" | jq -r '.wallet_uuid')
  CURRENCY=$(echo "$RESPONSE" | jq -r '.currency')

  if [ "$WALLET_UUID" = "null" ]; then
    echo "缺失：客户 $CUST_ID 未找到钱包"
  else
    echo "正常：$CUST_ID → $WALLET_UUID ($CURRENCY)"
  fi
done

import requests
import os

token = os.environ["A55_API_TOKEN"]
base = "https://core-manager.a55.tech/api/v1/bank/wallet/"
headers = {"Authorization": f"Bearer {token}"}

expected_wallets = {
    "cust_12345": "BRL",
    "cust_67890": "MXN",
    "cust_24680": "BRL",
}

reconciliation = {"matched": 0, "missing": 0, "mismatch": 0}

for customer_id, expected_currency in expected_wallets.items():
    response = requests.get(
        base,
        params={"customer_id": customer_id},
        headers=headers,
    )

    if response.status_code == 404:
        print(f"缺失：{customer_id}——未找到钱包")
        reconciliation["missing"] += 1
        continue

    wallet = response.json()
    if wallet["currency"] != expected_currency:
        print(f"不匹配：{customer_id}——预期 {expected_currency}，实际 {wallet['currency']}")
        reconciliation["mismatch"] += 1
    else:
        print(f"正常：{customer_id} → {wallet['wallet_uuid']} ({wallet['currency']})")
        reconciliation["matched"] += 1

print(f"\n对账结果：{reconciliation}")

const token = process.env.A55_API_TOKEN;
const base = "https://core-manager.a55.tech/api/v1/bank/wallet/";

const expectedWallets = {
  cust_12345: "BRL",
  cust_67890: "MXN",
  cust_24680: "BRL",
};

const results = { matched: 0, missing: 0, mismatch: 0 };

for (const [customerId, expectedCurrency] of Object.entries(expectedWallets)) {
  const params = new URLSearchParams({ customer_id: customerId });
  const response = await fetch(`${base}?${params}`, {
    headers: { Authorization: `Bearer ${token}` },
  });

  if (response.status === 404) {
    console.log(`缺失：${customerId}——未找到钱包`);
    results.missing++;
    continue;
  }

  const wallet = await response.json();
  if (wallet.currency !== expectedCurrency) {
    console.log(`不匹配：${customerId}——预期 ${expectedCurrency}，实际 ${wallet.currency}`);
    results.mismatch++;
  } else {
    console.log(`正常：${customerId} → ${wallet.wallet_uuid} (${wallet.currency})`);
    results.matched++;
  }
}

console.log("\n对账结果：", results);

提示

缓存钱包 UUID

首次查询后，将 wallet_uuid 缓存到数据库中。直接通过 UUID 查询比邮箱或 customer_id 查询更快。仅当缓存的 UUID 返回 404（钱包已删除并重建）时，才回退到邮箱/customer_id 查询。

速率限制

钱包查询与全局速率限制共享，每个令牌每分钟 100 次请求。对于大批量对账，请在请求之间添加小延迟，而不是一次性全部发送。

不要轮询余额变化

使用 webhooks 实时响应收费状态变化。将钱包查询保留用于定期对账任务，而不是作为事件驱动架构的替代方案。

创建钱包 →为商户和货币设置新钱包。创建收费 →在此钱包上处理付款。收费列表 →通过筛选和分页获取钱包的所有收费记录。

Quick Reference

何时使用此端点​

对账流程​

身份验证​

查询参数​

代码示例​

通过钱包 UUID 查询​

通过邮箱查询​

通过客户 ID 查询​

响应​

成功 (200 OK)​

响应字段​

错误响应​

完整示例——每日对账脚本​

提示​