Cómo documentar una integración para que no dependa de una sola persona
Por Carlos Manzano · · IA e integraciones · 4 min de lectura
En este artículo
Una integración está bien documentada cuando alguien autorizado puede entender qué hace, comprobar su estado y ejecutar una recuperación prevista sin llamar siempre a la persona que la construyó. Para ello necesitas más que una captura del flujo: hacen falta decisiones de negocio, referencias técnicas y pasos de operación.
Empieza por un documento breve situado junto al inventario de herramientas de la empresa. Dale un propietario y una fecha de revisión. La documentación debe acompañar los cambios; una guía perfecta que describe una versión antigua puede resultar más confusa que una ficha sencilla y vigente.
Explica el recorrido y sus límites
Escribe una frase con el resultado esperado: «llevar solicitudes válidas del formulario al CRM y crear una tarea para su responsable». Añade qué queda fuera, como llamadas o formularios de otras webs. Esa frontera evita que el equipo suponga que todo contacto está incluido.
Dibuja o enumera los pasos, indicando origen, transformación y destino. Para cada uno, identifica qué resultado confirma su finalización. Si existe una revisión humana, anota dónde aparece la tarea y quién debe completarla. Los pasos manuales forman parte del proceso aunque no aparezcan en el editor de automatizaciones.
| Apartado | Información que debe contener |
|---|---|
| Propósito | Resultado, usuarios y operaciones incluidas |
| Conexiones | Aplicaciones, cuentas titulares y entorno |
| Datos | Campos, identificadores y sistema responsable |
| Ejecución | Disparador, frecuencia y condiciones de paso |
| Control | Avisos, registros y comprobación del resultado |
| Recuperación | Pasos seguros para fallos conocidos |
| Mantenimiento | Propietario, última prueba y cambios pendientes |
Describe dónde están los accesos sin copiarlos
Registra quién administra cada cuenta y dónde se custodian las credenciales, utilizando el sistema de gestión de accesos del negocio. No pegues contraseñas, claves o enlaces privados con permisos amplios en una guía que leerá todo el equipo.
Anota qué permisos necesita la integración y qué persona puede renovarlos. Si una conexión depende de una cuenta personal de alguien que puede dejar la empresa, documenta la sustitución prevista. La titularidad y la continuidad del acceso son decisiones operativas, además de técnicas.
Conserva las reglas que no se ven en el diagrama
Explica por qué un campo tiene prioridad, cómo se reconocen duplicados y qué ocurre con un valor vacío. Incluye las correspondencias entre estados de aplicaciones distintas. Esas reglas suelen perderse porque parecen obvias a quien las configuró, pero determinan cómo interpreta el negocio los datos.
Guarda ejemplos ficticios de entrada y salida para que puedan consultarse sin exponer clientes. Si el flujo genera un resumen con IA, incorpora instrucciones, formato esperado y casos que deben derivarse a revisión. La versión del modelo o herramienta también puede ser relevante al investigar un cambio de comportamiento.
Añade procedimientos cortos para tareas habituales
Una guía para reintentar una operación debería indicar qué comprobar antes, qué acción ejecutar y qué resultado esperar. La referencia de AWS sobre procedimientos operativos propone documentar tareas repetibles y validarlas con otras personas. Adapta ese enfoque al tamaño de tu equipo, sin convertir cada acción sencilla en un manual extenso.
Separa las tareas rutinarias de las incidencias que requieren diagnóstico. Si no se conoce el resultado de una operación de pago o un envío, el procedimiento debe llevar a comprobarlo antes de repetir. La documentación no debería animar a pulsar un botón por ensayo y error.
Ejemplo ficticio de un relevo
Una agencia cambia a la persona que mantiene la conexión de formularios de un cliente. Es un ejemplo ficticio. La nueva responsable recibe un mapa de campos, los accesos custodiados, una muestra de prueba y el procedimiento de recuperación. Puede verificar el recorrido sin utilizar datos reales ni modificar la web pública.
Durante esa prueba descubre una instrucción desactualizada y la corrige. El relevo funciona también como revisión: si necesita explicaciones verbales para cada paso, esas decisiones todavía no están suficientemente documentadas.
Usa la documentación como criterio de entrega
Antes de dar por terminada una integración, pide a otra persona que localice el último resultado, identifique un fallo de prueba y explique cómo detener el flujo. Registra qué no pudo resolver. Completar esos huecos aporta continuidad real y facilita presupuestar el mantenimiento posterior.
Si necesitas aplicar este trabajo a tu empresa, puedes consultar el servicio de implantación de IA e integraciones o contarme tu situación y el objetivo que quieres conseguir.
Para seguir avanzando
Sigue explorando IA e integraciones
Artículos relacionados
