> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuración en tiempo de ejecución (Systemplane)

> Visualiza y modifica la configuración operativa de Matcher en tiempo de ejecución a través de Systemplane, sin reiniciar el servicio.

Systemplane te permite ver y modificar la configuración de Matcher en tiempo de ejecución — sin reiniciar el servicio. En entornos financieros regulados, los tiempos de inactividad no planificados para aplicar cambios de configuración representan un riesgo de cumplimiento y una interrupción operacional. Systemplane elimina ese riesgo: los parámetros operacionales se pueden ajustar mientras el servicio continúa ejecutándose, manteniendo los procesos de conciliación sin interrupciones.

## Por qué usar Systemplane

***

En un despliegue tradicional, cambiar un valor de configuración significa actualizar variables de entorno y reiniciar el servicio. Systemplane elimina ese tiempo de inactividad para muchas configuraciones:

* **Ajustar límites de tasa** durante picos de tráfico sin redeploy — evitando interrupciones del servicio en momentos de alto volumen de transacciones
* **Ajustar intervalos de workers** según la carga de trabajo observada — optimizando el rendimiento de conciliación sin modificar la infraestructura
* **Actualizar tamaños de connection pool** a medida que cambian los patrones de tráfico
* **Inspeccionar valores actuales en tiempo de ejecución** para diagnosticar problemas en producción sin bucear en logs

## Cómo funciona

***

Systemplane proporciona una API de gestión de clave-valor plana. Todas las claves de configuración están en un único namespace bajo `/system/matcher`.

### Endpoints

| Endpoint               | Método | Qué hace                                        |
| ---------------------- | ------ | ----------------------------------------------- |
| `/system/matcher`      | `GET`  | Listar todas las claves y sus valores actuales  |
| `/system/matcher/:key` | `GET`  | Obtener el valor actual de una clave específica |
| `/system/matcher/:key` | `PUT`  | Actualizar el valor de una clave específica     |

<Note>
  Estos endpoints son servidos directamente por la instancia de Matcher en ejecución. No están versionados bajo `/v1` — usa las rutas anteriores exactamente como se muestran.
</Note>

## Permisos

***

Los endpoints de Systemplane están protegidos por la misma autenticación utilizada por todas las rutas de la API de Matcher. Cuando la autenticación está habilitada, todos los endpoints `/system` requieren el permiso RBAC `system-runtime-config:admin` (recurso `system-runtime-config`, acción `admin`).

Cuando la autenticación está deshabilitada, todos los endpoints son accesibles sin restricciones.

## Comportamientos de aplicación

***

No todos los valores de configuración pueden cambiarse en tiempo de ejecución. Cada clave tiene un **comportamiento de aplicación** que indica cuándo surten efecto los cambios:

| Comportamiento               | Qué sucede                                                                                         |
| ---------------------------- | -------------------------------------------------------------------------------------------------- |
| **Solo bootstrap**           | El valor se lee una vez al inicio. Debes reiniciar el servicio para que los cambios surtan efecto. |
| **Lectura en vivo**          | Los cambios surten efecto inmediatamente en la próxima solicitud.                                  |
| **Reconstrucción de bundle** | Los cambios desencadenan una actualización de estado interno. Surte efecto en segundos.            |
| **Reconciliación de worker** | Los workers en segundo plano recogen el nuevo valor en su próximo ciclo.                           |

Las claves que son solo bootstrap NO están registradas en la API de systemplane — se gestionan exclusivamente a través de variables de entorno. Esto evita que un PUT de administrador parezca exitoso mientras el proceso en ejecución continúa silenciosamente usando el valor del momento de arranque.

## Claves de configuración comunes

***

A continuación se muestran las claves más comúnmente ajustadas, organizadas por categoría. Para una lista completa, llama a `GET /system/matcher`.

### Claves ajustables en tiempo de ejecución

Estas claves pueden cambiarse sin reiniciar Matcher:

