## Visión general ConversaLabs publica una referencia de **superficie pública OpenAPI 3.1** para descubrir e integrar los endpoints que pertenecen a ese contrato. Se produce a partir de rutas y fuentes curadas; no promete que toda ruta interna, módulo habilitable o formulario de la instalación se publique automáticamente. Hay tres formas de ver la misma referencia: - **ReDoc (lectura)** — una documentación navegable, organizada por grupos y tags, ideal para entender el contrato de cada endpoint: - **Swagger-UI (interactiva)** — la misma referencia con el botón **"Try it out"** para hacer llamadas reales a la API directamente desde el navegador: - **Definición OpenAPI (JSON)** — el archivo en bruto para importar en Postman, Insomnia o generar SDKs: La referencia agrupa **Account/AgentBot** en `/api/v1`, **Platform** en `/platform`, **Widget** en `/api/v1/widget`, rutas **public** en `/public/api`, metadatos públicos de descubrimiento/desafío y caminos de webhook que pertenecen al contrato. Lee la seguridad declarada por operación: no existe un token universal. ## Requisitos previos - La credencial que exige la operación: token de cuenta/AgentBot, clave de Platform App, token público propio del recurso o ninguna credencial, según el contrato. - Un navegador moderno. Para probar llamadas, prefiere un token de un entorno de pruebas. ## Paso a paso 1. Abre la referencia en (ReDoc) y navega por los grupos de módulos en la barra lateral. 2. Localiza el endpoint que necesitas (por método y ruta) y lee sus parámetros, cuerpo y respuestas. 3. Para **probar**, abre la referencia interactiva en . 4. Lee el requisito de seguridad de la operación antes de **Authorize** e ingresa solo una credencial compatible con esa ruta. 5. Elige un endpoint, haz clic en **Try it out**, completa los parámetros y usa **Execute** solo cuando el entorno de pruebas y la operación lo permitan. 6. Revisa la respuesta (estado, cuerpo) y reutiliza el ejemplo de solicitud (cURL) en tu integración. ## Configuración y opciones - **Cobertura y autenticación**: las rutas nuevas deben incluirse y revisarse en el contrato. Las operaciones pueden usar `api_access_token`, clave de Platform App, token de recurso o seguridad vacía explícita; nunca copies una credencial entre superficies por suposición. - **Webhooks entrantes**: un camino acepta llamadas solo cuando el recurso que lo configura está activo y validado. La autenticación varía por proveedor/recurso (firma, secreto, token de verificación o desafío), por lo que no es una API REST genérica para probar con un token de cuenta. - **Metrics**: `/monitoring/metrics` no es una operación de cliente. Está inerte hasta que el operador defina `OPERATIONS_METRICS_TOKEN` y exige `Authorization: Bearer ` para una recolección autorizada. - **MCP y operador**: MCP usa perfiles, URLs y credenciales Bearer/OAuth propios. La REST del operador tiene una referencia separada y no se sirve en `/swagger`. - **Disponibilidad**: en instalaciones self-hosted, la documentación la **habilita el operador** mediante una variable de entorno (`ENABLE_API_DOCS`). En la ConversaLabs alojada ya está disponible en las direcciones anteriores. ## Casos de uso - Determinar si una integración pertenece a Account/AgentBot, Platform, Widget o una superficie pública. - Consultar los requisitos de una operación antes de probar una llamada en un entorno controlado. - Importar la definición OpenAPI en Postman/Insomnia o generar un SDK cliente. ## Consejos, límites y buenas prácticas - Trata todo token o secreto como confidencial; no lo expongas en el front-end ni lo reutilices entre Account/AgentBot, Platform, Widget, MCP y Metrics. - Para pruebas, usa una credencial de mínimo privilegio y confirma si la operación es autenticada, pública o un webhook entrante condicionado. - Respeta los límites de tasa y maneja los errores 429/5xx con backoff. ### Tipos y respuestas en la integración Use el schema de cada respuesta, además del ejemplo, al generar o validar su cliente: - En la agenda, `all_day` es booleano y los valores de `reminders` son enteros en minutos. - En el perfil, `accounts[]` incluye el avance de configuración, el identificador del rol de acceso y `api_and_webhooks`. El objeto `access_role` aparece solo cuando existe un rol efectivo; los campos condicionados por permisos siguen sujetos a la autorización del servidor. - En el Cerebro, `signals` y `suggested_action` pueden conservar arrays JSON. No los fuerce a mapas; la lectura y la ocultación de datos siguen los permisos del solicitante. - Una inscripción de Follow-up puede responder 422 con `error` (motivo de rechazo) o con `message` y `attributes` (fallo de validación). Lea la variante recibida antes de elegir la siguiente acción. ## Solución de problemas - **La página no abre (404)**: la documentación puede estar deshabilitada en ese entorno — el operador la habilita con `ENABLE_API_DOCS`. - **401/403 al probar**: confirma la superficie y el esquema de seguridad; un `api_access_token` no autoriza automáticamente Platform, MCP, Metrics ni rutas públicas. - **Un endpoint no aparece**: puede estar fuera de la referencia pública, requerir una fuente curada o pertenecer a la REST separada del operador. ## Ver también - [SDK, API REST y MCP de Dashboard Apps](/hc/ajuda/articles/api-developers-dashboard-apps-sdk-rest-mcp-es) - [API REST, tokens y webhooks](/hc/ajuda/articles/api-developers-rest-tokens-webhooks-es) - [Visión general de API y Desarrolladores](/hc/ajuda/articles/api-developers-overview-es) - [Eventos por módulo](/hc/ajuda/articles/api-developers-eventos-por-modulo-es)