API · flows

Flujos (ADR 0040): el recorrido de etapas que eligen los servicios. Lectura: owner y manager; escritura: owner (API key con settings:write).

GET /base-states

Estados base del motor

flows:read: owner/manager por sesión, o API key config:read. Catálogo de estados base del motor.

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:read, config:read

Respuestas

GET /flow-examples

Ejemplos de flujo para copiar

flows:read: owner/manager por sesión, o API key config:read. El flujo de sistema y los de cada blueprint, con la forma del cuerpo de POST /flows (key más format, stages y exits). Reemplaza a /stage-templates.

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:read, config:read

Respuestas

GET /flow-message-catalog

Variables y textos por defecto del mensaje al cliente de una etapa

flows:read: owner/manager por sesión, o API key config:read. Ayuda para editar el mensaje al cliente de una etapa (on_enter.notify_customer.texts, F3-534): las variables protegidas con datos de ejemplo ya formateados (zona horaria, moneda e idioma) y el texto por defecto de cada plantilla en pt, es y en. Las variables son las únicas que el servidor acepta al publicar el flujo (PATCH /flows/{id}, flows:write): otra variable, llaves sueltas o formatos devuelven 422 message_variable_unknown | message_braces_invalid | message_text_empty | message_text_too_long | message_variable_not_available (cola, sin horario), con la etapa y el campo. Fecha/hora, monto y link de seguimiento los arma el core; el texto guardado es el que sale (nunca generado). Sin texto en el idioma del cliente, o con una variable sin valor, sale la plantilla.

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:read, config:read, flows:write

Respuestas

GET /flows

Listar flujos

flows:read: owner/manager por sesión, o API key config:read. Los de sistema primero; include_inactive=true agrega los desactivados. Sin purpose no incluye la raíz «Atención del bot» (no es un recorrido, F3-467): purpose=entry la trae (una por proyecto, sin etapas, con greeting y order en GET /flows/{id}).

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:read, config:read

Parámetros

Respuestas

POST /flows

Crear un flujo

flows:write: owner por sesión con CSRF, o API key settings:write (mismos roles que tenía service_stages:write). Flujo propio con su versión 1 (note opcional). purpose=entry: 422 entry_flow_unique (la raíz «Atención del bot» es una por proyecto y la crea el proyecto, F3-467; también al copiarla). purpose=intent exige mode=queue (422 flow_mode_mismatch): sus tareas no tienen servicio ni horario (F3-457). Flujo v2 con ítems y botones. confirm_moves=true es obligatorio si hay tareas que mover: 409 stage_moves_unconfirmed. Identidad estable contra todo el historial: 422 stage_key_reinterpreted; v1 no se restaura: 422 version_format_unsupported. 422 bot_offer_unknown_item si bot_offers nombra un ítem inexistente o de otro tipo. Campos v3/v4: 422 field_reserved, item_type_not_available (payment, products y offer con kind plan; offer y timer sin su configuración: invalid_offer, invalid_timer), effect_not_available, variable_not_available (, , ), con ruta del campo. 422 flow_mode_mismatch si un servicio del flujo es de otro modo, item_key_reserved si un ítem repite un campo del formulario de un servicio. Un flujo de sistema (system_key) no se publica: 422 flow_system_readonly al editarlo; se edita su copia propia (POST /flows/{id}/customize, F3-731) o se crea uno propio con POST /flows y se asigna con flow_id en POST|PATCH /services. Publicar mueve tareas y escribe auditoría (flow.updated) en su transacción (outbox, F3-184).

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:write, settings:write

Cuerpo de la solicitud (obligatorio)

• application/json: FlowInput

Respuestas

GET /flows/{id}

Leer un flujo con su versión vigente

flows:read: owner/manager por sesión, o API key config:read. Incluye los servicios que lo usan. Un flujo lo comparten varios servicios (ADR 0040): publicar una versión mueve las tareas abiertas de todos (impact.by_service) y impact.shared_with lista los servicios que cambian; el cliente (panel, MCP) pide confirmar.

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:read, config:read

Parámetros

Respuestas

PATCH /flows/{id}

Renombrar, activar o publicar un flujo