| Clave                             | Variable de entorno               | Descripción                                                                |
| --------------------------------- | --------------------------------- | -------------------------------------------------------------------------- |
| `server.body_limit_bytes`         | `HTTP_BODY_LIMIT_BYTES`           | Tamaño máximo del cuerpo de solicitud HTTP                                 |
| `cors.allowed_origins`            | `CORS_ALLOWED_ORIGINS`            | Orígenes CORS permitidos                                                   |
| `cors.allowed_methods`            | `CORS_ALLOWED_METHODS`            | Métodos CORS permitidos                                                    |
| `cors.allowed_headers`            | `CORS_ALLOWED_HEADERS`            | Cabeceras CORS permitidas                                                  |
| `swagger.enabled`                 | `SWAGGER_ENABLED`                 | Habilitar o deshabilitar Swagger UI                                        |
| `swagger.host`                    | `SWAGGER_HOST`                    | Override del host de Swagger                                               |
| `swagger.schemes`                 | `SWAGGER_SCHEMES`                 | Esquemas de URL de Swagger                                                 |
| `rate_limit.enabled`              | `RATE_LIMIT_ENABLED`              | Habilitar o deshabilitar el límite de tasa global                          |
| `rate_limit.max`                  | `RATE_LIMIT_MAX`                  | Máximo de solicitudes por ventana de límite de tasa                        |
| `rate_limit.expiry_sec`           | `RATE_LIMIT_EXPIRY_SEC`           | Duración de la ventana de límite de tasa (segundos)                        |
| `rate_limit.export_max`           | `EXPORT_RATE_LIMIT_MAX`           | Límite de tasa del endpoint de exportación                                 |
| `rate_limit.dispatch_max`         | `DISPATCH_RATE_LIMIT_MAX`         | Límite de tasa del endpoint de dispatch                                    |
| `rate_limit.admin_max`            | `ADMIN_RATE_LIMIT_MAX`            | Límite de tasa del plano admin (`/system`)                                 |
| `idempotency.retry_window_sec`    | `IDEMPOTENCY_RETRY_WINDOW_SEC`    | Ventana para reintentar solicitudes idempotentes fallidas                  |
| `idempotency.success_ttl_hours`   | `IDEMPOTENCY_SUCCESS_TTL_HOURS`   | Cuánto tiempo se almacenan en caché las claves de idempotencia completadas |
| `fetcher.discovery_interval_sec`  | `FETCHER_DISCOVERY_INTERVAL_SEC`  | Con qué frecuencia Matcher consulta Fetcher para nuevas fuentes de datos   |
| `export_worker.enabled`           | `EXPORT_WORKER_ENABLED`           | Habilitar o deshabilitar el worker de exportación                          |
| `export_worker.poll_interval_sec` | `EXPORT_WORKER_POLL_INTERVAL_SEC` | Con qué frecuencia el worker de exportación verifica nuevos trabajos       |
| `cleanup_worker.enabled`          | `CLEANUP_WORKER_ENABLED`          | Habilitar o deshabilitar el worker de limpieza                             |
| `cleanup_worker.interval_sec`     | `CLEANUP_WORKER_INTERVAL_SEC`     | Intervalo del worker de limpieza                                           |
| `scheduler.interval_sec`          | `SCHEDULER_INTERVAL_SEC`          | Intervalo de polling del scheduler                                         |
| `archival.enabled`                | `ARCHIVAL_WORKER_ENABLED`         | Habilitar o deshabilitar el worker de archivado                            |
| `webhook.timeout_sec`             | `WEBHOOK_TIMEOUT_SEC`             | Timeout para el despacho de webhooks/callbacks                             |
| `callback_rate_limit.per_minute`  | `CALLBACK_RATE_LIMIT_PER_MIN`     | Máximo de callbacks por sistema externo por minuto                         |
| `deduplication.ttl_sec`           | `DEDUPE_TTL_SEC`                  | TTL de deduplicación en segundos                                           |

### Claves multi-tenant (ajustables en tiempo de ejecución)

Estas claves controlan el comportamiento multi-tenant y pueden ajustarse sin reinicio. Consulta [Modo Multi-Tenant](/es/matcher/configuration/matcher-multi-tenant) para más detalles.

<Note>
  Habilitar el modo multi-tenant en sí (`tenancy.multi_tenant_enabled` / `MULTI_TENANT_ENABLED`) es **solo bootstrap** — se lee una vez al inicio y requiere un reinicio. No está registrado en la API de Systemplane y no puede alternarse en tiempo de ejecución. Consulta la tabla de solo bootstrap más abajo.
</Note>

