La API usa API keys de empresa. No hay OAuth ni login: la key es la identidad, y todo lo que devuelve la API queda acotado a la empresa dueña de esa key.
Cómo se envía la key
En el header Authorization, con el esquema Bearer:
curl https://www.flujoschat.foo/api/public/v1/conversations \
-H "Authorization: Bearer fjc_live_xxxxxxxxxxxx"También se acepta X-API-Key con el mismo valor, para herramientas que no permiten editar el header Authorization.
Crear una key
Entrá a Configuración → API Keys
Solo el propietario y los administradores ven esa pantalla: un agente no debería poder crear credenciales de acceso programático.
Elegí los permisos mínimos
Los permisos que escriben o generan costo no vienen premarcados. Si tu tienda solo manda avisos, dale messages:send y nada más.
Guardá la key: se muestra una sola vez
En nuestra base solo queda su hash, así que no podemos recuperarla. Si la perdés, creá otra y revocá la anterior.
Permisos (scopes)
Cada endpoint exige un scope. Si la key no lo tiene, la respuesta es 403 INSUFFICIENT_SCOPE y no consume tu cuota mensual.
Scopes disponibles
| Campo | Tipo | Descripción |
|---|---|---|
conversations:read | lectura | Listar conversaciones y leer sus historiales de mensajes. |
conversations:write | escritura | Cerrar o reabrir una conversación, pausar el bot, corregir el nombre. |
messages:send | escritura | Enviar mensajes de texto (dentro de la ventana de 24 h de Meta). |
templates:read | lectura | Listar tus plantillas y su mapa de variables. |
templates:send | escritura · costo | Enviar plantillas aprobadas. Va aparte porque cada envío tiene costo y puede iniciar una conversación. |
custom_fields:read | lectura | Leer el catálogo de campos y los valores de cada cliente. |
custom_fields:write | escritura | Escribir valores de campos personalizados. |
usage:read | lectura | Consultar el consumo del mes contra la cuota del plan. |
Los scopes nuevos no son retroactivos
templates:send) creá una key nueva con ese scope marcado.Rotar y revocar
Rotación sin cortar el servicio
- Creá la key nueva con los mismos permisos.
- Desplegá tu sistema con la key nueva.
- Comprobá que el tráfico usa la nueva (columna «último uso» en el panel).
- Revocá la vieja.
Buenas prácticas
- Una key por sistema (ERP, tienda, Zapier): así revocás una sin romper las otras y sabés cuál se filtró.
- En variables de entorno, nunca en el repositorio.
- Solo servidor a servidor. Para el navegador o la app móvil, usá tu propio backend como intermediario.
Para entender qué responde la API cuando algo falla, seguí en errores, cuotas e idempotencia.
Preguntas frecuentes
¿Cómo se autentica la API de FlujosChat?
Con una API key de empresa enviada en el header Authorization como Bearer token: Authorization: Bearer fjc_live_... También se acepta el header X-API-Key. No hay OAuth ni usuario y contraseña para la API pública.
¿Puedo cambiar los permisos de una API key ya creada?
No. Los scopes se fijan al crear la key y no se editan, justamente para que nadie amplíe permisos sin dejar rastro. Si necesitás otros permisos, creá una key nueva con los scopes correctos y revocá la anterior.
¿Qué pasa si se filtra mi API key?
Revocala desde el panel (Configuración → API Keys): deja de funcionar al instante y las llamadas con esa key responden 401 INVALID_API_KEY. Por eso conviene una key por sistema: revocás la comprometida sin romper las demás integraciones.