身份认证
概述
PIX Bacen API 使用与标准 EYT API 相同的身份认证系统。所有请求必须在 Authorization 请求头中包含有效的 Bearer 令牌。
身份认证方式与标准 API 相同。如果您已有凭据，可以直接使用。
获取令牌
接口端点
POST /api/auth/tokenX.509 证书必须经过 URL 编码 后放入 X-SSL-Client-Cert 请求头。系统会校验证书的 SHA256 指纹是否与账户绑定的记录一致。
请求
curl -X POST https://api.gateway.eyt.com.br/api/auth/token \
-H "Content-Type: application/json" \
-H "X-SSL-Client-Cert: -----BEGIN%20CERTIFICATE-----%0AMIIB..." \
-d '{
"clientId": "your-client-id",
"clientSecret": "your-client-secret"
}'const fs = require('fs');
const certificate = fs.readFileSync('./client-cert.pem', 'utf8');
const encodedCert = encodeURIComponent(certificate);
const response = await fetch('https://api.gateway.eyt.com.br/api/auth/token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-SSL-Client-Cert': encodedCert,
},
body: JSON.stringify({
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
}),
});
const { access_token } = await response.json();import requests
import urllib.parse
with open('client-cert.pem', 'r') as f:
certificate = f.read()
encoded_cert = urllib.parse.quote(certificate)
response = requests.post(
'https://api.gateway.eyt.com.br/api/auth/token',
headers={'X-SSL-Client-Cert': encoded_cert},
json={
'clientId': 'your-client-id',
'clientSecret': 'your-client-secret'
}
)
access_token = response.json()['access_token']响应
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 1800
}使用令牌
在所有 PIX Bacen API 请求中包含令牌：
curl -X PUT https://api.gateway.eyt.com.br/cob/abc123 \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{...}'认证参数
客户端 X.509 证书，PEM 格式并经过 URL 编码，绑定到您的账户。
应用程序的唯一标识符。在注册时提供。
应用程序的密钥。长度必须在 8 到 64 个字符之间。
切勿在前端代码或公开仓库中暴露 clientSecret。
响应字段
access_tokenstring用于认证请求的 JWT 令牌。
token_typestring令牌类型。始终为 "Bearer"。
expires_innumber令牌有效期（秒）。始终为 1800（30 分钟）。
令牌续期
令牌在 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 fs = require('fs');
const certificate = fs.readFileSync(process.env.CLIENT_CERT_PATH, 'utf8');
const encodedCert = encodeURIComponent(certificate);
const response = await fetch('https://api.gateway.eyt.com.br/api/auth/token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-SSL-Client-Cert': encodedCert,
},
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 | 令牌已过期 | 通过 /api/auth/token 获取新令牌 |
| 400/401/403 | /api/auth/token 的证书或凭据错误 | 请参阅标准认证指南中的证书错误说明 |