> ## 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 reconciliação com agendamentos baseados em cron por contexto e gerencie-os através de um ciclo de vida completo de criação, listagem, consulta, atualização e exclusão.

Agendamentos permitem executar a reconciliação automaticamente em uma cadência recorrente, em vez de disparar execuções de correspondência manualmente. Cada agendamento pertence a um contexto de reconciliação e dispara com base em uma expressão cron, de modo que um contexto pode ser reconciliado diariamente, de hora em hora ou em qualquer frequência personalizada que você definir.

## O que é um agendamento?

***

Um agendamento é um gatilho baseado em cron vinculado a um contexto. Quando dispara, o Matcher lança uma execução de reconciliação para aquele contexto usando suas regras e fontes ativas.

| 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 | Horário da última execução bem-sucedida (RFC 3339)                                              |
| `nextRunAt`               | Timestamp | Horário da próxima execução agendada (RFC 3339)                                                 |
| `createdAt` / `updatedAt` | Timestamp | Timestamps de criação e da última atualização (RFC 3339)                                        |

## Ciclo de vida do agendamento

***

Agendamentos suportam 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`                 |
| Consultar 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](/pt/reference/matcher/create-schedule) | [Listar agendamentos](/pt/reference/matcher/list-schedules) | [Obter agendamento](/pt/reference/matcher/retrieve-schedule) | [Atualizar agendamento](/pt/reference/matcher/update-schedule) | [Excluir agendamento](/pt/reference/matcher/delete-schedule)</Tip>

## Criando um agendamento

***

Forneça uma `cronExpression`; `enabled` assume o valor 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
 }'
```

<ParamField path="cronExpression" type="String" required>
  Expressão cron que define a frequência de execução (1–100 caracteres)
</ParamField>

<ParamField path="enabled" type="Boolean">
  Se o agendamento fica ativo imediatamente
</ParamField>

A resposta retorna o agendamento criado, incluindo seu `id`, `nextRunAt` e timestamps. A listagem de agendamentos (`GET`) retorna todos os agendamentos do contexto, habilitados e desabilitados igualmente.

## Pausar vs. excluir um agendamento

***

Quando você precisa parar uma reconciliação recorrente, tem duas opções — e a escolha importa.

**Desabilite** o agendamento para pausar as execuções automáticas mantendo sua configuração e histórico. Reabilitar depois é uma única chamada, sem necessidade de recriá-lo. Atualize a expressão cron, alterne `enabled` ou ambos (os campos omitidos permanecem 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 acabou de vez — a exclusão é permanente. Para simplesmente fazer uma pausa, desabilite em vez disso.

## Boas práticas

***

<AccordionGroup>
  <Accordion title="Alinhe a cadência com a disponibilidade das fontes">
    Agende as execuções para dispararem depois que todas as fontes do contexto tiverem entregue seus dados do período. Executar antes de a ingestão concluir produz exceções evitáveis.
  </Accordion>

  <Accordion title="Prefira desabilitar a excluir">
    Ao pausar uma cadência de reconciliação, desabilite o agendamento para que histórico e configuração sejam preservados e reabilitar seja uma única chamada.
  </Accordion>

  <Accordion title="Use expressões cron explícitas">
    Mantenha as expressões cron legíveis e documentadas (por exemplo, `0 0 * * *` = diariamente às 00:00). Verifique as premissas de fuso horário do seu ambiente antes de depender de um agendamento para execuções sensíveis a SLA.
  </Accordion>
</AccordionGroup>

## Próximos passos

***

<Card title="Contextos e Fontes" icon="folder-tree" href="/pt/matcher/configuration/matcher-contexts-and-sources" horizontal>
  Configure os contextos e as fontes que um agendamento reconcilia.
</Card>

<Card title="Gerando Relatórios" icon="chart-pie" href="/pt/matcher/daily-reconciliation/matcher-generating-reports" horizontal>
  Revise os resultados produzidos pelas execuções agendadas.
</Card>