Pular para o conteúdo principal

​
Visão Geral

A API FireBanking usa um método de autenticação simples e consistente para todas as operações. Nossa arquitetura unificada garante que você use as mesmas credenciais para todos os métodos de pagamento.

x-api-key

Método Único de Autenticação Usado em todos os endpoints: Cartão de Crédito, PIX, Boleto e APIs gerais

​
Características da Autenticação

  • Header obrigatório: x-api-key em todas as requisições
  • Formato JSON: Todas as respostas seguem estrutura consistente
  • Códigos HTTP semânticos: Status codes padronizados
  • Identificadores únicos: Recursos com IDs consistentes
  • Identificação do cliente: A chave API identifica unicamente cada cliente
  • Controle de acesso: Habilita roteamento e permissões específicas
  • Auditoria completa: Rastreamento detalhado de todas as operações
  • Webhooks assinados: Verificação automática de integridade
  • Erro 403 Forbidden: Para credenciais inválidas ou expiradas
  • Rate limiting: Proteção contra abuso de API

​
Autenticação x-api-key

Todos os endpoints da API usam autenticação através do cabeçalho x-api-key com sua Chave de API.

​
Uso

Inclua sua chave de API no cabeçalho x-api-key: 
x-api-key: SUA_CHAVE_DE_API

​
Exemplos de Requisição

curl -X GET "https://api-gateway.firebanking.com.br/v1/account/balance" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json"

​
Configuração no Postman

  1. Abra sua requisição no Postman
  2. Vá para a aba Headers
  3. Adicione novo header:
    • Key: x-api-key
    • Value: SUA_CHAVE_DE_API
  4. Adicione header de conteúdo:
    • Key: Accept
    • Value: application/json

​
Endpoints Aplicáveis

A autenticação x-api-key é usada para:
  • Operações de pagamento (criar, listar, obter, capturar, estornar)
  • Pagamentos PIX (criar, listar, consultar)
  • Boletos (criar, consultar, listar)
  • Tokenização de cartão (criar tokens, recuperar tokens)
  • Gerenciamento de comprador (criar, listar compradores)
  • Gerenciamento de assinatura (criar, atualizar, cancelar)
  • Operações de conta (saldo, configurações)

​
Webhooks

​
Configuração de Webhooks

Os webhooks requerem autenticação via x-api-key para configuração e gerenciamento. Configure URLs específicas para cada método de pagamento:
Configurar Webhooks
curl --request POST \
  --url https://api-gateway.firebanking.com.br/business/webhook \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: sua_chave_api' \
  --data '{
    "pixWebhookUrl": "https://meusite.com/webhooks/pix",
    "bankSlipWebhookUrl": "https://meusite.com/webhooks/boleto",
    "creditCardWebhookUrl": "https://meusite.com/webhooks/cartao"
  }'

​
Segurança de Webhooks

Recebimento de webhooks não requer autenticação via cabeçalho. A segurança é fornecida através de:
  • URLs únicas: Específicas para cada conta
  • HTTPS obrigatório: Todas as URLs devem usar protocolo HTTPS
  • Assinatura digital: Verificação de integridade do payload
  • Retry automático: Tentativas automáticas em caso de falha
  • Timeout configurável: Controle de tempo de resposta

​
Verificação de Assinatura

Exemplo de Verificação
const crypto = require("crypto");

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(payload).digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

​
URLs por Produto

Configure webhooks específicos para cada método:

PIX

pixWebhookUrl Cash In e Cash Out PIX

Boleto

bankSlipWebhookUrl Confirmações e vencimentos

Cartão

creditCardWebhookUrl Autorizações e capturas

​
Tratamento de Erros

​
Códigos de Resposta

CódigoDescriçãoAção Recomendada
200 OKRequisição processada com sucessoContinue com o fluxo
400 Bad RequestErro na estrutura da requisiçãoVerifique parâmetros enviados
401 UnauthorizedChave de API ausenteAdicione header x-api-key
403 ForbiddenChave de API inválida ou expiradaVerifique suas credenciais
429 Too Many RequestsLimite de requisições excedidoImplemente retry com backoff
500 Internal Server ErrorErro interno do servidorTente novamente ou contate suporte

​
Estrutura de Erro Padronizada

Exemplo de Resposta de Erro
{
  "message": "Forbidden resource",
  "error": "Forbidden",
  "statusCode": 403
}

​
Segurança de Webhook

  • URL única: Cada conta possui uma URL específica de webhook
  • Sem cabeçalhos de auth: Webhooks não requerem x-api-key
  • Validação via payload: Verifique a estrutura e origem dos dados

​
Obtendo sua Chave de API

​
Chave de API FireBanking

Sua chave de API pode ser obtida através de:

Portal FireBanking

Acesse seu painel administrativo e gere diretamente

Representante FireBanking

Entre em contato com seu gerente de conta
Processo de obtenção:
  1. Faça login no seu painel FireBanking
  2. Navegue para Configurações de API ou seção de Desenvolvedor
  3. Gere ou copie sua Chave de API
  4. Armazene com segurança - trate como uma senha