task_view (FIU-584) cambia «Cómo se ve la tarea» sin versión nueva ni mover tareas, también en un flujo de sistema. flows:write: owner por sesión con CSRF, o API key settings:write (mismos roles que tenía service_stages:write). Un flujo lo comparten varios servicios (ADR 0040): publicar una versión mueve las tareas abiertas de todos (impact.by_service) y impact.shared_with lista los servicios que cambian; el cliente (panel, MCP) pide confirmar. Con format, exits y stages publica una versión nueva (base_version evita pisar; 409 stale_version). Desactivar no cancela tareas ni cambia las de los servicios que ya lo usan: solo impide asignarlo. Flujo v2 con ítems y botones. confirm_moves=true es obligatorio si hay tareas que mover: 409 stage_moves_unconfirmed. Si hay varios servicios, shared_with_ack incluye todos los IDs revisados de impact.shared_with (incluido el editado); si falta alguno, 409 stage_shared_unconfirmed con impact actualizado exige validar y confirmar otra vez. Identidad estable contra todo el historial: 422 stage_key_reinterpreted; v1 no se restaura: 422 version_format_unsupported. 422 bot_offer_unknown_item si bot_offers nombra un ítem inexistente o de otro tipo. Campos v3/v4: 422 field_reserved, item_type_not_available (payment, products y offer con kind plan; offer y timer sin su configuración: invalid_offer, invalid_timer), effect_not_available, variable_not_available (, , ), con ruta del campo. 422 flow_mode_mismatch si un servicio del flujo es de otro modo, item_key_reserved si un ítem repite un campo del formulario de un servicio. Un flujo de sistema (system_key) no se publica: 422 flow_system_readonly al editarlo; se edita su copia propia (POST /flows/{id}/customize, F3-731) o se crea uno propio con POST /flows y se asigna con flow_id en POST|PATCH /services. Publicar mueve tareas y escribe auditoría (flow.updated) en su transacción (outbox, F3-184). Raíz «Atención del bot» (purpose=entry, ADR 0040 §4.4, F3-467): solo cambian greeting y order (versión nueva y auditoría flow.entry_root_changed); 422 entry_branch_unknown (con key) si una clave de order no es services, products, subscriptions, faq, mine, handoff ni flow: de un flujo por intención activo con entry y la etapa en la que nace su tarea (pausado o no: una rama propia pausada conserva su lugar, F3-467b); 422 entry_branch_duplicate si se repite; 422 invalid_entry_greeting si el saludo no es pt/es/en de hasta 300; active=false → 422 entry_flow_required (no se desactiva ni se borra); name, entry, etapas o restaurar una versión → 422 entry_flow_readonly. greeting u order en otro flujo → 422 root_fields_only_for_entry. La raíz se edita con bot:configure (owner, manager o colaborador) por sesión con CSRF o con una API key config:write (el mismo permiso que «Qué vende el bot», F3-467b); settings:write no alcanza para la raíz.

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:write, settings:write, config:write

Parámetros

Cuerpo de la solicitud (obligatorio)

• application/json: FlowPatchInput

Respuestas

DELETE /flows/{id}

Borrar un flujo sin uso

flows:write: owner por sesión con CSRF, o API key settings:write. F3-731: borra un flujo propio que ningún servicio usa y que nunca tuvo tareas (has_tasks falso), con sus versiones. 409 flow_in_use si un servicio lo usa (elegile otro antes); 409 flow_has_tasks si tiene tareas, abiertas o cerradas (desactivalo en su lugar); 422 flow_system_readonly para un flujo de sistema; 422 entry_flow_required para «Atención del bot». 404 si no existe en el proyecto. Escribe auditoría (flow.deleted).

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:write, settings:write

Parámetros

Respuestas

POST /flows/{id}/copy

Copiar un flujo

flows:write: owner por sesión con CSRF, o API key settings:write. Crea un flujo propio e independiente con la versión vigente del origen como su versión 1 (note opcional): ningún servicio pasa a usarlo y cambiar uno no cambia el otro. El origen puede ser de sistema, propio o desactivado; la copia conserva modo y propósito, queda activa y sin system_key. Se asigna a un servicio con flow_id en POST|PATCH /services. 404 si el flujo no existe en el proyecto; 422 con un nombre inválido. Escribe auditoría (flow.copied).

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:write, settings:write

Parámetros

Cuerpo de la solicitud (obligatorio)

• application/json: FlowCopyInput

Respuestas

POST /flows/{id}/customize

Editar un flujo de sistema en la copia propia del negocio

