环境配置

Quick Reference

What沙箱与生产环境

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

Reading Time5 分钟

Difficulty初级

Prerequisites身份验证

为什么环境配置很重要

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

同一地址，不同凭证

Sandbox（沙箱环境）与生产共用同一基础 URL 和 Cognito 主机。环境取决于您使用的 client_id / client_secret 凭证对。部署前请务必确认所用凭证。

---

端点

用途	URL
REST API	https://core-manager.a55.tech/api/v1
OAuth 2.0（开放授权）令牌	https://smart-capital.auth.us-east-1.amazoncognito.com/oauth2/token

两个 URL 在沙箱和生产环境中完全相同。您的凭证决定所处环境。

---

沙箱与生产对比

	沙箱	生产
资金	模拟——不进行结算	真实扣款与结算
卡片	测试卡及末位数字规则	真实发卡行授权
凭证	沙箱 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://smart-capital.auth.us-east-1.amazoncognito.com/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://core-manager.a55.tech/api/v1/wallets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" | jq .

Python

import os
import requests

AUTH_URL = "https://smart-capital.auth.us-east-1.amazoncognito.com/oauth2/token"
API_BASE = "https://core-manager.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://smart-capital.auth.us-east-1.amazoncognito.com/oauth2/token";
const API_BASE = "https://core-manager.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_CLIENT_ID="sandbox-xxxx-xxxx-xxxx"
export A55_CLIENT_SECRET="sandbox-secret-xxxx"
export A55_ENV="sandbox"

生产：

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. 身份验证正常	令牌已获取，API 正常响应	令牌已获取，API 正常响应
3. 创建收款	测试卡，状态为 paid	真实卡片，状态为 paid
4. Webhook 已接收	状态更新送达您的端点	状态更新送达您的端点
5. 退款已测试	沙箱中退款完成	——
6. 3DS 已测试	无摩擦流程和挑战流程均通过	——
7. 凭证轮换	——	轮换密钥，确认无停机

---

运维实践

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

---

申请凭证

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

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