Cada chave está associada ao contexto específico do cliente e pode ter escopos e permissões definidos conforme seu plano de negócio.

​
Formatos de Chave

Chaves de API

Formato: a9b484fc-90a6-4255-9394-...

​
Ciclo de Vida da Chave API

  • Apenas uma chave ativa por vez por conta
  • Janela de transição de 20 minutos ao gerar nova chave
  • Ambas as chaves funcionam durante a transição
  • Chave antiga é automaticamente revogada após o período
  • Revogação imediata possível via dashboard - Geração de nova chave revoga a anterior (após transição) - Rotação periódica recomendada para segurança - Backup seguro antes de revogar chave atual
  • Atualize sistemas gradualmente durante a janela de 20 minutos
  • Monitore logs para confirmação de migração
  • Teste nova chave antes de revogar a anterior
  • Mantenha procedimento de rollback preparado

​
Controles de Acesso Avançados

​
IP Whitelist

Configure restrições de IP para maior segurança:
  • Acesso restrito: Apenas IPs pré-definidos podem usar a API
  • Recomendado para produção: Especialmente importante em ambiente live
  • Configuração via dashboard: Adicione/remova IPs conforme necessário
  • Múltiplos IPs: Suporte para ranges e endereços específicos
  • Proteção contra vazamentos: Mesmo com chave exposta, acesso limitado
  • Controle geográfico: Restrinja acesso por localização
  • Auditoria simplificada: Logs mais limpos e rastreáveis
  • Compliance: Atende requisitos de segurança corporativa

​
Restrições por Documento

Para operações sensíveis como saques PIX:
  • Validação por CPF/CNPJ: Documentos específicos para operações de saque
  • Lista de documentos autorizados: Configure quais CPFs/CNPJs podem realizar saques
  • Segurança adicional: Previne operações não autorizadas mesmo com chave válida

​
Melhores Práticas de Segurança

​
Segurança da Chave

Variáveis de Ambiente

Armazene chaves em variáveis de ambiente, não no código fonte

Apenas HTTPS

Sempre use HTTPS para requisições de API

Rotação de Chave

Rotacione chaves periodicamente por segurança

Controle de Acesso

Limite acesso da chave a pessoal autorizado

IP Whitelist

Configure lista de IPs autorizados, especialmente em produção

Monitoramento

Monitore padrões de uso anômalos e atividade suspeita

Dashboard Protegido

Use autenticação forte para proteção do painel administrativo

​
Segurança de Implementação

Uso Seguro de Chave
// ✅ Bom - Variável de ambiente
const apiKey = process.env.FIREBANKING_API_KEY;

// ❌ Ruim - Codificado no fonte
const apiKey = "b7c859fe-12d4-4a89-8d6f-2f4e8b9c1a3e";

// ✅ Bom - Cabeçalhos seguros
const headers = {
  "x-api-key": apiKey,
  "Content-Type": "application/json",
  "User-Agent": "SeuApp/1.0",
};

​
Tratamento de Erros

Sempre trate erros de autenticação de forma graciosa:
Tratamento de Erros
try {
  const response = await fetch(
    "https://api-gateway.firebanking.com.br/v1/payment",
    {
      method: "POST",
      headers: {
        "x-api-key": apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(paymentData),
    }
  );

  if (response.status === 401) {
    // Tratar não autorizado - chave pode ser inválida
    throw new Error("Chave de API inválida");
  }

  if (response.status === 403) {
    // Tratar proibido - chave não tem permissões
    throw new Error("Permissões insuficientes");
  }

  const result = await response.json();
  return result;
} catch (error) {
  console.error("Erro de autenticação:", error);
  throw error;
}

​
Erros de Autenticação

​
Respostas de Erro Comuns

​
Chave Inválida ou Ausente

{
  "message": "Forbidden resource",
  "error": "Forbidden",
  "statusCode": 403
}
Este é o erro mais comum, retornado quando a chave de API está ausente, inválida ou expirada.

​
Solução de Problemas

Verificar Ambiente

Use chaves de teste com sandbox, chaves live com produção

Testar Permissões

Tente um endpoint simples como /health primeiro

Verificar Expiração

Algumas chaves podem ter datas de expiração

​
Limitação de Taxa

Todas as chaves têm os mesmos limites de taxa:
Tipo de OperaçãoLimite de TaxaUso
Operações de API60 req/minPagamentos, consultas, etc.
WebhooksSem limiteRecebimento de notificações
Limites de taxa são aplicados por chave de API, não por endereço IP.

​
Testando Autenticação

​
Teste de Conectividade

curl -X GET "https://api-gateway.firebanking.com.br/v1/account/balance" \
  -H "x-api-key: SUA_CHAVE"

​
Teste de Chave de API

curl -X GET "https://api-gateway.firebanking.com.br/v1/account/balance" \
  -H "x-api-key: SUA_CHAVE"
Pronto para fazer requisições autenticadas? Comece criando seu primeiro pagamento ou explore a referência da API.