环境配置

Quick Reference

What沙箱与生产环境

Why配置端点、理解凭证作用域，并发起首次 API 调用

Reading Time5 分钟

Difficulty初级

Prerequisites身份验证

为什么环境配置很重要

风险	后果	A55 的防护方式
在开发中使用生产凭证	测试时会产生真实扣款	为每个环境分配独立的凭证对
为不同环境指向错误的 API（应用程序编程接口）地址	请求失败或命中错误数据	每个环境使用独立地址——不易混淆
缺少明确的上线清单	缺陷被带入生产环境	沙箱与生产 1:1 镜像——沙箱通过即可上线

不同地址，不同凭证

沙箱与生产使用不同的基础 URL。请确保指向正确的 URL，并使用对应环境的 client_id / client_secret 凭证对。

---

端点

用途	生产	沙箱
REST API	https://api.a55.tech/api/v1	https://sandbox.api.a55.tech/api/v1
OAuth 2.0（开放授权）令牌	https://auth.a55.tech/oauth2/token	https://auth.a55.tech/oauth2/token

开发和测试时使用沙箱 URL，上线时切换至生产 URL。

---

沙箱与生产对比

	沙箱	生产
基础 URL	https://sandbox.api.a55.tech/api/v1	https://api.a55.tech/api/v1
资金	模拟——不进行结算	真实扣款与结算
卡片	测试卡及末位数字规则	真实发卡行授权
凭证	沙箱 client_id / client_secret	生产 client_id / client_secret
3DS（3D Secure 验证）	模拟流程	真实发卡行验证
Webhook（网络钩子）	发送至您的端点	发送至您的端点
速率限制	与生产相同	与沙箱相同
API 接口	完全一致	完全一致

---

首次 API 调用

将凭证设为环境变量，然后一次性完成身份验证并查询钱包列表。

cURL

# 设置沙箱凭证
export A55_CLIENT_ID="sandbox-xxxx-xxxx-xxxx"
export A55_CLIENT_SECRET="sandbox-secret-xxxx"

# 身份验证
TOKEN=$(curl -s -X POST \
  https://auth.a55.tech/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$A55_CLIENT_ID" \
  -d "client_secret=$A55_CLIENT_SECRET" | jq -r '.access_token')

echo "令牌已获取：${TOKEN:0:20}..."

# 查询钱包列表
curl -s https://sandbox.api.a55.tech/api/v1/wallets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" | jq .

Python

import os
import requests

AUTH_URL = "https://auth.a55.tech/oauth2/token"
API_BASE = "https://sandbox.api.a55.tech/api/v1"

client_id = os.environ["A55_CLIENT_ID"]
client_secret = os.environ["A55_CLIENT_SECRET"]

token = requests.post(AUTH_URL, data={
    "grant_type": "client_credentials",
    "client_id": client_id,
    "client_secret": client_secret,
}, headers={"Content-Type": "application/x-www-form-urlencoded"}).json()["access_token"]

print(f"令牌已获取：{token[:20]}...")

headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
wallets = requests.get(f"{API_BASE}/wallets", headers=headers).json()
print(wallets)

JavaScript

const AUTH_URL = "https://auth.a55.tech/oauth2/token";
const API_BASE = "https://sandbox.api.a55.tech/api/v1";

const clientId = process.env.A55_CLIENT_ID;
const clientSecret = process.env.A55_CLIENT_SECRET;

const tokenResp = await fetch(AUTH_URL, {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: clientId,
    client_secret: clientSecret,
  }),
});
const { access_token } = await tokenResp.json();
console.log(`令牌已获取：${access_token.slice(0, 20)}...`);

const wallets = await fetch(`${API_BASE}/wallets`, {
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
}).then(r => r.json());

console.log(wallets);

立即运行

复制上方代码片段，将凭证替换为您的沙箱凭证对，然后运行。如果能看到钱包列表，说明环境配置正确。

---

凭证配置

按环境将凭证存储在密钥管理器或 .env 文件中（切勿提交到版本控制系统）。

沙箱：

export A55_API_BASE="https://sandbox.api.a55.tech/api/v1"
export A55_CLIENT_ID="sandbox-xxxx-xxxx-xxxx"
export A55_CLIENT_SECRET="sandbox-secret-xxxx"
export A55_ENV="sandbox"

生产：

export A55_API_BASE="https://api.a55.tech/api/v1"
export A55_CLIENT_ID="prod-xxxx-xxxx-xxxx"
export A55_CLIENT_SECRET="prod-secret-xxxx"
export A55_ENV="production"

切勿混用环境

在开发中使用生产凭证会产生真实扣款。在生产中使用沙箱凭证会静默失败。部署前请务必确认所用凭证对。

---

上线清单

步骤	沙箱	生产
1. 凭证已配置	沙箱 client_id / client_secret	生产 client_id / client_secret
2. 基础 URL 已配置	https://sandbox.api.a55.tech/api/v1	https://api.a55.tech/api/v1
3. 身份验证正常	令牌已获取，API 正常响应	令牌已获取，API 正常响应
4. 创建收款	测试卡，状态为 paid	真实卡片，状态为 paid
5. Webhook 已接收	状态更新送达您的端点	状态更新送达您的端点
6. 退款已测试	沙箱中退款完成	——
7. 3DS 已测试	无摩擦流程和挑战流程均通过	——
8. 凭证轮换	——	轮换密钥，确认无停机

---

运维实践

实践	说明
密钥管理器	将凭证存储在 AWS Secrets Manager、HashiCorp Vault 或同类云服务中
禁止硬编码	切勿将凭证提交到版本控制系统
先在沙箱验证	在申请生产访问权限前完成所有流程测试
定期轮换	至少每季度轮换一次密钥
监控 401 错误	对异常的身份验证失败设置告警——可能意味着凭证泄露

---

申请凭证

发送邮件至 tech.services@a55.tech，包含公司名称、CNPJ（巴西企业税号，如适用）、联系邮箱、所需环境（沙箱 / 生产）以及简要的使用场景描述。

测试卡 →在沙箱中模拟批准、拒绝及各类边界场景。集成概览 →根据架构需求选择 H2H、SDK 或收银台页面。创建首笔收款 →在沙箱中完成端到端支付流程。