API 版本管理
A55 使用基于 URL 的版本控制，并提供稳定的向后兼容性保证。当前版本为 v1，所有端点均在以下路径提供：
https://core-manager.a55.tech/api/v1/
版本管理策略
| 方面 | 策略 |
|---|---|
| 方案 | URL 路径前缀（/api/v1/、/api/v2/） |
| 当前版本 | v1 |
| 稳定性 | 生产稳定——主版本内无破坏性变更 |
| 弃用通知 | 主版本停用前至少 6 个月通知 |
| 停用期 | 迁移期间 12 个月的双版本支持 |
什么算作破坏性变更
以下变更会触发新的主版本：
| 破坏性变更 | 示例 |
|---|---|
| 从响应中移除字段 | 从收费响应中移除 usd_currency |
| 重命名必填请求字段 | payer_name → cardholder_name |
| 更改字段类型 | installment_count 从 integer 改为 string |
| 移除端点 | 移除 POST /charge/ |
| 更改认证方案 | Bearer token → API key |
| 更改错误响应结构 | message: string → message: array |
什么不算破坏性变更
以下变更在当前版本内进行，无需事先通知：
| 非破坏性变更 | 示例 |
|---|---|
| 添加新的可选请求字段 | 创建收费中新增 metadata 字段 |
| 在响应中添加新字段 | 收费响应中新增 provider_reference |
| 添加新端点 | POST /api/v1/bank/wallet/checkout/ |
| 添加新的枚举值 | 新增 type_charge: "googlepay" |
| 添加新的 HTTP 状态码 | 新增 429 频率限制响应 |
| 改进错误描述 | 更具体的错误消息 |
| 性能改进 | 更快的响应时间 |
务必处理未知字段
您的集成应忽略 API 响应中的未知字段。A55 可能随时添加新的响应字段作为非破坏性变更。请使用宽松的 JSON 解析，避免对响应进行严格的 schema 验证。
环境 URL
| 环境 | 基础 URL | 用途 |
|---|---|---|
| 生产环境 | https://core-manager.a55.tech/api/v1 | 实际交易 |
| 沙箱环境 | https://sandbox.api.a55.tech/api/v1 | 测试和开发 |
使用环境变量切换环境：
export A55_API_URL="https://sandbox.api.a55.tech" # 开发环境
export A55_API_URL="https://core-manager.a55.tech" # 生产环境
export A55_ACCESS_TOKEN="your-token-here"
弃用流程
当新的主版本发布时：
- 公告——在停用前 6 个月以上通过博客文章、电子邮件通知和仪表盘横幅发布公告。
- 双版本支持——两个版本并行运行 12 个月。
v1端点返回Deprecation响应头。 - 迁移指南——发布详细的逐字段迁移指南。
- 停用——停用日期后，旧版本返回
410 Gone并附带迁移链接。
弃用响应头
当版本或端点被弃用时，响应包含：
Deprecation: true
Sunset: Sat, 01 Mar 2027 00:00:00 GMT
Link: <https://docs.a55.tech/migration/v1-to-v2>; rel="successor-version"
SDK 版本管理
A55 SDK 遵循语义化版本：
| SDK | 包名 | 版本规则 |
|---|---|---|
| JavaScript | @a55/a55pay-sdk | MAJOR.MINOR.PATCH |
| Python | a55-sdk | MAJOR.MINOR.PATCH |
SDK 主版本与 API 主版本对齐。新的 API v2 将随 SDK 2.x 一起发布。