🏆 Boas Práticas de Integração
Siga estas recomendações para garantir uma integração segura, performática e confiável com as APIs Credsystem.
🔐 1. Segurança
Proteção de Credenciais
NUNCA armazene credenciais em:
- Código-fonte versionado (Git, SVN)
- Frontend de aplicações web
- Aplicativos móveis (código JavaScript, variáveis)
- Logs de aplicação
- Mensagens de erro visíveis ao usuário
Use variáveis de ambiente ou cofres de segredos (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault) para armazenar:
client_idclient_secret- Tokens de acesso
- Chaves de criptografia
HTTPS Obrigatório
Todas as requisições devem usar HTTPS (TLS 1.2+). Conexões HTTP não criptografadas serão rejeitadas.
Validação de Certificados SSL
// ✅ BOM - Validação ativa
const https = require('https');
const agent = new https.Agent({
rejectUnauthorized: true // Padrão seguro
});
// ❌ RUIM - Nunca faça isso em produção
const agentInseguro = new https.Agent({
rejectUnauthorized: false // PERIGOSO!
});
⚡ 2. Performance e Rate Limiting
Respeite os Limites de Taxa
- Autenticação: 10 requisições/minuto por client_id
- APIs de Consulta: 100 requisições/minuto
- APIs de Transação: 50 requisições/minuto
Exceder estes limites resultará em erro 429 Too Many Requests.
Implemente Cache
Faça cache de dados que mudam raramente:
- Tokens de autenticação (até 5 minutos antes da expiração)
- Listas de estabelecimentos
- Configurações de produtos
- Dados mestres
Não faça cache de:
- Transações financeiras
- Saldos e limites
- Status de pagamento
// Exemplo de cache de token
class TokenCache {
constructor() {
this.token = null;
this.expiresAt = null;
}
isValid() {
return this.token && this.expiresAt > Date.now() + 300000; // 5min buffer
}
set(token, expiresIn) {
this.token = token;
this.expiresAt = Date.now() + (expiresIn * 1000);
}
}
🔄 3. Tratamento de Erros e Retry
Estratégia de Retry
Implemente retry com backoff exponencial apenas para erros temporários:
- 5xx - Erros de servidor (retry recomendado)
- 429 - Rate limit (aguarde e tente novamente)
- 408 - Timeout (retry recomendado)
NÃO faça retry para:
- 4xx - Erros de cliente (dados inválidos)
- 401/403 - Erros de autenticação
import time
import requests
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry
# Configurar retry automático
retry_strategy = Retry(
total=3,
backoff_factor=2, # 1s, 2s, 4s
status_forcelist=[429, 500, 502, 503, 504],
method_whitelist=["GET", "POST"]
)
adapter = HTTPAdapter(max_retries=retry_strategy)
session = requests.Session()
session.mount("https://", adapter)
Log de Erros Adequado
Registre nos logs:
- Request ID
- Timestamp
- Endpoint chamado
- Código de status HTTP
- Mensagem de erro da API
NUNCA registre:
- Tokens de autenticação completos (máximo últimos 4 dígitos)
- CPF/CNPJ completos (mascare:
123.***.***-01) - Dados de cartão
- Senhas ou secrets
📡 4. Integração Assíncrona
Use Webhooks quando disponível
Para operações longas (aprovação de empréstimo, compensação de pagamento), use webhooks ao invés de polling:
Vantagens:
- ✅ Menor latência
- ✅ Menos requisições desnecessárias
- ✅ Melhor experiência do usuário
- ✅ Economia de recursos
Configure webhooks no painel do desenvolvedor.
Idempotência
Use headers de idempotência para operações críticas:
X-Idempotency-Key: uuid-unico-por-operacao
Isso garante que transações duplicadas acidentais não sejam processadas.
const { v4: uuidv4 } = require('uuid');
async function criarTransacao(dados) {
const idempotencyKey = uuidv4();
return await fetch(url, {
method: 'POST',
headers: {
'X-Idempotency-Key': idempotencyKey,
'Authorization': `Bearer ${token}`
},
body: JSON.stringify(dados)
});
}
📊 5. Monitoramento e Observabilidade
Métricas Essenciais
Implemente monitoramento para:
- Taxa de sucesso/erro de chamadas API
- Tempo médio de resposta
- Distribuição de códigos HTTP
- Taxa de retry
- Disponibilidade dos endpoints
- Uso de rate limit (% do máximo)
Health Checks
// Endpoint de health check da sua aplicação
app.get('/health', async (req, res) => {
const checks = {
api: await checkApiConnection(),
database: await checkDatabase(),
cache: await checkCache()
};
const isHealthy = Object.values(checks).every(c => c.ok);
res.status(isHealthy ? 200 : 503).json({
status: isHealthy ? 'healthy' : 'unhealthy',
checks
});
});
🧪 6. Ambientes de Teste
Sempre teste em homologação antes de produção:
Homologação:
- Dados fictícios
- Sem cobranças reais
- Testes ilimitados
- Reset de dados disponível
Produção:
- Dados reais
- Transações financeiras reais
- Monitoramento rigoroso
- Suporte 24/7
Dados de Teste
Use estes CPFs para testes em homologação:
00000000191- Cliente com limite aprovado11111111111- Cliente sem limite99999999999- Cliente com restrição
⚠️ Estes CPFs NÃO funcionam em produção!
📱 7. Integrações Mobile
Para apps mobile:
- ✅ Use backend intermediário (BFF - Backend For Frontend)
- ✅ Implemente certificate pinning
- ✅ Use ProGuard/R8 (Android) e bitcode (iOS)
- ❌ NUNCA armazene secrets no código do app
- ❌ NUNCA faça chamadas diretas do app para APIs
📝 8. Versionamento de API
As APIs Credsystem usam versionamento na URL:
/v1/- Versão 1 (legado)/v2/- Versão 2 (atual)
Sempre use a versão mais recente quando disponível. Versões antigas podem ser descontinuadas com aviso prévio de 6 meses.
🎯 Checklist de Produção
Antes de ir para produção, certifique-se de:
- Credenciais em variáveis de ambiente seguras
- HTTPS/TLS configurado corretamente
- Retry com backoff exponencial implementado
- Cache de tokens implementado
- Logs seguros (sem dados sensíveis)
- Monitoramento e alertas configurados
- Tratamento de erros robusto
- Testes completos em homologação
- Documentação interna atualizada
- Rate limiting respeitado
- Idempotência implementada para operações críticas
- Health checks funcionando
- Plano de rollback definido
Após validar este checklist, entre em contato com o suporte técnico para iniciar o processo de homologação e liberação de credenciais de produção.