Automatizaciones

El motor de reglas convierte un evento en trabajo, y ya vive sobre el contrato v1. Una regla escucha un tipo de evento, una condición decide si ese evento concreto es su caso, y se ejecuta una lista ordenada de acciones — dieciocho operaciones sobre quince rutas bajo /v1/automations, todas tras el módulo nuevo automations. Empieza por la guía de automatizaciones.

• Pregunta al catálogo, no lo adivines — GET /v1/automations/catalog devuelve los disparadores a los que tu empresa puede suscribirse (ya filtrados por los módulos que incluye tu plan), el conjunto cerrado de operadores y combinadores de condición, y las acciones con adaptador registrado. Los campos evaluables de un disparador son una segunda llamada deliberada, GET /v1/automations/catalog/triggers/{trigger}/fields, para que el catálogo siga siendo lo bastante pequeño como para cachearlo y compararlo.
• Cada edición sella una versión — editar una regla nunca reescribe su definición anterior: sella una versión nueva y sube current_version, y cada ejecución guarda un puntero a la versión exacta que ejecutó. Una regla nace en draft y no escucha nada hasta que la activas.
• Un ensayo que no materializa nada — POST /v1/automations/rules/{rule}/dry_run responde qué haría una regla ante un evento de ejemplo: no sale ningún correo, no se entrega ningún webhook, no se muta ninguna entidad, no se escribe ninguna fila de ejecución, y no consume ni el presupuesto mensual ni el límite de frecuencia del motor. Una condición que no se puede evaluar vuelve como condition_error con un 200, porque ver por qué una regla no se puede evaluar es justo la gracia.
• Historial de ejecuciones, pasos y relanzamiento — cada evento admitido produce una ejecución y cada acción un paso, ambos con la definición congelada y el payload del disparador. discard_reason es un valor tipado de un catálogo cerrado, así que puedes ramificar sobre él en vez de parsear texto. El trabajo aparcado se rearma con POST /v1/automations/runs/{run}/replay o con su hermano por paso; el relanzamiento ejecuta de verdad y está marcado como x-irreversible en el spec.
• Cuatro guardarraíles, y bloqueada no es fallida — profundidad de cadena (tres saltos «acción → evento → regla» por defecto), un límite de frecuencia por minuto, el presupuesto mensual del plan (GET /v1/automations/usage) y una pausa automática tras una racha de ejecuciones fallidas. Una ejecución detenida por cualquiera de ellos se registra como blocked con su razón tipada. Consulta Códigos de error de Automatizaciones — 47 códigos nuevos bajo el grupo Automations, cada uno con su causa y qué hacer.
• Cuatro scopes finos — automations:read, automations:write, automations:delete y automation_runs:read. Leer y escribir reglas y leer el historial de ejecuciones se conceden en la pantalla de consentimiento OAuth; borrar una regla no, y se queda solo para API key. Leer el reglamento y leer lo que las reglas hicieron de verdad van por separado a propósito. Consulta Scopes y permisos.
• Siete eventos de ciclo de vida, y son disparadores ellos mismos — automation_rule.activated, .paused, .auto_paused, automation_run.started, .completed, .failed y .step_dead_lettered. Viven en el mismo catálogo cerrado que los demás eventos, así que una automatización puede reaccionar a automation_run.failed igual que reacciona a invoice.paid; encadenarlos está acotado por el tope de profundidad, no prohibido. Consulta Eventos.
• Reglas de cartera para gestorías — una regla declara qué empresas vigila en su campo scope: empresa (el valor por defecto) vigila su propia empresa, y cartera vigila todas las empresas gestionadas por una gestoría y le entrega el aviso a ella. El alcance es inmutable, y en cartera solo se admiten los cuatro tipos de acción que avisan — los otros cuatro tendrían por sujeto un documento de la empresa gestionada.
• Paridad con MCP y CLI — la misma superficie como 18 tools MCP (catálogo) y como el grupo de comandos factuarea automations (CLI).