> ## 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 > Mejores prácticas para integraciones Pix confiables: claves endToEndId idempotentes, confirmación por webhook, firmas HMAC y patrones de reintento y observabilidad. Seguir las prácticas de abajo ayuda a garantizar un comportamiento predecible, seguridad operativa y cumplimiento de las expectativas de BACEN, sobre todo en escenarios de volumen, inestabilidad de red o disputas. Estas recomendaciones aplican a todos los casos de uso de Pix: billeteras, pagos a comercios, cash-outs, flujos con QR Code, operaciones recurrentes y transferencias internas. # 1. Usa una clave de pago idempotente *** En el flujo de pago Pix, el `endToEndId` de BACEN es tu **clave de idempotencia**. Es un identificador único e inmutable de 32 caracteres que tú entregas o que genera Pix Lerian. Solo puedes reintentar de forma segura cuando el valor es tuyo. Trata el `endToEndId` como tu **clave de idempotencia**: * Si reintentas una solicitud después de un timeout, **reutiliza el mismo `endToEndId`**. * Si el primer intento ya creó el pago, Pix Lerian reproduce el existente. * Si el primer intento falló antes del procesamiento, el reintento crea el pago exactamente una vez. Esto evita: * Asientos duplicados en el ledger * Débitos dobles * Correcciones operativas manuales * Inconsistencias de conciliación **Nunca generes un nuevo `endToEndId` para un reintento.** Para el comportamiento de idempotencia en el nivel de header de cada producto Lerian, 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 del webhook: * Muestra el estado final al usuario **solo** después de la confirmación por webhook * Persiste el estado del webhook en tu sistema * Gestiona tanto las notificaciones de éxito como las de fallo Esperar el webhook alinea tu UI con la **liquidación confirmada por SPI**, lo que reduce disputas y falsos positivos. # 3. Valida la autenticidad del webhook *** Cada webhook incluye una firma HMAC (por ejemplo, `X-Signature`). Mejores prácticas: * Guarda el secreto en una bóveda * Recalcula el HMAC usando el **cuerpo crudo de la solicitud** * Compara con el header * Rechaza y registra las discrepancias Esto protege contra: * Callbacks falsos * Payloads manipulados * Solicitudes no autorizadas que llegan a tu endpoint La seguridad de los webhooks es un requisito en el nivel de PSP. # 4. Diseña para fallos y reintentos *** Pix es instantáneo. La red a su alrededor no lo es. Espera fallos en: * Conectividad del PSTI / proveedor directo * Entrega de telecomunicaciones / SMS (para la confirmación de claves) * Timeouts de red * Validaciones internas del ledger * Comprobaciones de límites y antifraude (reguladas) Enfoque recomendado: * Implementa **políticas de reintento claras** (backoff exponencial, bucles controlados) * Nunca reintentes a ciegas * Muestra al usuario mensajes accionables * Registra todos los fallos con IDs de correlación * Trata “pending” como un estado intermedio normal # 5. Monitorea las transacciones pendientes y los jobs en segundo plano *** Un Pix puede entrar en **PENDING** mientras espera: * El procesamiento del proveedor * El acuse de recibo del SPI * La entrega del webhook * Ciclos de reintento Pix Lerian ejecuta workers en segundo plano para garantizar la consistencia eventual: * Reintentar callbacks * Conciliar estados intermedios * Detectar operaciones atascadas Tus responsabilidades: * Monitorear las transacciones pendientes con regularidad * Configurar alertas para intentos de reintento excesivos * Integrar logs, métricas y trazas para la observabilidad **Pending ≠ fallo**, pero un pending prolongado requiere investigación. # 6. Mantén las claves Pix y los datos de clientes sincronizados *** Como las claves están ligadas a la identidad: * Si un usuario cambia de teléfono/correo → actualiza o elimina las claves Pix asociadas * Mantén los registros del CRM alineados con los datos del DICT * Elimina las claves desactualizadas para evitar enrutamientos erróneos * Para las instituciones que usan DICT: Confirma que las reclamaciones de portabilidad y titularidad siguen las reglas de BACEN Esto reduce: * Pagos a receptores equivocados * Casos de MED por claves incorrectas * Fricción en soporte La consistencia entre CRM ↔ DICT ↔ Pix Lerian es esencial. # 7. Respeta las expectativas de SLA y las ventanas de tiempo *** La liquidación de Pix ocurre en **hasta 10 segundos**, pero los SLA legales también cuentan. Diseña tu UX para respetar: * Las tolerancias máximas del SPI * Los ajustes de límite nocturno (20:00–06:00) * Los plazos de reducción de límite pedida por el cliente (inmediata) * Los aumentos de límite pedidos por el cliente (pueden requerir autenticación o un período de espera) Muestra siempre: * “Procesando…” mientras esperas la confirmación * Orientación de “Intentar de nuevo” para límites superados Tu UX debe reflejar el comportamiento regulatorio de Pix. # 8. Implementa conciliación y validación contable *** La conciliación cierra el ciclo entre: * Tu sistema * Pix Lerian * La liquidación en el SPI * Los asientos del ledger (Midaz) Ciclo de conciliación recomendado: * Confirma cada Pix liquidado con tu log de webhooks * Haz coincidir cada ID de Pix con un asiento del ledger * Compara los resúmenes diarios con las salidas del proveedor/SPB * Marca cualquier discrepancia para revisión manual Esto reduce el ruido operativo y respalda 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 * QR Codes expirados * Devoluciones (entrantes + salientes) * Disparadores de devolución relacionados con MED * Caídas de webhooks * Patrones de timeout y reintento de la API Prueba también escenarios de **Pix intra-ledger** cuando las dos cuentas existen en Midaz. Tu lista de validación: * Asientos del ledger correctos * Transiciones de estado de Pix correctas * Manejo adecuado de webhooks * Aplicación adecuada de límites * Comportamiento contable adecuado # 10. Prepara tus equipos de soporte y operaciones *** Se recomienda que los equipos de soporte entiendan: * Los plazos de Pix (incluidas las reglas de límite nocturno) * La diferencia entre “initiated”, “pending”, “completed”, “refunded”, “failed” * Cómo leer los IDs E2E * Cómo dar seguimiento a los problemas del DICT * Cuándo aplica MED frente a las devoluciones normales Flujos de soporte claros reducen la fricción del usuario y evitan disputas MED falsas.