Integracion REST externa (clave de API)
La integracion REST externa es una «puerta» controlada a traves de la cual otro sistema (un ERP, el backend de un sitio, 1C o una capa de integracion, una aplicacion propia) puede crear y actualizar tareas y oportunidades en LadVen OS mediante una API estandar con una clave de acceso. Con ello nadie transmite usuario ni contrasena y nadie trabaja como administrador.
Cada llamada se ejecuta desde una cuenta de servicio (bot) independiente con los permisos minimos necesarios: solo las acciones que usted haya autorizado y solo en los departamentos, proyectos, pipelines y etapas que haya definido. Todas las peticiones pasan por las reglas habituales del portal —acceso, comprobaciones, automatizacion, notificaciones— y quedan registradas en un historial que se puede consultar por cada integracion.
La conexion se anade una sola vez en el Hub de integraciones (seccion CRM → Integraciones, ruta /crm/integrations).
Cuando usarla
La integracion REST es necesaria cuando «algo ocurre en otro sistema y en LadVen OS debe aparecer automaticamente una tarea o una oportunidad». Escenarios tipicos:
- el ERP o el sitio crea una tarea o un caso cuando llega un pedido, una solicitud o un ticket;
- una aplicacion propia mantiene las tareas y las oportunidades sincronizadas con una base externa;
- un sistema externo adjunta archivos, deja comentarios, registra tiempo o mueve la oportunidad por las etapas a medida que avanza el trabajo en el otro lado.
En que se diferencia de los formularios y los webhooks: el formulario del sitio y el webhook son una recepcion unidireccional de solicitudes en el CRM. La integracion REST es una conexion programatica bidireccional: el sistema externo lee (obtiene tareas, oportunidades, historial) y escribe (crea y actualiza). El portal en si no envia webhooks salientes a traves de esta conexion: la parte externa se dirige al portal por su cuenta.
Como configurarla
La conexion se crea con un asistente paso a paso (CRM → Integraciones → anadir «Integracion REST externa»). Por pasos, en terminos de trabajo:
- Nombre y actividad. Asigne un nombre claro a la integracion y decida si activarla de inmediato. Se puede lanzar la comprobacion de conexion en el acto.
- Cuenta de servicio. Elija un bot existente o cree uno nuevo dentro del asistente (nombre y usuario). No es un empleado ni un administrador: la integracion trabaja en su nombre. Si elige una cuenta con permisos de administrador, el asistente avisara: esta pensado asi, las integraciones reciben el minimo de permisos.
- Escenario y nivel de permisos. Elija el conjunto de operaciones para la tarea: «Tareas y CRM», «Solo tareas» o «Solo CRM». Despues, el nivel de permisos: solo lectura, creacion y edicion o gestion. Los permisos se aplican a la cuenta de servicio antes de emitir la clave.
- Acciones permitidas. Marque las operaciones concretas que la integracion puede ejecutar. El principio es el minimo necesario: active solo lo que realmente haga falta. Todo lo que no este marcado se rechazara antes de ejecutarse.
- Alcance. Limite la integracion a los departamentos, proyectos, pipelines y etapas necesarios. Es un marco por encima de los permisos de la cuenta: incluso una accion permitida solo funcionara dentro del alcance definido.
- Campos y limites. Defina que campos de tareas y oportunidades puede cambiar la integracion, el limite de peticiones por minuto y el pico admisible, asi como la lista blanca de direcciones IP desde las que se permiten las llamadas.
- Creacion de la clave y comprobacion. Guarde y el portal mostrara una sola vez la clave de acceso en la pantalla de resultado, con un boton para copiarla. Desde aqui mismo se puede lanzar la comprobacion de conexion.
Tras la creacion, la conexion dispone de un historial de peticiones: que operaciones se invocaron, con que resultado y con detalle de cada llamada (los datos sensibles quedan ocultos en los registros).
Seguridad y clave de acceso
La integracion REST se basa en el principio de minimos permisos, algo importante para el dueno del negocio:
- La clave se muestra una sola vez. Copiela y guardela de inmediato en un gestor de secretos. El portal no volvera a mostrar esta clave ni la almacena en texto plano. Si necesita cambiar la clave, vuelva a emitirla repasando el asistente de esa conexion.
- Cuenta de servicio independiente. La integracion no trabaja como una persona ni como administrador; tiene su propia zona de responsabilidad y sus propios permisos.
- Marcos de acceso. Las acciones permitidas, el alcance (departamentos, proyectos, pipelines, etapas), la lista blanca de campos, el limite de peticiones y la lista blanca de IP limitan que puede hacer la integracion y desde donde.
- Historial. Cada llamada queda registrada: se puede revisar quien y que cambio a traves de la integracion.
Nunca muestre en capturas de pantalla ni publique la clave real, la cabecera de autorizacion, las direcciones IP de la lista blanca ni el usuario de la cuenta de servicio. Para las ilustraciones utilice valores obviamente ficticios.
Errores frecuentes
- Dar a la integracion una cuenta de administrador en lugar de un bot de servicio.
- Activar mas acciones de las necesarias en vez del conjunto minimo imprescindible.
- No copiar la clave de un solo uso al crearla.
- No definir la lista blanca de IP ni el limite de peticiones.
- Definir un alcance demasiado amplio: todo el portal en lugar de un unico pipeline necesario.
- Esperar que el portal empiece a enviar por su cuenta webhooks salientes: la integracion funciona con llamadas entrantes, es el sistema externo el que se dirige al portal.
Como verificar que funciona
- Lance la comprobacion de conexion al final del asistente (o active su ejecucion de inmediato).
- Asegurese de que la tarjeta de la conexion muestra un estado activo y correcto.
- Revise el historial de peticiones: alli deben constar llamadas exitosas.
- Compruebe que la tarea u oportunidad de prueba aparecio con el responsable, el pipeline y la etapa correctos, y que la automatizacion y las notificaciones funcionaron como de costumbre.