Autenticación
Descripción general
La API PIX Bacen utiliza el mismo sistema de autenticación que la API estandar de Avista. Todas las solicitudes deben incluir un token Bearer valido en el header Authorization.
La autenticación es identica a la de la API estandar. Si ya tiene credenciales, puede usarlas directamente.
Obtener un Token
Endpoint
POST /oauth/tokenSolicitud
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']Respuesta
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "pix:read pix:write balance:read"
}Uso del Token
Incluya el token en todas las solicitudes a la API PIX Bacen:
curl -X PUT https://api.gateway.goforge.com.br/cob/abc123 \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{...}'Parámetros de Autenticación
Identificador único de su aplicación. Proporcionado durante el registro.
Clave secreta de su aplicación. Debe tener entre 8 y 64 caracteres.
Nunca exponga el clientSecret en código frontend o repositorios publicos.
Campos de Respuesta
access_tokenstringToken JWT para autenticar solicitudes.
token_typestringTipo de token. Siempre "Bearer".
expires_innumberTiempo de vida del token en segundos. Por defecto: 3600 (1 hora).
scopestringAlcances de permisos del token.
Renovacion del Token
El token expira después de expires_in segundos. Implemente la renovacion automatica:
class TokenManager {
private token: string | null = null;
private expiresAt: number = 0;
async getToken(): Promise<string> {
// Renovar 5 minutos antes de la expiracion
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);
}
}Errores de Autenticación
| Código | Descripción | Solución |
|---|---|---|
| 401 | Token no proporcionado | Incluya el header Authorization: Bearer <token> |
| 401 | Token invalido | Verifique que el token sea correcto y no haya expirado |
| 401 | Token expirado | Obtenga un nuevo token via /oauth/token |
| 403 | Permiso denegado | Verifique los alcances del token |