Skip to main content

​
Pré-requisitos

Antes de começar, você precisa ter:
Certificado X.509 (arquivo .pem) vinculado à sua conta
Credenciais OAuth (clientId e clientSecret)
Solicite suas credenciais e certificado através do Painel Avista.

​
1. Configurar Ambiente

Crie um arquivo .env com suas credenciais: 
AVISTA_CLIENT_ID=account-93-seu-id
AVISTA_CLIENT_SECRET=sua-senha-secreta
AVISTA_API_URL=https://api.avista.global
Salve seu certificado como client-cert.pem no diretório do projeto.

​
2. Instalar Dependências

npm install axios dotenv

​
3. Código Completo

O exemplo abaixo autentica, consulta saldo e cria uma cobrança PIX: 
require('dotenv').config();
const axios = require('axios');
const fs = require('fs');

const API_URL = process.env.AVISTA_API_URL;
const certificate = fs.readFileSync('./client-cert.pem', 'utf8');
const encodedCert = encodeURIComponent(certificate);

// 1. Obter token
async function getToken() {
  const response = await axios.post(`${API_URL}/api/auth/token`, {
    clientId: process.env.AVISTA_CLIENT_ID,
    clientSecret: process.env.AVISTA_CLIENT_SECRET
  }, {
    headers: {
      'Content-Type': 'application/json',
      'X-SSL-Client-Cert': encodedCert
    }
  });
  return response.data.access_token;
}

// 2. Consultar saldo
async function getBalance(token) {
  const response = await axios.get(`${API_URL}/api/balance`, {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  return response.data;
}

// 3. Criar cobrança PIX
async function createPixCharge(token, value, description, externalId, payer) {
  const response = await axios.post(`${API_URL}/api/pix/cash-in`, {
    transaction: {
      value,
      description,
      externalId,
      expirationTime: 3600, // 1 hora
      generateQrCode: true
    },
    payer: {
      fullName: payer.name,
      document: payer.document
    }
  }, {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
  });
  return response.data;
}

// Executar
async function main() {
  try {
    // Autenticar
    console.log('Autenticando...');
    const token = await getToken();
    console.log('Token obtido com sucesso!');

    // Consultar saldo
    console.log('\nConsultando saldo...');
    const balance = await getBalance(token);
    console.log(`Saldo disponível: R$ ${balance.netBalance.toFixed(2)}`);

    // Criar cobrança
    console.log('\nCriando cobrança PIX...');
    const charge = await createPixCharge(token, 100.00, 'Teste de integração', 'ORDER-001', {
      name: 'João da Silva',
      document: '12345678901'
    });

    console.log(`\nCobrança criada!`);
    console.log(`ID: ${charge.transactionId}`);
    console.log(`Status: ${charge.status}`);
    console.log(`PIX Copia e Cola: ${charge.pixCode}`);
    console.log(`Expira em: ${charge.expirationDate}`);

  } catch (error) {
    console.error('Erro:', error.response?.data || error.message);
  }
}

main();

​
4. Executar

node quickstart.js
Saída esperada: 
Autenticando...
Token obtido com sucesso!

Consultando saldo...
Saldo disponível: R$ 48734.90

Criando cobrança PIX...

Cobrança criada!
ID: 7845
Status: PENDING
PIX Copia e Cola: 00020126580014br.gov.bcb.pix...
Expira em: 2024-01-20T14:30:00.000Z

​
5. Receber Notificações (Webhook)

Configure um endpoint para receber notificações quando o pagamento for confirmado: 
// Express.js
app.post('/webhook/avista', (req, res) => {
  const { event, transactionId, status, finalAmount } = req.body;

  if (event === 'CashIn' && status === 'CONFIRMED') {
    console.log(`Pagamento ${transactionId} confirmado: R$ ${finalAmount}`);
    // Atualizar pedido no seu sistema
  }

  res.status(200).send('OK');
});
Configure a URL do webhook no Painel Avista. Veja o Guia de Webhooks para mais detalhes.

​
Próximos Passos

Autenticação

Entenda o fluxo de autenticação em detalhes

PIX Cash-In

Explore todas as opções de cobrança PIX

PIX Cash-Out

Envie pagamentos PIX

Webhooks

Configure notificações em tempo real

​
Troubleshooting

Verifique se:
  • O arquivo client-cert.pem existe no diretório
  • O certificado está sendo enviado URL-encoded
  • O header X-SSL-Client-Cert está presente
Verifique se:
  • As variáveis de ambiente estão configuradas corretamente
  • O clientId e clientSecret estão corretos
  • O certificado está vinculado à sua conta
Entre em contato com o suporte Avista para vincular o certificado à sua conta.
O token expira em 30 minutos. Implemente renovação automática:
// Renovar token antes de expirar
if (tokenExpiresAt < Date.now() + 30000) {
  token = await getToken();
}