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

# Agendamentos

> Automatize execuções de conciliação com agendamentos por contexto baseados em cron e gerencie-os por um ciclo de vida completo de criar, listar, recuperar, atualizar e excluir.

Os agendamentos permitem rodar a conciliação automaticamente em uma cadência recorrente, em vez de disparar execuções de correspondência na mão. Cada agendamento pertence a um contexto de conciliação e dispara por uma expressão cron, com um intervalo mínimo de cinco minutos entre disparos.

## O que é um agendamento?

***

Um agendamento é um gatilho baseado em cron ligado a um contexto. Quando ele dispara, o Matcher inicia uma execução de correspondência `COMMIT` para esse contexto com as regras e as fontes dele. A execução só concilia quando o contexto está `ACTIVE`.

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | UUID | Identificador único do agendamento |
| `contextId` | UUID | Contexto ao qual este agendamento pertence |
| `cronExpression` | String | Expressão cron que define a frequência (por exemplo `0 0 * * *` para diariamente à meia-noite) |
| `enabled` | Boolean | Se o agendamento está ativo |
| `lastRunAt` | Timestamp | Momento em que o Matcher despachou pela última vez o gatilho assíncrono de execução de correspondência; não indica conclusão nem sucesso (RFC 3339) |
| `nextRunAt` | Timestamp | Próximo horário de execução agendado (RFC 3339) |
| `createdAt` / `updatedAt` | Timestamp | Timestamps de criação e da última atualização (RFC 3339) |

## Ciclo de vida do agendamento

***

Os agendamentos têm um ciclo de vida CRUD completo em `/v1/contexts/{contextId}/schedules`.

| Ação | Método e caminho |
| - | - |
| Criar agendamento | `POST /v1/contexts/{contextId}/schedules` |
| Listar agendamentos | `GET /v1/contexts/{contextId}/schedules` |
| Recuperar agendamento | `GET /v1/contexts/{contextId}/schedules/{scheduleId}` |
| Atualizar agendamento | `PATCH /v1/contexts/{contextId}/schedules/{scheduleId}` |
| Excluir agendamento | `DELETE /v1/contexts/{contextId}/schedules/{scheduleId}` |

> [!TIP]
>
> Referência da API:
>
> * [Criar agendamento](https://docs.lerian.studio/pt/reference/products/matcher/create-schedule.md)
> * [Listar agendamentos](https://docs.lerian.studio/pt/reference/products/matcher/list-schedules.md)
> * [Obter agendamento](https://docs.lerian.studio/pt/reference/products/matcher/retrieve-schedule.md)
> * [Atualizar agendamento](https://docs.lerian.studio/pt/reference/products/matcher/update-schedule.md)
> * [Excluir agendamento](https://docs.lerian.studio/pt/reference/products/matcher/delete-schedule.md)

## Como criar um agendamento

***

Forneça uma `cronExpression`. O campo `enabled` fica ativo por padrão quando omitido.

```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
 }'
```

**cronExpression** `String` *required*

Expressão cron que define a frequência de execução (1–100 caracteres), com pelo menos cinco minutos entre disparos. Use cinco campos: minuto, hora, dia do mês, mês e dia da semana. O Matcher rejeita um campo de segundos, macros como `@daily` e agendamentos por minuto e abaixo de um minuto

**enabled** `Boolean`

Se o agendamento fica ativo imediatamente

A resposta retorna o agendamento criado, incluindo o `id`, o `nextRunAt` e os timestamps dele. Listar agendamentos (`GET`) retorna cada agendamento do contexto, habilitados e desabilitados igualmente.

## Pausar vs. excluir um agendamento

***

Quando você precisar parar uma conciliação recorrente, tem duas opções.

**Desabilite** o agendamento para pausar as execuções automáticas mantendo a configuração e o histórico dele. Reabilitar depois é uma única chamada, sem precisar recriá-lo. Atualize a expressão cron, alterne `enabled` ou faça os dois (os campos omitidos ficam inalterados):

```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
 }'
```

**Exclua** o agendamento (`DELETE .../schedules/{scheduleId}`) apenas quando a cadência tiver acabado de vez. A exclusão é permanente. Para dar uma pausa, desabilite.

## Boas práticas

***

> [accordion] Alinhe a cadência com a disponibilidade das fontes
>
> Agende as execuções para disparar depois que todas as fontes do contexto entregarem os dados delas do período. Rodar antes de a ingestão terminar produz exceções evitáveis.

> [accordion] Prefira desabilitar a excluir
>
> Para pausar uma cadência de conciliação, desabilite o agendamento. Ele mantém o histórico e a configuração, e reabilitar é uma única chamada.

> [accordion] Use expressões cron explícitas
>
> Mantenha as expressões cron legíveis e documentadas (por exemplo `0 0 * * *` = diariamente às 00:00). O Matcher as avalia em UTC.

## Próximos passos

***

> [card] [Contextos e fontes](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-contexts-and-sources.md)
>
> Configure os contextos e as fontes que um agendamento concilia.

> [card] [Geração de relatórios](https://docs.lerian.studio/pt/products/matcher/daily-reconciliation/matcher-generating-reports.md)
>
> Revise os resultados produzidos pelas execuções agendadas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.