Integraciones de agentes, canales y proveedores de AI Dashboard

Configura cada integración mediante el contrato que le corresponde. AI Dashboard presenta los flujos de agentes e integraciones; la API de Ordering.co autoriza los registros y acciones centrales; cada canal o proveedor controla su propia identidad, entrega, límites y fallos.

Límite del ciclo de vida del agente

El frontend puede listar, crear, actualizar, habilitar, deshabilitar, registrar y supervisar registros de agentes compatibles mediante el cliente de API. También solicita esquemas de configuración de proveedores y genera formularios a partir del esquema recibido.

• Trata el esquema de proveedor devuelto como el contrato actual del formulario. No codifiques una lista de proveedores ni copies campos secretos en constantes del cliente.
• Valida en la interfaz para ofrecer respuesta inmediata y confía en la validación y autorización del servidor para la decisión final.
• Mantén separados los estados configured, enabled, del sitio, SSL y supervisión. Que uno tenga éxito no demuestra que otro límite esté listo.
• Oculta los campos secretos conocidos y nunca devuelvas al navegador la credencial completa después del envío inicial.
• No deduzcas la compatibilidad con un proveedor por el nombre de un componente o un fixture de prueba; confirma el esquema de proveedor devuelto para el entorno previsto.

Canales y conversaciones

Superficie	Responsabilidad del frontend	Responsabilidad del servidor/proveedor	Límite del fallo
Configuración del agente	Mostrar ajustes basados en esquema, enviar cambios autorizados y presentar un estado saneado.	La API valida el registro del agente; el proveedor valida las credenciales del canal y el estado de la cuenta.	Un registro guardado aún puede estar sin configurar, deshabilitado o rechazado por el proveedor.
Conexión de WhatsApp	Presentar el flujo manual o de inicio de sesión de negocio compatible, bloquear campos gestionados por el proveedor y conservar el estado de conexión devuelto.	El flujo de API y Meta intercambia y protege credenciales e identificadores externos.	La finalización de OAuth, la revisión del proveedor, el estado del teléfono y la entrega de mensajes pueden fallar por separado.
Conversaciones	Consultar conversaciones autorizadas, mostrar el historial y suscribirse a actualizaciones en tiempo real compatibles.	La API controla el acceso y el historial; los sistemas de sockets/canales entregan eventos.	Un socket activo no demuestra que el historial esté completo, y un resultado de API no demuestra entregas futuras.
Voz u otros canales	Mostrar únicamente esquemas y rutas que se devuelvan como compatibles.	El proveedor controla el transporte de medios, la identidad, el consentimiento y los límites específicos del canal.	La capacidad del navegador y la aceptación del proveedor son independientes.
Sitios de agentes	Mostrar la configuración y el estado del sitio que devuelve la API.	La persona responsable del sitio/despliegue controla la provisión, DNS, certificados y estado de publicación.	Un dominio o valor de estado en una respuesta del agente no demuestra de forma independiente que se haya desplegado.

Importadores e integraciones de negocio

El importador de menús es un servicio FastAPI independiente. El navegador envía el contexto bearer de la persona con sesión iniciada, el contexto del proyecto y de API, los negocios seleccionados y la entrada específica del origen. El servicio valida el origen, obtiene o recibe los datos, los normaliza al formato Ordering.co Menu Sync v2, puede copiar imágenes compatibles al almacenamiento de objetos y envía el menú normalizado a la API de Ordering.co.

Mantén separados estos resultados:

1. se aceptó la entrada del origen;
2. se obtuvieron los datos externos;
3. se normalizaron los datos;
4. se copiaron las imágenes opcionales;
5. se aceptó la sincronización con la API de Ordering.co para cada negocio seleccionado; y
6. Dashboard invalidó la caché y volvió a leer el catálogo resultante.

Una importación parcial no equivale a un éxito completo. Informa los fallos por negocio y etapa sin registrar el token bearer, credenciales del proveedor, cargas de origen con datos de clientes ni detalles privados de almacenamiento.

Las integraciones de POS, canales de venta, entrega, pagos y marketing siguen la misma regla de responsabilidad: una tarjeta o indicador de función visible permite que el frontend presente un flujo; el acceso al negocio, el estado del plugin, las credenciales del proveedor y la aceptación del proveedor se siguen aplicando de forma independiente.

Seguridad de proveedores

• Mantén fuera del frontend y del control de código fuente las claves de service role, secretos compartidos internos, secretos de clientes OAuth, claves de cifrado de tokens y tokens de acceso de proveedores.
• Usa el estado de OAuth generado y verificado por el servidor. No construyas el resultado de un callback únicamente con parámetros de consulta del navegador.
• Mantén las listas de redirecciones permitidas exactas y específicas para cada entorno. Elimina tokens y detalles innecesarios del proveedor de las URL, telemetría y capturas de soporte.
• Guarda las credenciales de larga duración cifradas mediante la ruta de backend aprobada y registra la rotación de claves sin exponer texto sin cifrar.
• Aplica el consentimiento, el propósito y las políticas de canal cuando se envía una operación, no solo cuando se conecta una integración.

Fallos y escalación

Observación	Responsable siguiente
El tipo/proveedor no aparece en la respuesta del esquema	Responsables de API y producto; no crees una opción solo en el cliente.
Se guarda el agente, pero la conexión sigue incompleta	Responsable del proveedor/autenticación; conserva por separado los estados guardado y conectado.
Carga el historial de conversaciones, pero se detienen las actualizaciones en vivo	Responsable de socket/canal; conserva el historial de API y diagnostica la entrega aparte.
Se obtienen datos de importación, pero falla la sincronización de un negocio	Responsables del importador de menús y API de Ordering.co; informa la etapa exacta y evita repetir a ciegas los negocios que tuvieron éxito.
OAuth devuelve resultado, pero las credenciales no se guardan	Responsable del servicio de proveedor y almacenamiento; no expongas errores de persistencia ni secretos al navegador.

Relacionado: Límites de servicios y datos · Guía de ingeniería de AI Dashboard