| Clave                                   | Variable de entorno             | Descripción                                            |
| --------------------------------------- | ------------------------------- | ------------------------------------------------------ |
| `tenancy.multi_tenant_url`              | `MULTI_TENANT_URL`              | URL del servicio de multi-tenancy                      |
| `tenancy.multi_tenant_max_tenant_pools` | `MULTI_TENANT_MAX_TENANT_POOLS` | Máximo de pools de tenant concurrentes                 |
| `tenancy.multi_tenant_idle_timeout_sec` | `MULTI_TENANT_IDLE_TIMEOUT_SEC` | Timeout de inactividad para evicción de pool de tenant |
| `tenancy.multi_tenant_cache_ttl_sec`    | `MULTI_TENANT_CACHE_TTL_SEC`    | TTL de caché de configuración de tenant                |

### Claves solo bootstrap (requieren reinicio)

Estas claves no están registradas en la API de systemplane. Cámbialas mediante variables de entorno y reinicia:

| Clave                          | Variable de entorno    | Descripción                                                                                          |
| ------------------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------- |
| `tenancy.multi_tenant_enabled` | `MULTI_TENANT_ENABLED` | Habilitar infraestructura multi-tenant. Se lee una vez al inicio; requiere un reinicio para cambiar. |
| `app.env_name`                 | `ENV_NAME`             | Nombre del entorno de la aplicación                                                                  |
| `telemetry.enabled`            | `ENABLE_TELEMETRY`     | Habilitar OpenTelemetry                                                                              |
| `app.log_level`                | `LOG_LEVEL`            | Nivel de log de la aplicación (debug, info, warn, error)                                             |
| `server.address`               | `SERVER_ADDRESS`       | Dirección de escucha del servidor HTTP                                                               |
| `postgres.primary_host`        | `POSTGRES_HOST`        | Host de la base de datos primaria                                                                    |
| `postgres.primary_port`        | `POSTGRES_PORT`        | Puerto de la base de datos primaria                                                                  |
| `postgres.primary_db`          | `POSTGRES_DB`          | Nombre de la base de datos primaria                                                                  |
| `redis.host`                   | `REDIS_HOST`           | Host de Redis                                                                                        |
| `rabbitmq.host`                | `RABBITMQ_HOST`        | Host de RabbitMQ                                                                                     |
| `auth.enabled`                 | `PLUGIN_AUTH_ENABLED`  | Habilitar middleware de autenticación                                                                |
| `auth.host`                    | `PLUGIN_AUTH_ADDRESS`  | Dirección del servicio de autenticación                                                              |

## Mejores prácticas

***

<AccordionGroup>
  <Accordion title="Inspecciona los valores actuales antes de cambiar">
    Llama a `GET /system/matcher` para ver todos los valores actuales en tiempo de ejecución antes de realizar cualquier cambio. Esto confirma lo que el proceso está usando realmente, que puede diferir de las variables de entorno si se realizaron llamadas PUT anteriores.
  </Accordion>

  <Accordion title="Prueba los cambios en staging primero">
    Aunque los cambios en tiempo de ejecución no requieren reinicio, surten efecto de inmediato. Prueba en un entorno de staging antes de aplicar a producción.
  </Accordion>

  <Accordion title="Reinicia para claves solo bootstrap">
    Si una clave no es visible en `GET /system/matcher`, es solo bootstrap. Actualiza la variable de entorno y reinicia el servicio — no hay ruta en tiempo de ejecución para esos valores.
  </Accordion>
</AccordionGroup>

## Próximos pasos

***

<Card title="Modo multi-tenant" icon="building" href="/es/matcher/configuration/matcher-multi-tenant" horizontal>
  Habilitar y configurar el aislamiento de tenant.
</Card>

<Card title="Enrutamiento de excepciones" icon="route" href="/es/matcher/configuration/matcher-exception-routing" horizontal>
  Configurar cómo se despachan las excepciones a sistemas externos.
</Card>

<Card title="Reglas de coincidencia" icon="code-compare" href="/es/matcher/configuration/matcher-match-rules" horizontal>
  Configurar reglas de coincidencia de transacciones.
</Card>

<Card title="Seguridad" icon="shield" href="/es/matcher/reference/matcher-security" horizontal>
  Autenticación, autorización y protección de datos.
</Card>