Skip to main content

​
Visão Geral

A API PIX Bacen utiliza o mesmo sistema de autenticação da API padrão Avista. Todas as requisições devem incluir um token Bearer válido no header Authorization.
A autenticação é idêntica à API padrão. Se você já possui credenciais, pode usá-las diretamente.

​
Obtendo o Token

​
Endpoint

POST /oauth/token

​
Request

curl -X POST https://api.avista.global/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "seu-client-id",
    "clientSecret": "seu-client-secret"
  }'

​
Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "pix:read pix:write balance:read"
}

​
Usando o Token

Inclua o token em todas as requisições da API PIX Bacen: 
curl -X PUT https://api.avista.global/cob/abc123 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{...}'

​
Parâmetros de Autenticação

​
clientId
string
required
Identificador único da sua aplicação. Fornecido durante o cadastro.
​
clientSecret
string
required
Chave secreta da sua aplicação. Deve ter entre 8 e 64 caracteres.
Nunca exponha o clientSecret em código frontend ou repositórios públicos.

​
Campos da Resposta

​
access_token
string
Token JWT para autenticação nas requisições.
​
token_type
string
Tipo do token. Sempre "Bearer".
​
expires_in
number
Tempo de vida do token em segundos. Padrão: 3600 (1 hora).
​
scope
string
Escopos de permissão do token.

​
Renovação do Token

O token expira após expires_in segundos. Implemente renovação automática: 
class TokenManager {
  private token: string | null = null;
  private expiresAt: number = 0;

  async getToken(): Promise<string> {
    // Renovar 5 minutos antes de expirar
    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.avista.global/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);
  }
}

​
Erros de Autenticação

CódigoDescriçãoSolução
401Token não fornecidoInclua o header Authorization: Bearer <token>
401Token inválidoVerifique se o token está correto e não expirou
401Token expiradoObtenha um novo token via /oauth/token
403Permissão negadaVerifique os escopos do token

​
Boas Práticas

  • Use variáveis de ambiente
  • Nunca commite credenciais no código
  • Use secret managers em produção (AWS Secrets Manager, HashiCorp Vault)
  • Cache o token até próximo da expiração
  • Renove alguns minutos antes de expirar
  • Evite requisições desnecessárias ao endpoint de token
  • Todas as requisições devem usar HTTPS
  • Verifique certificados SSL/TLS
  • Configure timeouts apropriados

​
Próximos Passos

Ativação

Ative o modo PIX Bacen na sua conta

Criar Cobrança

Faça sua primeira cobrança