> ## 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 lança uma execução de conciliação para esse contexto usando as regras e as fontes ativas dele.
| 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}` |
Referência da API:
* [Criar agendamento](/pt/reference/products/matcher/create-schedule)
* [Listar agendamentos](/pt/reference/products/matcher/list-schedules)
* [Obter agendamento](/pt/reference/products/matcher/retrieve-schedule)
* [Atualizar agendamento](/pt/reference/products/matcher/update-schedule)
* [Excluir agendamento](/pt/reference/products/matcher/delete-schedule)
## Como criar um agendamento
***
Forneça uma `cronExpression`. O campo `enabled` assume ativo como 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
}'
```
Expressão cron que define a frequência de execução (1–100 caracteres), com pelo menos cinco minutos entre disparos. O Matcher rejeita agendamentos por minuto e abaixo de um minuto
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
***
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.
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.
Mantenha as expressões cron legíveis e documentadas (por exemplo `0 0 * * *` = diariamente às 00:00). Verifique as suposições de fuso horário do seu deploy antes de depender de um agendamento para execuções sensíveis a SLA.
## Próximos passos
***
Configure os contextos e as fontes que um agendamento concilia.
Revise os resultados produzidos pelas execuções agendadas.