Automatizaciones

Sistema de automatizaciones

Keirost permite definir reglas de automatizacion que se ejecutan automaticamente 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 automatizacion

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 automatizacion.

Tipos de trigger

Trigger	Descripcion	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	Ejecucion programable (cron)	Diaria, semanal, mensual
plugin.hook	Hook de plugin registrado	Segun 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 accion (opcional).

Operadores disponibles

Operador	Descripcion
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.

Accion	Descripcion
email.send	Enviar email
document.lock	Bloquear documento
document.cancel	Anular documento
document.update_field	Actualizar un campo
notification.create	Crear notificacion in-app
webhook.call	Llamar a un webhook externo
report.generate	Generar y enviar informe
payment.reconcile	Conciliar automaticamente
plugin.execute	Ejecutar funcion de plugin
http.request	Hacer peticion HTTP

Ejemplo de accion 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 accion de bloqueo

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

Ejemplo de accion 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:

Expresion	Descripcion
0 9 * * *	Cada dia a las 9:00
0 8 * * 1	Cada lunes a las 8:00
0 0 1 * *	El dia 1 de cada mes
0 0 1 1 *	El 1 de enero
0 0 * * 5	Cada viernes a medianoche

Ejemplo de automatizacion 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

Metodo	Ruta	Descripcion
GET	/api/automations	Listar automatizaciones
POST	/api/automations	Crear automatizacion
GET	/api/automations/:id	Ver automatizacion
PATCH	/api/automations/:id	Actualizar automatizacion
DELETE	/api/automations/:id	Eliminar automatizacion
POST	/api/automations/:id/test	Probar automatizacion (dry run)
POST	/api/automations/:id/enable	Activar automatizacion
POST	/api/automations/:id/pause	Pausar automatizacion
GET	/api/automations/:id/logs	Ver logs de ejecucion

Crear automatizacion

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 ejecucion

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

Metodo	Ruta	Descripcion
GET	/api/automations	Listar automatizaciones
POST	/api/automations	Crear automatizacion
GET	/api/automations/:id	Ver automatizacion
PATCH	/api/automations/:id	Actualizar automatizacion
DELETE	/api/automations/:id	Eliminar automatizacion
POST	/api/automations/:id/test	Probar automatizacion
POST	/api/automations/:id/enable	Activar
POST	/api/automations/:id/pause	Pausar
GET	/api/automations/:id/logs	Ver logs de ejecucion