身份认证
概述
PIX Bacen API 使用与标准 Avista API 相同的身份认证系统。所有请求必须在 Authorization 请求头中包含有效的 Bearer 令牌。
身份认证方式与标准 API 相同。如果您已有凭据，可以直接使用。
获取令牌
接口端点
POST /oauth/token请求
curl -X POST https://api.gateway.goforge.com.br/oauth/token \
-H "Content-Type: application/json" \
-d '{
"clientId": "your-client-id",
"clientSecret": "your-client-secret"
}'const response = await fetch('https://api.gateway.goforge.com.br/oauth/token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
}),
});
const { access_token } = await response.json();import requests
response = requests.post(
'https://api.gateway.goforge.com.br/oauth/token',
json={
'clientId': 'your-client-id',
'clientSecret': 'your-client-secret'
}
)
access_token = response.json()['access_token']响应
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "pix:read pix:write balance:read"
}使用令牌
在所有 PIX Bacen API 请求中包含令牌：
curl -X PUT https://api.gateway.goforge.com.br/cob/abc123 \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{...}'认证参数
应用程序的唯一标识符。在注册时提供。
应用程序的密钥。长度必须在 8 到 64 个字符之间。
切勿在前端代码或公开仓库中暴露 clientSecret。
响应字段
access_tokenstring用于认证请求的 JWT 令牌。
token_typestring令牌类型。始终为 "Bearer"。
expires_innumber令牌有效期（秒）。默认值：3600（1 小时）。
scopestring令牌的权限范围。
令牌续期
令牌在 expires_in 秒后过期。请实现自动续期机制：
class TokenManager {
private token: string | null = null;
private expiresAt: number = 0;
async getToken(): Promise<string> {
// 在过期前 5 分钟续期
if (!this.token || Date.now() >= this.expiresAt - 300000) {
await this.refreshToken();
}
return this.token!;
}
private async refreshToken(): Promise<void> {
const response = await fetch('https://api.gateway.goforge.com.br/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientId: process.env.CLIENT_ID,
clientSecret: process.env.CLIENT_SECRET,
}),
});
const data = await response.json();
this.token = data.access_token;
this.expiresAt = Date.now() + (data.expires_in * 1000);
}
}认证错误
| 状态码 | 描述 | 解决方案 |
|---|---|---|
| 401 | 未提供令牌 | 包含 Authorization: Bearer <token> 请求头 |
| 401 | 令牌无效 | 检查令牌是否正确且未过期 |
| 401 | 令牌已过期 | 通过 /oauth/token 获取新令牌 |
| 403 | 权限不足 | 检查令牌的权限范围 |