La especificación
La API publica su especificación OpenAPI 3.1, abierta y sin autenticación:
https://www.flujoschat.foo/api/public/v1/openapi.jsonNo se desincroniza
Postman e Insomnia
- Postman: Import → Link → pegá la URL de arriba. Te arma la colección con los doce endpoints y sus ejemplos.
- Insomnia: Create → Import From → URL.
- Después definí una variable de entorno con tu API key y usá
Authorization: Bearer {{apiKey}}a nivel de colección.
Generar un cliente
Con la spec podés generar un cliente tipado en el lenguaje que uses, sin escribir el transporte a mano:
# Ver la spec formateada en la terminal
curl -s https://www.flujoschat.foo/api/public/v1/openapi.json | jq '.paths | keys'¿Conviene generar un cliente?
Para doce endpoints con un envoltorio uniforme, un par de funciones con fetch o requests suele ser más fácil de mantener que un cliente generado. Los tipos de TypeScript, en cambio, valen la pena siempre: te avisan en tiempo de compilación si cambia una forma.
Usarla con asistentes de IA
Si estás escribiendo la integración con Claude, ChatGPT, Cursor o Copilot, dale las fuentes buenas y te va a inventar mucho menos:
https://www.flujoschat.foo/api/public/v1/openapi.json— la especificación completa (rutas, esquemas, códigos de error).https://www.flujoschat.foo/llms.txt— el índice del sitio en texto plano.https://www.flujoschat.foo/llms-full.txt— toda esta documentación en un solo archivo, pensado para pegar en el contexto de un modelo.
Dos cosas que los modelos suelen inventar
OPEN de conversación (no existe: solo IN_PROGRESS y CLOSED), y que se puede mandar texto libre en cualquier momento (fuera de la ventana de 24 h hay que usar plantilla). Si el código que te generó falla con INVALID_STATUS o WHATSAPP_24H_WINDOW_EXPIRED, es eso.Preguntas frecuentes
¿Dónde está la especificación OpenAPI de FlujosChat?
En https://www.flujoschat.foo/api/public/v1/openapi.json. Es OpenAPI 3.1, pública y sin autenticación, así que la podés importar directo en Postman, Insomnia o un generador de clientes.
¿La especificación se mantiene sincronizada con la API real?
Sí. Vive en el mismo módulo que las rutas del backend y hay un chequeo automático que compara los paths, los códigos de error y los scopes declarados contra los que Express registra de verdad: si divergen, falla.
¿Hay SDK oficial de FlujosChat para Node o Python?
Todavía no. La recomendación es generar el cliente desde el OpenAPI con la herramienta de tu ecosistema, o usar directamente fetch/requests: la API son doce endpoints REST con un envoltorio de respuesta uniforme.