Buenas prácticas
Recomendaciones de producción para operar integraciones con Core.
Esta página recoge las prácticas operativas que separan una integración de Core que funciona en sandbox de una que sobrevive en producción. La mayoría no son opcionales — así es como mantienes el ledger consistente, evitas duplicados cuando la red parpadea y respondes rápido cuando algo sale mal.
Si estás desplegando Core para mover dinero real, trata esta página como un checklist antes del lanzamiento y como referencia durante incidentes.
Esta página es un esqueleto de buenas prácticas. La versión completa incluirá ejemplos concretos, antipatrones a evitar y runbooks para los modos de falla de producción más comunes.
Idempotencia en cada write
Cada write a Core — crear una transacción de ledger, emitir una tarjeta, disparar una dispersión — debe incluir una clave de idempotencia. Sin ella, un timeout de red duplicará la escritura en silencio.
Concilia contra el ledger, no contra tu caché
El ledger de Core es la fuente de verdad. La base de datos de tu aplicación puede desincronizarse; el ledger no. Construye un job de conciliación que compare periódicamente tu vista de saldos contra el ledger y exponga cualquier desviación.
Los webhooks no reemplazan al polling
Los webhooks se disparan de forma async y pueden llegar fuera de orden o ser reintentados. Para operaciones en estado final (transacciones liquidadas, dispersiones completadas), consulta la API en el momento en que tu lógica de negocio depende del resultado. Usa webhooks para despertar tu sistema; usa la API para confirmar.
Rota las claves con un calendario
Las API keys no expiran automáticamente. Rótalas al menos cada 90 días e inmediatamente después de cualquier exposición sospechada. Mantén un procedimiento de rotación documentado que no dependa de la memoria humana.
Logea el request ID
Cada respuesta de Core lleva un request ID. Logéalo en cada petición e inclúyelo en tu reporte de errores. Cuando escales un problema a soporte de Mono, el request ID es el camino más corto al diagnóstico.
Antipatrones a evitar
- Reutilizar una sola API key entre staging y producción.
- Hardcodear URLs de webhook sin una forma de rotarlas.
- Tratar la respuesta síncrona de una dispersión como confirmación de settlement.
- Mantener entradas de ledger en memoria entre procesos — siempre escribe en el ledger.