Pular para o conteúdo principal

​
Ambientes Disponíveis

A API FireBanking oferece dois ambientes para desenvolvimento e produção, cada um com suas próprias URLs base e características específicas.

Desenvolvimento

Base URL: https://api-gateway.firebanking.devAmbiente para testes e desenvolvimento

Produção

Base URL: https://api-gateway.firebanking.com.brAmbiente com transações reais

​
Configuração de Headers

Todas as requisições para a API FireBanking devem incluir os headers obrigatórios abaixo:

​
Headers Obrigatórios

x-api-key: SUA_CHAVE_DE_API
Descrição: Chave de autenticação da API
  • Desenvolvimento: Chave que inicia com dev_
  • Produção: Chave que inicia com prod_
  • Obtenção: Disponível no Dashboard FireBanking
Content-Type: application/json
Descrição: Tipo de conteúdo enviado na requisição
  • Obrigatório: Para métodos POST, PATCH, PUT
  • Valor: Sempre application/json
  • Encoding: UTF-8
Accept: application/json
Descrição: Tipo de resposta esperada
  • Recomendado: Para todas as requisições
  • Valor: Sempre application/json
  • Função: Garante resposta em formato JSON

​
Ambiente de Desenvolvimento

​
Características

  • URL Base: https://api-gateway.firebanking.dev
  • Dados: Simulados e seguros para teste
  • Transações: Não há movimentação financeira real
  • Rate Limits: Mais flexíveis para desenvolvimento
  • Logs: Mais detalhados para debug

​
Configuração

curl --request POST \
  --url 'https://api-gateway.firebanking.dev/pix/v2/payment' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: dev_sua_chave_aqui' \
  --data '{
    "transaction": {
      "value": 10.00,
      "description": "Teste de desenvolvimento",
      "externalId": "test-pix-001"
    },
    "payer": {
      "fullName": "João da Silva Teste",
      "document": "11144477735"
    }
  }'

​
Dados de Teste

Para facilitar o desenvolvimento, use estes dados de teste validados:
CPF Válido: 11144477735 (formato: apenas números)CNPJ Válido: 11222333000181 (formato: apenas números)Chaves PIX de Teste:
  • Email: [email protected]
  • Telefone: +5511999999999
  • CPF: 11144477735
  • UUID: 123e4567-e89b-12d3-a456-426614174000
Aprovado (final 0, 1, 4): 5186882549895601Negado (final 2): 5465415736976082Expirado (final 3): 5112970800105403Timeout (final 6): 5186882549895606CVV: SEMPRE terminado em 0 (ex: 220, 120, 340)Validade: 12/2025 (qualquer data futura)Nome: JOSE DAS NEVES TEST
CEP: 01000000 (formato: apenas números)Rua: Rua das FloresNúmero: 123Bairro: CentroCidade: São PauloEstado: SPPaís: BR
{
  "name": "João da Silva Teste",
  "document": "11144477735",
  "email": "[email protected]",
  "phone": "11999999999",
  "countryCode": "+55",
  "address": {
    "country": "BR",
    "state": "SP",
    "city": "São Paulo",
    "district": "Centro",
    "street": "Rua das Flores",
    "zipCode": "01000000",
    "number": "123"
  }
}

​
Ambiente de Produção

​
Características

  • URL Base: https://api-gateway.firebanking.com.br
  • Dados: Reais com movimentação financeira
  • Transações: Processamento real no sistema bancário
  • Rate Limits: Configurados para uso comercial
  • Segurança: Máxima proteção e monitoramento

​
Configuração

curl --request POST \
  --url 'https://api-gateway.firebanking.com.br/pix/v2/payment' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: prod_sua_chave_aqui' \
  --data '{
    "transaction": {
      "value": 50.00,
      "description": "Pagamento real",
      "externalId": "prod-payment-001"
    },
    "payer": {
      "fullName": "Maria Silva Santos",
      "document": "11144477735"
    }
  }'

​
Requisitos de Segurança

ATENÇÃO: No ambiente de produção, suas chaves de API manipulam dinheiro real. Mantenha-as seguras!
  • Nunca commit chaves de produção no código
  • Use variáveis de ambiente para armazenar credenciais
  • Monitore logs de acesso e uso da API
  • Implemente retry policies para falhas de rede
  • Configure alertas para transações fora do padrão

​
Variáveis de Ambiente

​
Configuração Recomendada

Configure variáveis de ambiente para facilitar a troca entre ambientes: 
FIREBANKING_BASE_URL=https://api-gateway.firebanking.dev
FIREBANKING_API_KEY=dev_sua_chave_de_desenvolvimento
FIREBANKING_ENVIRONMENT=development

​
Implementação

// config.js
module.exports = {
  firebanking: {
    baseUrl: process.env.FIREBANKING_BASE_URL,
    apiKey: process.env.FIREBANKING_API_KEY,
    environment: process.env.FIREBANKING_ENVIRONMENT || 'development'
  }
};

// uso na aplicação
const config = require('./config');

const headers = {
  'x-api-key': config.firebanking.apiKey,
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

​
Rate Limits

Os limites de requisições variam entre ambientes:
AmbienteLimite GeralPIXCartãoBoleto
Desenvolvimento1000 req/min500 req/min300 req/min200 req/min
Produção10000 req/min5000 req/min3000 req/min2000 req/min

​
Headers de Rate Limit

A API retorna headers informativos sobre seus limites: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1620000000

​
Monitoramento

​
Status da API

Monitore incidentes e manutenções:
  • Status Page: status.firebanking.io
  • Webhook de Status: Configure notificações de downtime
  • Métricas: Disponíveis no Dashboard FireBanking

​
Troubleshooting

​
Problemas Comuns

Problema: Chave de API inválida ou ausenteSolução:
  • Verifique se o header x-api-key está presente
  • Confirme se a chave está correta
  • Verifique se está usando a chave do ambiente correto
Problema: Chave válida mas sem permissãoSolução:
  • Verifique se a funcionalidade está ativa na sua conta
  • Confirme se não ultrapassou os rate limits
  • Entre em contato com o suporte se necessário
Problema: Header Content-Type ausente ou incorretoSolução:
  • Adicione Content-Type: application/json
  • Verifique se o body está em formato JSON válido
Problema: Rate limit excedidoSolução:
  • Implemente backoff exponencial
  • Distribua requisições ao longo do tempo
  • Considere upgrade de plano se necessário

​
Migração para Produção

​
Checklist de Preparação

1

Teste Completo

Execute todos os cenários em desenvolvimento
2

Configuração de Variáveis

Configure variáveis de ambiente de produção
3

Webhooks de Produção

Configure URLs de webhook para produção
4

Monitoramento

Implemente logs e alertas
5

Backup e Rollback

Prepare plano de contingência

​
Validação Final

Antes de ir para produção, teste:
  • Autenticação com chaves de produção
  • Funcionalidades críticas do seu sistema
  • Webhooks e notificações
  • Tratamento de erros
  • Rate limits e timeout
  • Logs e monitoramento
Dica: Use feature flags para ativar gradualmente o ambiente de produção, permitindo rollback rápido se necessário.