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

# Programaciones

> Automatiza ejecuciones de conciliación con programaciones cron por contexto, y gestiónalas mediante crear, listar, consultar, actualizar y eliminar.

Las programaciones te permiten ejecutar la conciliación automáticamente con una cadencia recurrente en lugar de disparar las ejecuciones de coincidencia a mano. Cada programación pertenece a un contexto de conciliación y se dispara según una expresión cron, con un intervalo mínimo de cinco minutos entre disparos.

## ¿Qué es una programación?

***

Una programación es un disparador basado en cron asociado a un contexto. Cuando se dispara, Matcher lanza una ejecución de conciliación para ese contexto usando sus reglas y fuentes activas.

| Campo                     | Tipo      | Descripción                                                                                                                                                  |
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                      | UUID      | Identificador único de la programación                                                                                                                       |
| `contextId`               | UUID      | Contexto al que pertenece esta programación                                                                                                                  |
| `cronExpression`          | String    | Expresión cron que define la frecuencia (por ejemplo, `0 0 * * *` para diario a medianoche)                                                                  |
| `enabled`                 | Boolean   | Si la programación está activa                                                                                                                               |
| `lastRunAt`               | Timestamp | Hora en que Matcher despachó por última vez el disparador asíncrono de una ejecución de coincidencia; no indica que se completó ni que tuvo éxito (RFC 3339) |
| `nextRunAt`               | Timestamp | Hora de la próxima ejecución programada (RFC 3339)                                                                                                           |
| `createdAt` / `updatedAt` | Timestamp | Marcas de tiempo de creación y última actualización (RFC 3339)                                                                                               |

## Ciclo de vida de una programación

***

Las programaciones admiten un ciclo de vida CRUD completo bajo `/v1/contexts/{contextId}/schedules`.

| Acción                  | Método y ruta                                            |
| ----------------------- | -------------------------------------------------------- |
| Crear programación      | `POST /v1/contexts/{contextId}/schedules`                |
| Listar programaciones   | `GET /v1/contexts/{contextId}/schedules`                 |
| Consultar programación  | `GET /v1/contexts/{contextId}/schedules/{scheduleId}`    |
| Actualizar programación | `PATCH /v1/contexts/{contextId}/schedules/{scheduleId}`  |
| Eliminar programación   | `DELETE /v1/contexts/{contextId}/schedules/{scheduleId}` |

<Tip>Referencia de la API: [Crear programación](/es/reference/matcher/create-schedule) | [Listar programaciones](/es/reference/matcher/list-schedules) | [Obtener programación](/es/reference/matcher/retrieve-schedule) | [Actualizar programación](/es/reference/matcher/update-schedule) | [Eliminar programación](/es/reference/matcher/delete-schedule)</Tip>

## Crear una programación

***

Proporciona una `cronExpression`; `enabled` toma el valor activo por defecto cuando se omite.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/schedules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "cronExpression": "0 0 * * *",
   "enabled": true
 }'
```

<ParamField path="cronExpression" type="String" required>
  Expresión cron que define la frecuencia de ejecución (1–100 caracteres), con al menos cinco minutos entre disparos. Se rechazan las programaciones por minuto y subminuto
</ParamField>

<ParamField path="enabled" type="Boolean">
  Si la programación está activa de inmediato
</ParamField>

La respuesta devuelve la programación creada, incluyendo su `id`, `nextRunAt` y marcas de tiempo. Listar las programaciones (`GET`) devuelve todas las programaciones del contexto, tanto habilitadas como deshabilitadas.

## Pausar vs. eliminar una programación

***

Cuando necesitas detener una conciliación recurrente, tienes dos opciones, y la elección importa.

**Deshabilita** la programación para pausar las ejecuciones automáticas conservando su configuración e historial. Volver a habilitarla más adelante es una sola llamada, sin necesidad de recrearla. Actualiza la expresión cron, alterna `enabled`, o ambas cosas (los campos omitidos se dejan sin cambios):

```bash cURL theme={null}
curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}/schedules/{scheduleId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "cronExpression": "0 6 * * *",
   "enabled": false
 }'
```

**Elimina** la programación (`DELETE .../schedules/{scheduleId}`) solo cuando la cadencia haya desaparecido definitivamente: la eliminación es permanente. Para simplemente tomar una pausa, deshabilítala en su lugar.

## Buenas prácticas

***

<AccordionGroup>
  <Accordion title="Alinea la cadencia con la disponibilidad de las fuentes">
    Programa las ejecuciones para que se disparen después de que todas las fuentes del contexto hayan entregado sus datos del período. Ejecutar antes de que finalice la ingesta produce excepciones evitables.
  </Accordion>

  <Accordion title="Prefiere deshabilitar antes que eliminar">
    Al pausar una cadencia de conciliación, deshabilita la programación para que el historial y la configuración se conserven y volver a habilitarla sea una sola llamada.
  </Accordion>

  <Accordion title="Usa expresiones cron explícitas">
    Mantén las expresiones cron legibles y documentadas (por ejemplo, `0 0 * * *` = diario a las 00:00). Verifica los supuestos de zona horaria de tu despliegue antes de depender de una programación para ejecuciones sensibles a SLA.
  </Accordion>
</AccordionGroup>

## Próximos pasos

***

<Card title="Contextos y fuentes" icon="folder-tree" href="/es/matcher/configuration/matcher-contexts-and-sources" horizontal>
  Configura los contextos y las fuentes que reconcilia una programación.
</Card>

<Card title="Generando reportes" icon="chart-pie" href="/es/matcher/daily-reconciliation/matcher-generating-reports" horizontal>
  Revisa los resultados producidos por las ejecuciones programadas.
</Card>