flows:write: owner por sesión con CSRF, o API key settings:write. F3-731: el negocio edita su copia de un flujo de sistema (turno_simple, pedido_simple, alta_simple, cuota_simple). La primera vez la crea con la versión vigente de la base (copy_of dice de cuál, mismo nombre que se ve) y le pasa todos los servicios que usaban la base; los servicios nuevos de ese modo nacen en la copia. Las tareas abiertas siguen en el suyo. Si ya existe, la devuelve sin cambios (idempotente). Después se publica con PATCH /flows/{copia}. 422 flow_not_system si el flujo no es de sistema; 404 si no existe en el proyecto. Escribe auditoría (flow.customized).

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:write, settings:write

Parámetros

Respuestas

POST /flows/{id}/restore

Volver al flujo de sistema original

flows:write: owner por sesión con CSRF, o API key settings:write. F3-731: «Volver al original» desde la copia propia (copy_of): sus servicios vuelven al flujo de sistema y los nuevos nacen ahí. Las tareas abiertas no se mueven: terminan con la versión del flujo que tenían. La copia nunca se borra (decisión B): queda como flujo propio «… (anterior)», sin copy_of ni servicios («Sin uso»), y se borra a mano con DELETE /flows/{id} si no tiene tareas. Devuelve el flujo de sistema. 422 flow_not_copy si el flujo no es una copia propia; 404 si no existe en el proyecto. Escribe auditoría (flow.restored).

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:write, settings:write

Parámetros

Respuestas

POST /flows/{id}/simulate

Probar dónde cae cada frase de entrada sin escribir

flows:write: owner por sesión con CSRF, o API key settings:write. Simulacro de entrada (ADR 0040 §6, F3-460) de un flujo por intención: corre los examples y not_when de entry (el del cuerpo, sin guardarlo, o el guardado) y todos los ejemplos de cada otro flujo por intención que el bot ofrece por el mismo elegidor del bot de clientes: palabras clave sin IA y, si no deciden, una elección barata con lista cerrada por frase, con la IA del proyecto (cuenta en su uso de IA). results dice dónde cae cada frase (landed: flow, service, action, reply o ask con options) y ok=false si choca: un ejemplo que no cae en este flujo (fix add_example_or_keyword) o una frase que no es de este flujo y cae en él o en una pregunta que lo incluye (fix add_not_when). catalog_clash: una palabra clave choca con el catálogo (al guardar, 422 flow_entry_keyword_catalog). No simula el catálogo por reglas (un mensaje que nombra un servicio lo toma su plantilla antes). 422 entry_only_for_intent si el flujo no es por intención; 422 flow_entry_missing sin entry dada ni guardada. No guarda nada ni crea tareas.

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:write, settings:write

Parámetros

Cuerpo de la solicitud (obligatorio)

• application/json: FlowSimulateInput

Respuestas

GET /flows/{id}/usage

Uso de un flujo por día y dónde se traban sus tareas

days: tareas que entraron (día local de su alta) y que se completaron, por día. stages: tareas abiertas por etapa y su espera desde que entraron a ella; bottleneck, la de más espera promedio. El colaborador ve solo lo suyo (scope: own, F3-729). Tenant desde la credencial, RLS. Panel: permiso flows:usage (owner, manager y colaborador); el colaborador lo tiene solo sobre lo suyo (scope: own: tareas asignadas a los recursos enlazados a su usuario; sin recurso propio, cero), nunca los totales del negocio (scope: business). API key: scope bookings:read. Entran las tareas por el día local de su alta, sin las de prueba ni los holds que no se concretaron (held, expired). Solo lectura: no guarda nada nuevo.

• Autenticación: Clave de API o sesión del panel
• Scopes: bookings:read

Parámetros

Respuestas

POST /flows/{id}/validate

Validar un flujo sin escribir

