Visión general
Conversa Labs publica una referencia completa de la API en formato OpenAPI 3.1, generada automáticamente a partir de las rutas reales del producto. Cubre todos los módulos — conversaciones, contactos, CRM, catálogo, pagos, agenda, tareas, follow-ups, ventas y gamificación, WhatsApp y mucho más — y se mantiene sincronizada con la API en cada build.
Hay dos 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: https://app.conversalabs.com.br/swagger
- Swagger-UI (interactiva) — la misma referencia con el botón "Try it out" para hacer llamadas reales a la API directamente desde el navegador: https://app.conversalabs.com.br/swagger/ui.html
- Definición OpenAPI (JSON) — el archivo en bruto para importar en Postman, Insomnia o generar SDKs: https://app.conversalabs.com.br/swagger/swagger.json
Requisitos previos
- Un token de acceso válido (generado en tu perfil/cuenta). Consulta el artículo de API REST y tokens.
- Un navegador moderno. Para probar llamadas, prefiere un token de un entorno de pruebas.
Paso a paso
- Abre la referencia en https://app.conversalabs.com.br/swagger (ReDoc) y navega por los grupos de módulos en la barra lateral.
- Localiza el endpoint que necesitas (por método y ruta) y lee sus parámetros, cuerpo y respuestas.
- Para probar, abre la referencia interactiva en https://app.conversalabs.com.br/swagger/ui.html.
- Haz clic en Authorize e ingresa tu token en el encabezado
api_access_token. - Elige un endpoint, haz clic en Try it out, completa los parámetros y haz clic en Execute.
- Revisa la respuesta (estado, cuerpo) y reutiliza el ejemplo de solicitud (cURL) en tu integración.
Configuración y opciones
- Generación automática: la referencia se construye a partir de la introspección de las rutas reales de la aplicación, así que los nuevos endpoints aparecen automáticamente.
- Autenticación: todos los endpoints autenticados usan el encabezado
api_access_token. - Disponibilidad: en instalaciones self-hosted, la documentación la habilita el operador
mediante una variable de entorno (
ENABLE_API_DOCS). En la Conversa Labs alojada ya está disponible en las direcciones anteriores.
Casos de uso
- Descubrir rápidamente qué endpoints existen para un módulo (CRM, Pagos, Catálogo, etc.).
- Probar una llamada con tu token antes de escribirla en el código.
- Importar la definición OpenAPI en Postman/Insomnia o generar un SDK cliente.
Consejos, límites y buenas prácticas
- Trata el token como un secreto — no lo compartas ni lo expongas en el front-end.
- Para pruebas, usa un token con el menor alcance posible y, preferiblemente, de un entorno de pruebas.
- Respeta los límites de tasa y maneja los errores 429/5xx con backoff.
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: el token es inválido o no tiene permiso; genera uno nuevo y revisa el alcance.
- Un endpoint no aparece: puede requerir un módulo/recurso no habilitado en tu cuenta.