Tu tienda deja de enviar pedidos al equipo de empaque. La persona que hizo la conexión está de vacaciones y el resto encuentra tres archivos llamados «versión final». El problema se vuelve más caro porque nadie sabe cuál describe lo que funciona hoy.
Documentá cada integración con su propósito, sistemas, responsables, referencias de datos, procedimiento de comprobación y manejo de excepciones. Guardá una versión vigente donde el equipo autorizado pueda encontrarla y probá que otra persona la entiende. Las contraseñas y los tokens permanecen en su gestor autorizado; la ficha solo indica cómo solicitar acceso.
No hace falta comenzar con un manual de cincuenta páginas. Hace falta que alguien pueda responder qué debería ocurrir, cómo comprobarlo y a quién recurrir si el resultado falta. Esa información también sirve para revisar una propuesta, cambiar de proveedor y decidir qué parte requiere mantenimiento.
Elegí una conexión que tenga un resultado comprobable
«El sistema de ventas» es demasiado amplio para una primera ficha. Elegí un recorrido: desde que una persona aprueba un pedido hasta que aparece una tarea de empaque. O desde que cambia un dato del catálogo hasta que queda disponible en el canal acordado. Definí un principio y un final observables.
Después escribí qué queda fuera. Preparar una tarea de empaque no confirma el cobro ni demuestra que el transportista retiró el paquete. Si el documento mezcla esos resultados, quien lo use puede dar por terminado un trabajo que todavía depende de otra persona.
La guía para conectar WhatsApp, tienda y mostrador explica cómo distribuir datos entre canales. Este recurso aborda el paso siguiente: dejar documentado el recorrido elegido para que su operación no dependa de la memoria de quien lo instaló.
Quince campos para una ficha que se pueda usar
La plantilla separa información estable de evidencia que cambia. El nombre del proceso puede mantenerse durante meses; la persona responsable, los permisos y la última prueba necesitan revisiones. Una celda vacía debe convertirse en un pendiente asignado, no en una suposición silenciosa.
| Parte de la ficha | Pregunta que debe resolver | Evidencia útil |
|---|---|---|
| Identidad, propósito y alcance | ¿Qué conexión es y qué resultado cubre? | Nombre único, versión y límites |
| Responsables y sistemas | ¿Quién responde por cada extremo? | Roles, suplente y ambientes |
| Referencias y datos | ¿Cómo se relacionan los registros? | Ejemplo ficticio y fuente de cada campo |
| Disparador y acceso | ¿Cuándo empieza y quién puede revisarla? | Condición de inicio y procedimiento autorizado |
| Procedimiento y comprobación | ¿Qué pasos se siguen y qué confirma el resultado? | Secuencia y referencia de evidencia |
| Excepción y recuperación | ¿Qué hacer cuando algo falta? | Límites de actuación y escalamiento |
| Dependencias y mantenimiento | ¿Qué se afecta si cambia y cuándo se revisa? | Registro de cambios y próxima comprobación |
Las filas de la tabla agrupan los quince campos del archivo. No todos necesitan un párrafo largo: una referencia a un procedimiento vigente puede ser suficiente cuando ese procedimiento existe y el equipo tiene permiso para consultarlo.
Dejá una guía que tu suplente pueda usar. Descargá la ficha Excel de quince campos, mapa y prueba de entrega o el ficha de campos en CSV sin fórmulas. Incluye una integración ficticia y hojas de revisión y cambios. No guarda credenciales ni se conecta a sistemas.
Separá la responsabilidad comercial de la técnica
La persona de ventas puede confirmar si un pedido debería pasar a preparación. La persona técnica puede revisar por qué la conexión no produjo el resultado. Un suplente necesita saber a quién acudir en ambos casos. Anotá roles y referencias de contacto internas que el negocio pueda mantener actualizadas.
No escribás únicamente el nombre de quien programó. Agregá quién acepta el resultado, quién autoriza un cambio y quién conserva el documento. Si hay un proveedor externo, indicá el canal de soporte contratado y la información necesaria para abrir un caso. No inventés tiempos de respuesta que no estén acordados.
Asigná también el mantenimiento de la ficha. Cuando nadie tiene esa tarea, el documento queda congelado mientras cambian la tienda, los campos y las personas. Una revisión breve después de cada cambio pertinente suele aportar más que una fecha distante que nadie relaciona con el trabajo real.
Referenciá los accesos sin copiar las credenciales
La ficha puede indicar «cuenta corporativa del integrador», «permisos de consulta» y «procedimiento de solicitud en el gestor autorizado». No necesita contener el token, la contraseña ni una captura que los muestre. El lector debe poder localizar el proceso de acceso con su propia identidad autorizada.
La guía de gestión de secretos de OWASP incluye documentación y metadatos para administrar su uso y responsabilidades. Aplicamos esa separación a esta ficha: documentar para qué se necesita un acceso no exige distribuir el secreto dentro del manual.
Antes de adjuntar una imagen, revisá direcciones, cabeceras y campos ocultos. Una captura destinada a explicar dónde buscar un resultado puede exponer información que no aporta a esa explicación. Para una entrega pública o una capacitación, prepará datos ficticios y recortá la vista al paso necesario.
Una conexión también necesita una entrega operativa. KMSOFT puede ayudarte a definir responsables, documentación y pruebas del recorrido comercial. Documentar mis integraciones.
Un ejemplo ficticio: del pedido a una tarea de empaque
El archivo incluye DOC-DEMO-01, una integración ilustrativa entre una tienda de prueba y un tablero de empaque de prueba. El pedido PED-DEMO-041 debería producir la tarea TAREA-DEMO-07 con dos líneas de productos. Ninguna referencia corresponde a un cliente o instalación real.
La ficha dice que el recorrido comienza cuando la persona responsable aprueba el pedido de prueba. No afirma que se haya cobrado. El resultado esperado es que el equipo encuentre la tarea y pueda contrastar las dos líneas con la fuente acordada. El detalle de transporte queda fuera.
El procedimiento propuesto tiene cinco pasos: buscar la referencia, comprobar su estado, localizar la tarea, contrastar los productos y registrar la evidencia. Para cada paso, la persona que adapta la ficha debe indicar la pantalla o el registro real de su operación. «Revisar el sistema» no permite que otro repita la comprobación.
Si la tarea no aparece, el documento pide conservar la referencia y el estado observado, y escalar a soporte. No incluye un botón imaginario para reenviar todo. Antes de ejecutar una recuperación, el equipo debe contar con un procedimiento autorizado y comprobar qué acciones ya ocurrieron.
Escribí pasos con una salida visible
Compará dos instrucciones: «verificar la integración» y «buscar la referencia del pedido en el tablero de destino y registrar el identificador de la tarea». La segunda permite saber si el paso terminó y qué evidencia debe quedar. También permite explicar un resultado negativo sin culpar a quien está revisando.
Un paso útil indica la condición previa, la acción permitida y el resultado esperado. Cuando requiere permisos especiales, lo dice antes de comenzar. Cuando el resultado falta, señala dónde se detiene la revisión y quién continúa. Si todavía no conocés esa respuesta, registrá el pendiente con un responsable.
La orientación de AWS sobre procedimientos operativos recomienda mantener instrucciones accesibles y actualizadas, con herramientas, permisos y tratamiento de errores. La ficha traslada ese criterio a una conexión comercial pequeña; no requiere contratar servicios de AWS para utilizarla.
Entregá la ficha a alguien que no la escribió
Una revisión del autor puede pasar por alto lo que este ya sabe. Pedí a otra persona autorizada que localice la versión vigente, describa origen y destino y explique qué resultado comprobaría. Esa primera lectura puede hacerse sin ejecutar acciones ni acceder a información de clientes.
Después, si existe autorización y un ambiente de prueba, prepará un caso ficticio. Registrá qué instrucciones alcanzaron, dónde faltó contexto y qué evidencia encontró la persona. Si no hay un ambiente seguro disponible, dejá pendiente la ejecución; una explicación verbal no equivale a una prueba completada.
La hoja «Prueba de entrega» propone seis comprobaciones: localización, comprensión, acceso, caso controlado, excepción y mantenimiento. No entrega una calificación automática. El responsable registra lo observado y decide qué falta para aceptar la entrega. Esa decisión debe conservar sus límites, especialmente cuando todavía hay pasos no probados.
Conservá una versión vigente y el motivo de cada cambio
Elegí un lugar central del negocio con acceso controlado. El mapa de integraciones del recurso sirve para encontrar la ficha correspondiente; no reemplaza el repositorio o la herramienta documental que ya utilicen. Evitá que cada persona mantenga una copia distinta en una conversación privada.
Cuando cambie una conexión, anotá fecha, versión, motivo, autor, revisor y comprobación realizada. Si cambió el origen de un campo, revisá los pasos que lo usan. Si cambió un permiso, revisá las instrucciones de acceso. Un cambio pequeño puede dejar una captura correcta con una explicación equivocada.
La próxima revisión puede fijarse por una fecha acordada y adelantarse ante cambios. La ficha no impone un intervalo universal. Un proceso que cambia cada semana necesita otra atención que uno estable; ambos necesitan una persona que detecte cuándo dejó de describirse la realidad.
Convertí los vacíos en trabajo concreto
Tres vacíos habituales permiten comenzar: nadie sabe quién responde por el destino, no existe una referencia común entre registros o el paso de recuperación solo lo conoce una persona. Elegí uno, asigná responsable y definí qué evidencia permitiría cerrarlo. Completar encabezados no resuelve esas dependencias.
Cuando el flujo utiliza CatalogoCR, documentá qué dato se mantiene allí y qué parte depende de una conexión o procedimiento externo realmente contratado. La ficha no agrega integraciones a la plataforma ni demuestra que exista una sincronización entre dos herramientas.
KMSOFT puede revisar el recorrido, sus responsables y las pruebas de entrega. Somos Tech Provider de Meta y trabajamos con integraciones y agentes para WhatsApp; ese trabajo también necesita una operación documentada. El punto de partida es una conexión concreta que tu equipo quiera entender y mantener.
Preguntas frecuentes
¿Qué debe incluir la documentación de una integración?
Debe identificar propósito, alcance, sistemas, responsables, referencias, datos, disparador, acceso autorizado, procedimiento, comprobación, excepciones, recuperación, dependencias y mantenimiento. La ficha descargable organiza esos quince campos y una prueba de entrega a otra persona.
¿Puedo guardar contraseñas y tokens en la plantilla?
No. Usá referencias al gestor autorizado y al procedimiento para solicitar acceso. Las credenciales, los códigos de autenticación y los datos completos de clientes no deben copiarse en esta ficha operativa.
¿Cómo sé si otra persona puede usar el documento?
Pedile que encuentre la versión vigente y explique el recorrido y su resultado esperado. Si dispone de autorización y un ambiente seguro, realizá una prueba con datos ficticios y registrá lo observado y los pendientes.
¿La plantilla prueba o repara una integración automáticamente?
No. Es un recurso de documentación con un ejemplo ficticio. No se conecta a cuentas, ejecuta solicitudes ni aplica cambios; las comprobaciones y recuperaciones requieren responsables y procedimientos autorizados.
