Fluxo de Trabalho

Esta seção apresenta um guia passo a passo para integrar a API Finexis Payments em sua aplicação, cobrindo os principais fluxos de trabalho.

Visão Geral

Este guia mostra como implementar os principais casos de uso da API:

1. Autenticação inicial
2. Processamento de cobranças PIX (recebimento)
3. Realização de transferências PIX (envio)

1. Autenticação

O primeiro passo é autenticar-se e obter um token de acesso.

Passo 1: Preparar Credenciais

Você precisa ter:

• Username: Seu nome de usuário
• API Key: Sua chave de API

Passo 2: Codificar Payload

O payload deve ser codificado em hexadecimal no formato username:apikey:

// Exemplo em JavaScript
const username = 'Joao';
const apiKey = '26e3992f-6abe-42eb-a9d8-311d2cb519c2';
const payload = Buffer.from(`${username}:${apiKey}`).toString('hex');
// Resultado: "4a6f616f3a32366533393932662d366162652d343265622d613964382d333131643263623531396332"

Passo 3: Realizar Login

const response = await fetch('https://app.finexis.com.br/api/v1/gateway/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payload: payload
  })
});

const data = await response.json();
const token = data.data.token;

Passo 4: Armazenar Token

Armazene o token de forma segura para usar nas requisições subsequentes:

// Exemplo: armazenar em variável (não recomendado para produção)
let authToken = token;

// Para produção, considere:
// - Variáveis de ambiente
// - Armazenamento seguro no servidor
// - Gerenciamento de sessão

2. Cobrança PIX (Recebimento)

Este fluxo mostra como receber pagamentos via PIX.

Passo 1: Verificar Informações da Conta

Antes de criar cobranças, verifique as informações da conta:

const accountId = 5;
const accountInfo = await fetch(
  `https://app.finexis.com.br/api/v1/gateway/account/${accountId}/info`,
  {
    headers: {
      'Authorization': `Bearer ${authToken}`
    }
  }
);

const accountData = await accountInfo.json();
console.log('Conta:', accountData.data);

Passo 2: Criar Cobrança

Crie uma nova cobrança PIX:

const charge = await fetch(
  `https://app.finexis.com.br/api/v1/gateway/account/${accountId}/charge/pix/create`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${authToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 10.50,
      description: 'Pagamento de serviço',
      currency: 'BRL'
    })
  }
);

const chargeData = await charge.json();
const { reference, content, metadata } = chargeData.data;

console.log('Referência:', reference);
console.log('QR Code:', content);
console.log('Expira em:', metadata.expires_at);

Passo 3: Exibir QR Code

Gere e exiba o QR Code para o pagador:

// Usando biblioteca qrcode (npm install qrcode)
const QRCode = require('qrcode');

QRCode.toDataURL(content, (err, url) => {
  if (err) throw err;
  
  // Exibir QR Code na interface
  document.getElementById('qrcode').src = url;
});

Passo 4: Monitorar Status

Consulte o status periodicamente até a cobrança ser paga:

const checkChargeStatus = async (reference) => {
  const response = await fetch(
    `https://app.finexis.com.br/api/v1/gateway/account/${accountId}/charge/pix/status?reference=${reference}`,
    {
      headers: {
        'Authorization': `Bearer ${authToken}`
      }
    }
  );
  
  const data = await response.json();
  return data.data.status;
};

// Consultar a cada 5 segundos
const interval = setInterval(async () => {
  const status = await checkChargeStatus(reference);
  
  if (status === 'paid') {
    clearInterval(interval);
    console.log('Pagamento confirmado!');
    // Processar confirmação de pagamento
  } else if (status === 'expired' || status === 'cancelled') {
    clearInterval(interval);
    console.log('Cobrança expirada ou cancelada');
  }
}, 5000);

3. Transferência PIX (Envio)

Este fluxo mostra como enviar dinheiro via PIX.

Passo 1: Verificar Saldo

Sempre verifique o saldo antes de criar uma transferência:

const accountInfo = await fetch(
  `https://app.finexis.com.br/api/v1/gateway/account/${accountId}/info`,
  {
    headers: {
      'Authorization': `Bearer ${authToken}`
    }
  }
);

const accountData = await accountInfo.json();
const balance = accountData.data.balance;

const transferAmount = 50.00;

if (balance < transferAmount) {
  throw new Error('Saldo insuficiente');
}

Passo 2: Criar Transferência

Crie a transferência PIX:

const transfer = await fetch(
  `https://app.finexis.com.br/api/v1/gateway/account/${accountId}/transfer/pix/create`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${authToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      pix_key: '70059235373',
      pix_type: 'cpf',
      amount: transferAmount
    })
  }
);

const transferData = await transfer.json();
const { reference, status } = transferData.data;

console.log('Transferência criada:', reference);
console.log('Status inicial:', status);

Passo 3: Verificar Conclusão

Consulte o status para confirmar que a transferência foi concluída:

const checkTransferStatus = async (reference) => {
  const response = await fetch(
    `https://app.finexis.com.br/api/v1/gateway/account/${accountId}/transfer/pix/status?reference=${reference}`,
    {
      headers: {
        'Authorization': `Bearer ${authToken}`
      }
    }
  );
  
  const data = await response.json();
  return data.data;
};

// Consultar a cada 3 segundos
const interval = setInterval(async () => {
  const transfer = await checkTransferStatus(reference);
  
  if (transfer.status === 'paid') {
    clearInterval(interval);
    console.log('Transferência concluída!');
    // Processar confirmação
  } else if (transfer.status === 'failed') {
    clearInterval(interval);
    console.log('Transferência falhou');
    // Tratar erro
  }
}, 3000);

Exemplo Completo: E-commerce

Aqui está um exemplo completo de integração em um e-commerce:

class FinexisPayment {
  constructor(accountId, token) {
    this.accountId = accountId;
    this.token = token;
    this.baseUrl = 'https://app.finexis.com.br/api/v1/gateway';
  }
  
  async createCharge(amount, description) {
    const response = await fetch(
      `${this.baseUrl}/account/${this.accountId}/charge/pix/create`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.token}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          amount,
          description,
          currency: 'BRL'
        })
      }
    );
    
    return await response.json();
  }
  
  async checkChargeStatus(reference) {
    const response = await fetch(
      `${this.baseUrl}/account/${this.accountId}/charge/pix/status?reference=${reference}`,
      {
        headers: {
          'Authorization': `Bearer ${this.token}`
        }
      }
    );
    
    return await response.json();
  }
  
  async waitForPayment(reference, onPaid, onExpired) {
    const interval = setInterval(async () => {
      const { data } = await this.checkChargeStatus(reference);
      
      if (data.status === 'paid') {
        clearInterval(interval);
        onPaid(data);
      } else if (data.status === 'expired' || data.status === 'cancelled') {
        clearInterval(interval);
        onExpired(data);
      }
    }, 5000);
  }
}

// Uso
const payment = new FinexisPayment(5, authToken);

// Criar cobrança
const { data: charge } = await payment.createCharge(100.00, 'Compra #1234');

// Exibir QR Code
displayQRCode(charge.content);

// Aguardar pagamento
payment.waitForPayment(
  charge.reference,
  (charge) => {
    console.log('Pagamento confirmado!');
    completeOrder();
  },
  (charge) => {
    console.log('Cobrança expirada');
    showExpiredMessage();
  }
);

Boas Práticas

1. Tratamento de Erros: Sempre trate erros de rede e da API
2. Timeouts: Implemente timeouts para evitar consultas infinitas
3. Segurança: Nunca exponha tokens ou credenciais no frontend
4. Validação: Valide dados antes de enviar requisições
5. Logs: Registre transações importantes para auditoria
6. Retry: Implemente lógica de retry para falhas temporárias

Próximos Passos

• Consulte a Referência para detalhes técnicos
• Veja exemplos de Cobranças PIX
• Veja exemplos de Transferências PIX