> ## 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 las ejecuciones de conciliación con programaciones basadas en cron por contexto, y gestiónalas a través de un ciclo de vida completo de creación, listado, consulta, actualización y eliminación.

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, de modo que un contexto puede conciliarse a diario, cada hora o con cualquier frecuencia personalizada que definas.

## ¿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 de la última ejecución exitosa (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>API Reference: [Create schedule](/es/reference/matcher/create-schedule) | [List schedules](/es/reference/matcher/list-schedules) | [Get schedule](/es/reference/matcher/retrieve-schedule) | [Update schedule](/es/reference/matcher/update-schedule) | [Delete schedule](/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)
</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="Contexts and Sources" 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="Generating Reports" icon="chart-pie" href="/es/matcher/daily-reconciliation/matcher-generating-reports" horizontal>
  Revisa los resultados producidos por las ejecuciones programadas.
</Card>