> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Mejores prácticas > Pix es un sistema de pago en tiempo real, pero una integración confiable depende de más que solo llamar APIs. Seguir las prácticas a continuación ayuda a asegurar un comportamiento predecible, seguridad operacional y cumplimiento con las expectativas de BACEN — especialmente bajo volumen, inestabilidad de red o escenarios de disputa. Estas recomendaciones aplican a todos los casos de uso de Pix: billeteras, pagos a comerciantes, cash-outs, flujos de código QR, operaciones recurrentes y transferencias internas. # 1. Usa IDs de transacción idempotentes *** Siempre envía un `transactionId` **único e inmutable** creado por tu sistema. Trátalo como tu **clave de idempotencia**: * Si reintentas una solicitud debido a timeout, **reutiliza el mismo ID**. * Si el primer intento tuvo éxito, Pix Switch devolverá el mismo resultado. * Si el primer intento falló antes del procesamiento, el reintento creará la transacción exactamente una vez. Esto previene: * Registros duplicados en el libro mayor * Débitos dobles * Correcciones operacionales manuales * Inconsistencias de conciliación **Nunca generes un nuevo ID durante un reintento.** Además, Pix Switch soporta el header HTTP estándar IETF `Idempotency-Key` en los endpoints de creación de pago e iniciación de devolución. El middleware hace replay de la respuesta cacheada completa de forma transparente para solicitudes duplicadas (Pix Switch no retorna el header `X-Idempotency-Replayed`). Para más detalles, consulta [Reintentos e idempotencia](/es/reference/retries-idempotency). # 2. Confía en los webhooks para el estado final de la transacción *** Un `200 OK` de la API **no garantiza que el Pix se completó**. Solo significa que la solicitud entró en el flujo de orquestación. El estado autoritativo es el webhook: * Muestra el estado final al usuario **solo** después de la confirmación del webhook * Persiste el estado del webhook en tu sistema * Maneja tanto notificaciones de éxito como de falla Esperar el webhook alinea tu UI con la **liquidación confirmada por SPI**, reduciendo disputas y falsos positivos. # 3. Valida la autenticidad del webhook *** Cada webhook incluye una firma HMAC (ej., `X-Signature`). Mejores prácticas: * Almacena el secreto en una bóveda * Recalcula el HMAC usando el **cuerpo de la solicitud sin procesar** * Compara con el header * Rechaza y registra las discrepancias Esto protege contra: * Callbacks falsos * Payloads manipulados * Solicitudes no autorizadas llegando a tu endpoint La seguridad del webhook es un requisito de nivel PSP — trátalo como tal. # 4. Diseña para fallas y reintentos *** Pix es instantáneo; la red a su alrededor no lo es. Espera fallas en: * Conectividad PSTI / proveedor directo * Entrega de Telecom / SMS (para confirmación de claves) * Timeouts de red * Validaciones internas del libro mayor * Verificaciones de límites y antifraude (reguladas) Enfoque recomendado: * Implementa **políticas de reintento claras** (backoff exponencial, loops controlados) * Nunca reintentas ciegamente * Muestra mensajes accionables al usuario * Registra todas las fallas con IDs de correlación * Trata "pendiente" como un estado intermediario normal Una integración Pix confiable es resiliente por diseño. # 5. Monitorea transacciones pendientes y trabajos en segundo plano *** Un Pix puede entrar en **PENDING** mientras espera: * Procesamiento del proveedor * Reconocimiento de SPI * Entrega de webhook * Ciclos de reintento El Pix Switch ejecuta workers en segundo plano para garantizar consistencia eventual: * Reintentar callbacks * Conciliar estados intermedios * Detectar operaciones atascadas Tus responsabilidades: * Monitorea transacciones pendientes regularmente * Configura alertas para intentos de reintento excesivos * Integra logs, métricas y trazas para observabilidad **Pendiente ≠ falla**, pero pendiente prolongado requiere investigación. # 6. Mantén las claves Pix y datos de clientes sincronizados *** Porque las claves están vinculadas a la identidad: * Si un usuario cambia teléfono/correo electrónico → actualiza o elimina las claves Pix asociadas * Mantén los registros de CRM alineados con los datos de DICT * Elimina claves desactualizadas para evitar enrutamiento incorrecto * Para instituciones que usan DICT: Asegura que los reclamos de portabilidad y propiedad sigan las reglas de BACEN Esto reduce: * Pagos a destinatarios incorrectos * Casos MED debido a claves incorrectas * Fricción de soporte La consistencia entre CRM ↔ DICT ↔ Pix Switch es esencial. # 7. Respeta las expectativas de SLA y ventanas de tiempo *** La liquidación de Pix ocurre en **hasta 10 segundos**, pero los SLAs legales también importan. Diseña tu UX para respetar: * Tolerancias máximas de SPI * Ajustes de límites nocturnos (20:00–06:00) * Retrasos en reducción de límites controlados por el cliente (inmediatos) * Aumentos de límites controlados por el cliente (pueden requerir autenticación o período de espera) Siempre muestra: * "Procesando…" mientras esperas confirmación * Guía de "Intentar de nuevo" para violaciones de límites Tu UX debe reflejar el comportamiento regulatorio real de Pix. # 8. Implementa conciliación y validación contable *** La conciliación cierra el ciclo entre: * Tu sistema * El Pix Switch * Liquidación de SPI * Registros en el libro mayor (Midaz) Ciclo de conciliación recomendado: * Confirma cada Pix liquidado usando tu log de webhooks * Empareja cada ID de Pix con un registro en el libro mayor * Compara resúmenes diarios con salidas de proveedor/SPB * Marca cualquier discrepancia para revisión manual Esto reduce el ruido operacional y apoya la preparación para auditorías. # 9. Prueba de extremo a extremo con flujos realistas *** Antes de entrar en producción, simula: * Cash-in y cash-out * Límites de alto valor * Claves inválidas * Códigos QR expirados * Reembolsos (entrantes + salientes) * Disparadores de reembolso relacionados con MED * Tiempo de inactividad del webhook * Patrones de timeout y reintento de API También prueba escenarios de **Pix intra-ledger** cuando ambas cuentas existen en Midaz. Tu checklist de validación: * Registros correctos en el libro mayor * Transiciones de estado de Pix correctas * Manejo apropiado de webhooks * Aplicación apropiada de límites * Comportamiento contable apropiado # 10. Prepara a tus equipos de soporte y operaciones *** Los equipos de soporte deben entender: * Plazos de Pix (incluyendo reglas de límites nocturnos) * Diferencia entre "iniciado", "pendiente", "completado", "reembolsado", "fallido" * Cómo leer IDs E2E * Cómo rastrear problemas de DICT * Cuándo aplica MED vs reembolsos normales Flujos de soporte claros reducen la fricción del usuario y evitan disputas MED falsas.