# Buenas prácticas

> Cómo enviar transacciones de forma confiable: qué enviar, formato de los datos, seguridad de las credenciales, manejo de respuestas e inmutabilidad.

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

## Envío de datos

- **Envía todos los campos disponibles.** Cuantos más datos proporciones, mayor es la eficacia de las soluciones contratadas. Campos como `card_bin`, `order_number`, `ip_address` y `addresses` son especialmente importantes.

- **Usa el envío por lotes para grandes volúmenes.** En lugar de enviar una transacción por solicitud, agrupa hasta 1000 transacciones en el endpoint `/transactions/batch` para reducir la sobrecarga de red.

- **Mantén `external_source` y `external_id` consistentes.** Estos campos se usan para detectar duplicados. Usa identificadores únicos y estables de tu sistema de origen.

- **Envía las transacciones lo antes posible.** Cuanto más cerca del momento de la venta, mejor es la cobertura de las soluciones de prevención.

## Formato de los datos

- **`transaction_date` en ISO 8601.** Usa el formato completo con zona horaria (ej.: `2026-04-01T15:30:00Z`).

- **`currency` en mayúsculas.** Usa el código ISO 4217 de 3 letras mayúsculas (ej.: `USD`, `BRL`, `EUR`).

- **`card_last4` como string.** Envíalo como string de exactamente 4 dígitos (ej.: `"0042"`, no `42`).

- **`merchant_id` como UUID.** Usa el UUID del merchant tal como lo devuelve la API o el panel.

## Seguridad

- **Nunca expongas tu `client_secret`.** Trátalo como una contraseña. No lo incluyas en código frontend, repositorios públicos ni logs.

- **Usa siempre HTTPS.** Todas las solicitudes deben hacerse por HTTPS.

- **Implementa reintentos con espera progresiva.** Ante un error 500 (error interno), espera antes de intentar de nuevo: 1s, 2s y luego 4s entre intentos. En el `429` no hace falta adivinar: la respuesta trae el header `Retry-After` con los segundos exactos hasta que la ventana se reinicie (ver [Rate limit](https://doc.rapidchargeback.com/es/referencia/codigos-de-resposta/#rate-limit)).

## Manejo de respuestas

- **Transacción única:** revisa el campo `data` para los datos de la transacción creada y `warnings` para los avisos.

- **Envío por lotes:** recorre `results` (éxitos con `tx_id` y `warnings`) y `errors` (fallas con `external_id`, `status` y mensaje).

- **Presta atención a los `warnings`.** No bloquean la creación, pero indican campos ausentes que afectan la eficacia de las soluciones.

- **Guarda el `id` devuelto.** Lo vas a necesitar para consultar, actualizar o eliminar la transacción.

## Inmutabilidad

- **Corrige los errores antes de la primera consulta.** Las transacciones usadas por las soluciones (ej.: consultadas por la **Prevención**) se vuelven inmutables. Usa PATCH para corregir datos mientras la transacción todavía no fue usada.