调试指南

Quick Reference

What高效调试 A55 API 集成问题

Why在出现问题时缩短解决时间

Reading Time10 分钟

Difficulty中级

Prerequisites可运行的沙箱集成

使用 request_id 获取支持

每个 A55 API 响应的响应体中都包含一个 request_id。此标识符可帮助 A55 支持团队在处理流水线中追踪您的确切请求。

{
  "uuid": "chg_abc123...",
  "status": "declined",
  "request_id": "req_7f3a2b1c-4d5e-6f78-9a0b-cdef12345678"
}

联系 tech.services@a55.tech 时，请务必提供：

request_id
请求的时间戳（UTC）
端点和 HTTP 方法
收到的 HTTP 状态码

HTTP 状态码

状态码	含义	操作
`200`	成功	处理响应内容
`201`	已创建	资源创建成功
`400`	错误请求	修正请求体——检查必填字段和格式
`401`	未授权	令牌已过期或无效——重新认证
`403`	禁止访问	您的凭证无权访问此资源
`404`	未找到	检查 URL 和资源 UUID
`409`	冲突	使用了相同的幂等键但载荷不同
`422`	无法处理的实体	验证失败——查看 `error.details` 获取字段级错误
`429`	请求过多	已触发速率限制——等待后使用退避策略重试
`500`	服务器内部错误	A55 端问题——使用指数退避重试
`502/503`	服务不可用	临时中断——使用指数退避重试

解读错误响应

A55 返回结构化的错误响应：

{
  "error": {
    "code": "INVALID_CARD_NUMBER",
    "message": "The card number failed Luhn validation",
    "details": [
      {
        "field": "card.number",
        "reason": "Must be a valid card number (Luhn check failed)"
      }
    ]
  },
  "request_id": "req_7f3a2b1c..."
}

字段	描述
`error.code`	机器可读的错误代码——用于错误处理逻辑
`error.message`	人类可读的描述
`error.details`	字段级验证错误数组（适用时）

沙箱测试

沙箱环境模拟生产环境行为：

使用测试卡参考中的测试卡
测试您代码处理的每种拒绝场景
沙箱中的 webhook 触发方式与生产环境相同
速率限制相同（100 请求/分钟）

# 快速沙箱环境健康检查
curl -s -o /dev/null -w "%{http_code}" \
  "https://sandbox.api.a55.tech/api/v1/health/"
# 预期返回：200

Webhook 调试

使用 ngrok 进行本地开发

# 启动 ngrok 隧道
ngrok http 8080

# 使用该 HTTPS URL 作为您的 webhook_url
# 示例：https://abc123.ngrok.io/webhooks/a55

使用 webhook.site

访问 webhook.site
复制您的专属 URL
在创建收款时将其设置为 webhook_url
在浏览器中检查收到的载荷

验证投递

如果 webhook 未到达：

确认您的端点在 5 秒内返回 HTTP 200
检查您的端点是否可公开访问（未在 VPN/防火墙后面）
确认 HMAC 签名验证没有拒绝有效的载荷
检查 A55 的重试机制——webhook 最多重试 5 次，使用指数退避

收款状态转换

如果收款卡在意外状态中：

# 轮询收费状态
curl -s "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/?charge_uuid=${CHARGE_UUID}" \
  -H "Authorization: Bearer ${A55_ACCESS_TOKEN}" | python3 -m json.tool

常见状态流程：

流程	状态
成功收款	`pending` → `authorized` → `captured` → `settled`
自动扣款	`pending` → `confirmed` → `settled`
被拒收款	`pending` → `declined`
已退款收款	`settled` → `refunded`
3DS 验证	`pending` → `awaiting_3ds` → `authorized` → `captured`

cURL 调试参数

详细输出 (`-v`)

显示请求/响应头部和 TLS 握手信息：

curl -v -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/" \
  -H "Authorization: Bearer ${A55_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"amount": "100.00", "currency": "BRL"}' 2>&1

完整追踪 (`--trace`)

捕获发送和接收的每个字节：

curl --trace trace.log -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/" \
  -H "Authorization: Bearer ${A55_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"amount": "100.00", "currency": "BRL"}'

# 查看追踪信息
less trace.log

响应计时

curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTotal: %{time_total}s\nHTTP: %{http_code}\n" \
  "https://sandbox.api.a55.tech/api/v1/health/"

常见错误 →避免 15 个常见集成陷阱速率限制 →正确处理 429 响应状态生命周期 →了解收款状态转换

Quick Reference

使用 request_id 获取支持​

HTTP 状态码​

解读错误响应​

沙箱测试​

Webhook 调试​

使用 ngrok 进行本地开发​

使用 webhook.site​

验证投递​

收款状态转换​

cURL 调试参数​

详细输出 (-v)​

完整追踪 (--trace)​

响应计时​