# Boas práticas

> Como enviar transações de forma confiável: o que enviar, formato dos dados, segurança das credenciais, tratamento de respostas e imutabilidade.

Página: https://doc.rapidchargeback.com/canais/transactions/boas-praticas/

## Envio de dados

- **Envie todos os campos disponíveis.** Quanto mais dados você fornecer, maior a eficácia das soluções contratadas. Campos como `card_bin`, `order_number`, `ip_address` e `addresses` são especialmente importantes.

- **Use envio em lote para grandes volumes.** Em vez de enviar uma transação por requisição, agrupe até 1000 transações no endpoint `/transactions/batch` para reduzir overhead de rede.

- **Mantenha `external_source` e `external_id` consistentes.** Esses campos são usados para detecção de duplicatas. Use identificadores únicos e estáveis do seu sistema de origem.

- **Envie transações o mais rápido possível.** Quanto mais próximo do momento da venda, melhor a cobertura das soluções de prevenção.

## Formato dos dados

- **`transaction_date` em ISO 8601.** Use o formato completo com timezone (ex: `2026-04-01T15:30:00Z`).

- **`currency` em maiúsculas.** Use o código ISO 4217 com 3 letras maiúsculas (ex: `USD`, `BRL`, `EUR`).

- **`card_last4` como string.** Envie como string de exatamente 4 dígitos (ex: `"0042"`, não `42`).

- **`merchant_id` como UUID.** Use o UUID do merchant conforme retornado pela API ou painel.

## Segurança

- **Nunca exponha seu `client_secret`.** Trate como senha. Não inclua em código frontend, repositórios públicos ou logs.

- **Use sempre HTTPS.** Todas as requisições devem ser feitas via HTTPS.

- **Implemente retry com espera progressiva.** Em erro 500 (erro interno), aguarde antes de tentar novamente: 1s, 2s e depois 4s entre tentativas. No `429` não precisa chutar, a resposta traz o header `Retry-After` com os segundos exatos até a janela virar (ver [Rate limit](https://doc.rapidchargeback.com/referencia/codigos-de-resposta/#rate-limit)).

## Tratamento de respostas

- **Transação única:** verifique o campo `data` para os dados da transação criada e `warnings` para avisos.

- **Envio em lote:** itere sobre `results` (sucessos com `tx_id` e `warnings`) e `errors` (falhas com `external_id`, `status` e mensagem).

- **Atente-se aos `warnings`.** Não bloqueiam a criação, mas indicam campos ausentes que impactam a eficácia das soluções.

- **Guarde o `id` retornado.** Você precisará dele para consultar, atualizar ou deletar a transação.

## Imutabilidade

- **Corrija erros antes da primeira consulta.** Transações utilizadas pelas soluções (ex: consultadas pela **Prevenção**) se tornam imutáveis. Use PATCH para corrigir dados enquanto a transação ainda não foi utilizada.