1. Preparación

En este tutorial vas a construir un plugin completo y realista de principio a fin: fidelizacion, un sistema de puntos de fidelidad para clientes.

Qué vamos a construir

Al terminar las 6 partes, el plugin:

• Añade el campo Puntos de fidelidad a los clientes y Puntos canjeados a las facturas de venta
• Crea su propia tabla fidelizacion_movimientos para el historial de puntos
• Acumula puntos automáticamente al asentar facturas (1 punto por cada 10 €)
• Valida los canjes antes de crear la factura (no puedes canjear más puntos de los que tienes)
• Marca como VIP a los clientes con más de 100 puntos en el listado de socios
• Expone sus propios endpoints HTTP y una página propia en el ERP con módulo en el sidebar
• Inyecta un widget en el dashboard y una tool de IA en el chat

El recorrido: 1. Preparación → 2. Campos y tablas → 3. Hooks de negocio → 4. Interfaz de usuario → 5. Widget y AI tool → 6. Publicar.

Requisitos

• Node.js 18+ y npm
• Acceso a un servidor Keirost (remoto o local) donde probar el plugin
• El CLI: npm i -g @openfactu/cli

Crear el proyecto

1. Ve al template oficial y pulsa “Use this template” para crear tu repositorio.

2. Clona tu repo y entra en la carpeta:

   git clone https://github.com/tu-usuario/fidelizacion.git
   cd fidelizacion
   npm install

3. Revisa la estructura:

   • Directoriofidelizacion/

     • index.ts el punto de entrada — exporta init()
     • manifest.json metadatos y UI del plugin
     • Directorioui/

       • Page.tsx componentes React (opcional)
     • package.json con @openfactu/plugin-sdk como devDependency

El SDK (@openfactu/plugin-sdk) es type-only: solo aporta los tipos TypeScript. La implementación real la inyecta el servidor Keirost al cargar tu plugin.

El punto de entrada init()

Sustituye el contenido de index.ts por la versión mínima:

index.ts

import type { PluginContext } from '@openfactu/plugin-sdk';

const PLUGIN_ID = 'fidelizacion';

export const init = async (context: PluginContext) => {
  console.log(`[${PLUGIN_ID}] Plugin inicializado`);
};

El servidor ejecuta init() al cargar el plugin (y en cada hot reload). El objeto context trae todo lo que un plugin puede usar: migraciones, hooks, base de datos, FactuAPI, widgets y AI tools — lo iremos usando pieza a pieza. La referencia completa está en PluginContext.

Conectar con tu servidor

Servidor remoto (recomendado)

No necesitas tener Keirost instalado en tu máquina. Genera una API key de desarrollo desde la UI del ERP (Plugins → Desarrollo → Generar API Key) y lanza el watcher:

openfactu plugin watch \
  --server http://mi-servidor:3000 \
  --client-id ofk_... \
  --client-secret ofs_...

Cada vez que guardes un archivo, el plugin se sube y recarga automáticamente. Detalles en Desarrollo remoto.

Instalación local

Si tienes Keirost instalado en tu máquina:

# Enlazar tu plugin (symlink)
openfactu plugin link ~/fidelizacion

# Arrancar con hot reload
openfactu plugin dev fidelizacion

Activar el plugin en tu empresa

Los plugins se activan por empresa (tenant). En la UI del ERP: menú lateral → Plugins → activa el toggle de fidelizacion. Más detalle en Activación por empresa.

Checkpoint

Si todo va bien, en los logs del servidor deberías ver:

[fidelizacion] Plugin inicializado

Parte 2: Campos y tablasAñadir campos a tablas del ERP y crear la tabla de movimientos del plugin.