flows:write: owner por sesión con CSRF, o API key settings:write (mismos roles que tenía service_stages:write). Un flujo lo comparten varios servicios (ADR 0040): publicar una versión mueve las tareas abiertas de todos (impact.by_service) y impact.shared_with lista los servicios que cambian; el cliente (panel, MCP) pide confirmar. Devuelve impact: tareas que se moverían (count, moves, by_service) y shared_with. En un flujo de sistema valida solo el formato. Flujo v2 con ítems y botones. confirm_moves=true es obligatorio si hay tareas que mover: 409 stage_moves_unconfirmed. Identidad estable contra todo el historial: 422 stage_key_reinterpreted; v1 no se restaura: 422 version_format_unsupported. 422 bot_offer_unknown_item si bot_offers nombra un ítem inexistente o de otro tipo. Campos v3/v4: 422 field_reserved, item_type_not_available (payment, products y offer con kind plan; offer sin su configuración: invalid_offer), effect_not_available, variable_not_available (, , ), con ruta del campo. 422 flow_mode_mismatch si un servicio del flujo es de otro modo, item_key_reserved si un ítem repite un campo del formulario de un servicio. Un flujo de sistema (system_key) es de solo lectura: 422 flow_system_readonly al editarlo; se crea uno propio con POST /flows y se asigna con flow_id en POST|PATCH /services. Publicar mueve tareas y escribe auditoría (flow.updated) en su transacción (outbox, F3-184).

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:write, settings:write

Parámetros

Cuerpo de la solicitud (obligatorio)

• application/json: FlowValidateInput

Respuestas

GET /flows/{id}/versions

Historial de versiones del flujo

flows:read: owner/manager por sesión, o API key config:read. Paginado hacia atrás con before; next_before es el cursor.

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:read, config:read

Parámetros

Respuestas

GET /flows/{id}/versions/{version}

Leer una versión del flujo

flows:read: owner/manager por sesión, o API key config:read. Versión inmutable del flujo.

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:read, config:read

Parámetros

Respuestas

POST /flows/{id}/versions/{version}/revert

Restaurar una versión del flujo creando otra

flows:write: owner por sesión con CSRF, o API key settings:write (mismos roles que tenía service_stages:write). Un flujo lo comparten varios servicios (ADR 0040): publicar una versión mueve las tareas abiertas de todos (impact.by_service) y impact.shared_with lista los servicios que cambian; el cliente (panel, MCP) pide confirmar. Crea una versión nueva con el contenido de la elegida (reverted_from); mismas confirmaciones que publicar. Flujo v2 con ítems y botones. confirm_moves=true es obligatorio si hay tareas que mover: 409 stage_moves_unconfirmed. Si hay varios servicios, shared_with_ack incluye todos los IDs revisados de impact.shared_with (incluido el editado); si falta alguno, 409 stage_shared_unconfirmed con impact actualizado exige validar y confirmar otra vez. Identidad estable contra todo el historial: 422 stage_key_reinterpreted; v1 no se restaura: 422 version_format_unsupported. 422 bot_offer_unknown_item si bot_offers nombra un ítem inexistente o de otro tipo. Campos v3/v4: 422 field_reserved, item_type_not_available (payment, products y offer con kind plan; offer y timer sin su configuración: invalid_offer, invalid_timer), effect_not_available, variable_not_available (, , ), con ruta del campo. 422 flow_mode_mismatch si un servicio del flujo es de otro modo, item_key_reserved si un ítem repite un campo del formulario de un servicio. Un flujo de sistema (system_key) no se publica: 422 flow_system_readonly al editarlo; se edita su copia propia (POST /flows/{id}/customize, F3-731) o se crea uno propio con POST /flows y se asigna con flow_id en POST|PATCH /services. Publicar mueve tareas y escribe auditoría (flow.updated) en su transacción (outbox, F3-184).

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:write, settings:write

Parámetros

Cuerpo de la solicitud (opcional)

• application/json: FlowRevertInput

Respuestas

GET /flows/usage

Uso de los flujos en los últimos 7 días

Por flujo: tareas que entraron cada uno de los últimos 7 días (hoy al final), su total y el de los 7 anteriores, y si se usó alguna vez (used). Día local del proyecto; sin tareas de prueba (F3-729). Tenant desde la credencial, RLS. Panel: permiso flows:usage (owner, manager y colaborador); el colaborador lo tiene solo sobre lo suyo (scope: own: tareas asignadas a los recursos enlazados a su usuario; sin recurso propio, cero), nunca los totales del negocio (scope: business). API key: scope bookings:read. Entran las tareas por el día local de su alta, sin las de prueba ni los holds que no se concretaron (held, expired). Solo lectura: no guarda nada nuevo.

• Autenticación: Clave de API o sesión del panel
• Scopes: bookings:read

Respuestas