Automatizaciones

Sistema de automatizaciones

Keirost permite definir reglas de automatización que se ejecutan automáticamente cuando se cumplen ciertas condiciones. Por ejemplo: enviar un email cuando se crea una factura, bloquear un documento a cierta hora, o generar un informe cada mes.

---

Modelo de automatización

interface Automation {
  id: string;
  name: string;
  description?: string;
  trigger: AutomationTrigger;
  conditions: AutomationCondition[];
  actions: AutomationAction[];
  status: 'active' | 'paused' | 'disabled';
  execution_count: number;
  last_executed_at?: string;
  created_by: string;
  created_at: string;
}

---

Triggers

Los triggers definen cuando se ejecuta la automatización.

Tipos de trigger

Trigger	Descripción	Eventos disponibles
document.created	Al crear un documento	Facturas, pedidos, albaranes
document.updated	Al actualizar un documento	Cambio de estado, importe, partner
document.status_changed	Cambio de estado	pending → sent, sent → locked
document.sent	Al enviar documento por email
document.paid	Al registrar pago de un documento
payment.received	Al registrar un cobro
schedule.cron	Ejecución programable (cron)	Diaria, semanal, mensual
plugin.hook	Hook de plugin registrado	Según plugin
system.startup	Al iniciar el servidor

Ejemplo de trigger

{
  "type": "document.status_changed",
  "document_type": "sales_invoice",
  "from_status": "draft",
  "to_status": "sent"
}

---

Condiciones

Las condiciones filtran cuando se ejecuta la acción (opcional).

Operadores disponibles

Operador	Descripción
equals	Campo igual a valor
not_equals	Campo diferente
contains	Campo contiene texto
greater_than	Campo mayor que valor
less_than	Campo menor que valor
is_empty	Campo vacio
in	Campo dentro de lista de valores

Ejemplo de condiciones

[
  {
    "field": "partner.tax_id",
    "operator": "is_empty",
    "value": null
  },
  {
    "field": "total",
    "operator": "greater_than",
    "value": 10000
  }
]

---

Acciones

Las acciones son lo que ocurre cuando se cumplen el trigger y las condiciones.

Acción	Descripción
email.send	Enviar email
document.lock	Bloquear documento
document.cancel	Anular documento
document.update_field	Actualizar un campo
notification.create	Crear notificación in-app
webhook.call	Llamar a un webhook externo
report.generate	Generar y enviar informe
payment.reconcile	Conciliar automáticamente
plugin.execute	Ejecutar función de plugin
http.request	Hacer petición HTTP

Ejemplo de acción email

{
  "type": "email.send",
  "to": "{{document.partner.email}}",
  "subject": "Su factura {{document.number}} ha sido enviada",
  "body_html": "<p>Estimado {{document.partner.name}}, adjuntamos su factura.</p>",
  "attach_pdf": true
}

Ejemplo de acción de bloqueo

{
  "type": "document.lock",
  "document_type": "sales_invoice",
  "when": "end_of_day"
}

Ejemplo de acción de webhook

{
  "type": "webhook.call",
  "url": "https://tu-sistema.com/webhook/keirost",
  "method": "POST",
  "headers": { "Authorization": "Bearer {{api_key}}" },
  "body": "{{json_document}}"
}

---

Expresiones cron

Para ejecuciones programables, se usa sintaxis cron:

Expresión	Descripción
0 9 * * *	Cada día a las 9:00
0 8 * * 1	Cada lunes a las 8:00
0 0 1 * *	El día 1 de cada mes
0 0 1 1 *	El 1 de enero
0 0 * * 5	Cada viernes a medianoche

Ejemplo de automatización con cron

{
  "name": "Recordatorio facturas pendientes",
  "trigger": {
    "type": "schedule.cron",
    "expression": "0 9 * * 1-5"
  },
  "conditions": [
    { "field": "document.status", "operator": "equals", "value": "pending" },
    { "field": "days_overdue", "operator": "greater_than", "value": 7 }
  ],
  "actions": [
    {
      "type": "notification.create",
      "user_id": "{{document.owner_id}}",
      "title": "Factura vencida",
      "body": "La factura {{document.number}} lleva 7 dias pendiente."
    }
  ]
}

---

API de automatizaciones

Método	Ruta	Descripción
GET	/api/automations	Listar automatizaciones
POST	/api/automations	Crear automatización
GET	/api/automations/:id	Ver automatización
PATCH	/api/automations/:id	Actualizar automatización
DELETE	/api/automations/:id	Eliminar automatización
POST	/api/automations/:id/test	Probar automatización (dry run)
POST	/api/automations/:id/enable	Activar automatización
POST	/api/automations/:id/pause	Pausar automatización
GET	/api/automations/:id/logs	Ver logs de ejecución

Crear automatización

POST /api/automations
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Enviar email al crear factura enviada",
  "description": "Notifica al director comercial al enviar una factura a un cliente nuevo",
  "trigger": {
    "type": "document.status_changed",
    "document_type": "sales_invoice",
    "from_status": "draft",
    "to_status": "sent"
  },
  "conditions": [
    {
      "field": "partner.is_new",
      "operator": "equals",
      "value": true
    }
  ],
  "actions": [
    {
      "type": "email.send",
      "to": "director@empresa.com",
      "subject": "Nueva factura enviada a cliente nuevo",
      "body_html": "Se ha enviado la factura {{document.number}} a {{document.partner.name}}."
    },
    {
      "type": "notification.create",
      "user_id": "user_comercial",
      "title": "Factura enviada",
      "body": "Nueva factura {{document.number}} a {{document.partner.name}}."
    }
  ]
}

Logs de ejecución

GET /api/automations/:id/logs

{
  "data": [
    {
      "executed_at": "2026-05-08T09:00:00Z",
      "trigger": "document.status_changed",
      "document_id": "inv_2026_0012",
      "actions_executed": ["email.send", "notification.create"],
      "status": "success",
      "duration_ms": 250
    }
  ]
}

---

Resumen de endpoints

Método	Ruta	Descripción
GET	/api/automations	Listar automatizaciones
POST	/api/automations	Crear automatización
GET	/api/automations/:id	Ver automatización
PATCH	/api/automations/:id	Actualizar automatización
DELETE	/api/automations/:id	Eliminar automatización
POST	/api/automations/:id/test	Probar automatización
POST	/api/automations/:id/enable	Activar
POST	/api/automations/:id/pause	Pausar
GET	/api/automations/:id/logs	Ver logs de ejecución