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

# Gerenciando prazos

> Acompanhe quando relatórios regulatórios e de negócio vencem com os prazos do Reporter: crie obrigações recorrentes, monitore o status delas e marque-as como entregues.

Um **prazo** é a camada de rastreamento do Reporter para entregas de relatórios. Templates definem *como* um relatório se parece, e a geração de relatórios produz o *resultado*. Um prazo registra *quando* um relatório vence e o estado de entrega dele. Cada prazo representa uma obrigação de entrega, tipicamente uma remessa regulatória ou um relatório de negócio recorrente. Você pode, opcionalmente, vincular um prazo ao template que o cumpre.

Prazos ficam ao lado do [ciclo de vida da geração de relatórios](https://docs.lerian.studio/pt/products/reporter/reporter-quick-start.md#the-reporting-lifecycle) como um rastreador operacional, para que as equipes vejam o que está `pending`, `overdue`, ou já `delivered`.

## Por que os prazos existem

***

A geração de relatórios responde *como* e *o quê*. Prazos respondem *quando* e *se foi cumprido*. Sem uma camada de rastreamento, uma equipe pode produzir relatórios perfeitos e ainda perder uma janela de envio. Nada no mecanismo de geração de relatórios em si sabe que um relatório estava *vencendo*.

Prazos resolvem um problema de compliance de entrega. Eles transformam obrigações de geração de relatórios recorrentes em compromissos rastreados e datados, para que nada escape silenciosamente:

* **Obrigações de envio regulatório**: muitos envios devem chegar a um regulador em um cronograma fixo. Um prazo registra essa obrigação, a recorrência dela e o estado de entrega dela, para que um envio perdido ou atrasado fique visível antes de se tornar um incidente de compliance.
* **SLAs internos**: relatórios de negócio recorrentes costumam carregar compromissos internos ("o financeiro recebe o pacote de fechamento mensal até o dia 5"). Prazos tornam esses compromissos explícitos e mensuráveis.
* **Trilhas de auditoria para entrega**: cada prazo registra `deliveredAt` e passa por `pending` → `overdue` → `delivered`. Isso deixa um histórico auditável de *quando* cada obrigação foi cumprida.

## Quem usa os prazos

***

Prazos são uma ferramenta de negócio e compliance construída sobre o mecanismo de geração de relatórios. Usuários típicos incluem:

* Uma **fintech que entrega relatórios regulatórios ao BACEN** em cronogramas fixos mensais ou anuais. Ela usa prazos para rastrear e cumprir cada janela de envio.
* Uma **equipe de tesouraria ou financeiro** rastreando entregas de relatórios mensais recorrentes, usando a visualização de calendário e status para confirmar que cada saída rotineira foi enviada no prazo.
* Um **profissional de compliance** monitorando obrigações vencidas em toda a organização, filtrando pelo status `overdue` para identificar qualquer coisa em risco antes que escale.

Para essas equipes, os prazos mostram o que está por vir, o que está atrasado e o que está concluído.

## Como os prazos se encaixam no workflow do Reporter

***

Prazos envolvem relatórios e fontes de dados para adicionar uma camada de status de entrega sobre o mecanismo de geração de relatórios. Fontes de Dados fornecem os dados, Templates definem o resultado, e o ciclo de vida da geração de relatórios produz o arquivo. Um prazo fica acima de tudo isso. Ele opcionalmente se vincula ao template que cumpre a obrigação, observa a data de vencimento, e expõe um único status. O status informa ao negócio se a obrigação foi cumprida.

Prazos nunca enviam um relatório a um regulador. Quando um operador ativa o gatilho de prazos, o Reporter publica `deadline.due` no dia em que um prazo vence. Ele também gera o relatório, mas apenas para as categorias de template que o operador lista em `DEADLINE_TRIGGER_GENERATE_CATEGORIES`. Em todos os outros casos, você gera relatórios pelo ciclo de vida normal, e o prazo registra o status de entrega.

## O que um prazo rastreia

***

Cada prazo captura a data de vencimento de uma obrigação de relatório, além dos metadados que a sua equipe precisa para gerenciá-la:

| Campo | Descrição |
| - | - |
| `name` | Nome legível do prazo (por exemplo, *Monthly Regulatory Report*). |
| `description` | Descrição mais longa e opcional da obrigação. |
| `type` | Classificação do prazo, como `regulatory` ou `custom`. |
| `frequency` | Com que frequência o prazo recorre, como `monthly` ou `annual`. |
| `dueDate` | Quando o relatório vence, no formato RFC 3339. |
| `color` | Cor hexadecimal usada para identificar visualmente o prazo nos dashboards. |
| `notifyDaysBefore` | Número de dias antes da data de vencimento em que as notificações começam. |
| `monthsOfYear` | Meses (1–12) em que um prazo `semiannual` ou `annual` vence. Obrigatório para essas duas frequências e recusado para as demais. |
| `templateId` | UUID opcional do [template](https://docs.lerian.studio/pt/products/reporter/using-reporter.md) usado para cumprir o prazo. O template deve ter uma categoria. |
| `filters` | Filtros de linha opcionais, por fonte de dados, tabela e campo, para o relatório gerado para este prazo. Uma condição pode usar `period`, como `previous_month`, que o Reporter converte em um intervalo de datas quando o prazo dispara. |
| `active` | Se o prazo está ativo no momento. |

O Reporter também mantém campos somente leitura em cada prazo: `id`, `status` (`pending`, `overdue`, ou `delivered`), `deliveredAt`, `templateName`, `createdAt`, e `updatedAt`.

> [!NOTE]
>
> Inclua um header `Authorization: Bearer <token>` em cada requisição de prazo se o seu ambiente habilitar o [Access Manager](https://docs.lerian.studio/pt/platform/access-manager.md).

## Criando um prazo

***

Crie um prazo com o endpoint [Criar um Prazo](https://docs.lerian.studio/pt/reference/products/reporter/create-deadline.md) (`POST /v1/deadlines`).

Os campos obrigatórios são `name`, `type`, `frequency`, `dueDate`, e `color`. Defina `templateId` para vincular o prazo ao template que o cumpre, e `notifyDaysBefore` para controlar quando os lembretes começam.

```json theme={null}
{
  "name": "Monthly Regulatory Report",
  "description": "Monthly regulatory compliance report",
  "type": "regulatory",
  "frequency": "monthly",
  "dueDate": "2026-03-31T23:59:59Z",
  "color": "#FF5733",
  "notifyDaysBefore": 5,
  "templateId": "00000000-0000-0000-0000-000000000000",
  "active": true
}
```

Uma requisição bem-sucedida retorna `201 Created` com o prazo completo, incluindo o `id` gerado e um `status` inicial.

> [!TIP]
>
> Referência da API: [Criar um Prazo](https://docs.lerian.studio/pt/reference/products/reporter/create-deadline.md)

## Listando prazos

***

Recupere prazos com o endpoint [Recuperar Prazos](https://docs.lerian.studio/pt/reference/products/reporter/retrieve-deadlines.md) (`GET /v1/deadlines`). O endpoint pagina os resultados, e você pode filtrá-los por status, atividade, tipo e intervalo de vencimento.

| Parâmetro de consulta | Descrição | Padrão |
| - | - | - |
| `status` | Filtra por `pending`, `overdue`, ou `delivered`. | — |
| `active` | Filtra por prazos ativos ou inativos. | — |
| `type` | Filtra por tipo de prazo. | — |
| `start_date`, `end_date` | Primeira e última data de vencimento, em `YYYY-MM-DD`, inclusivas. | — |
| `limit` | Número de registros por página (número inteiro ≥ 1). | `10` |
| `page` | Número da página a retornar (número inteiro ≥ 1). | `1` |

Por exemplo, para listar prazos vencidos, dez por página:

```
GET /v1/deadlines?status=overdue&limit=10&page=1
```

A resposta contém um array `items` além de `page`, `limit`, e `total` para paginação.

> [!TIP]
>
> Referência da API: [Recuperar Prazos](https://docs.lerian.studio/pt/reference/products/reporter/retrieve-deadlines.md)

## Atualizando um prazo

***

Atualize um prazo existente com o endpoint [Atualizar um Prazo](https://docs.lerian.studio/pt/reference/products/reporter/update-deadline.md) (`PATCH /v1/deadlines/{id}`). O endpoint altera apenas os campos no corpo da requisição, então você pode enviar um payload parcial. Por exemplo, adie uma data de vencimento ou desative um prazo:

```json theme={null}
{
  "dueDate": "2026-06-30T23:59:59Z",
  "notifyDaysBefore": 10,
  "active": false
}
```

Uma requisição bem-sucedida retorna `200 OK` com o prazo atualizado.

> [!TIP]
>
> Referência da API: [Atualizar um Prazo](https://docs.lerian.studio/pt/reference/products/reporter/update-deadline.md)

## Excluindo um prazo

***

Remova um prazo que você não precisa mais rastrear com o endpoint [Excluir um Prazo](https://docs.lerian.studio/pt/reference/products/reporter/delete-deadline.md) (`DELETE /v1/deadlines/{id}`). Uma requisição bem-sucedida retorna `204 No Content`.

> [!TIP]
>
> Referência da API: [Excluir um Prazo](https://docs.lerian.studio/pt/reference/products/reporter/delete-deadline.md)

## Marcando um prazo como entregue

***

Depois de protocolar ou enviar o relatório por trás de um prazo, marque o prazo como entregue. Use o endpoint [Entregar um Prazo](https://docs.lerian.studio/pt/reference/products/reporter/deliver-deadline.md) (`PATCH /v1/deadlines/{id}/deliver`). Ele move o `status` do prazo para `delivered` e registra `deliveredAt`.

```json theme={null}
{
  "delivered": true
}
```

Como `delivered` é um booleano, o mesmo endpoint também pode reverter a ação. Envie `"delivered": false` para reabrir um prazo que você marcou como entregue por engano. Uma requisição bem-sucedida retorna `200 OK` com o prazo atualizado.

> [!NOTE]
>
> Entregar um prazo apenas rastreia a obrigação. Isso registra que a obrigação foi cumprida. Isso não gera nem envia o relatório subjacente. Gere o relatório pelo [ciclo de vida da geração de relatórios](https://docs.lerian.studio/pt/products/reporter/reporter-quick-start.md), depois marque o prazo como entregue para manter o seu rastreador preciso.

> [!TIP]
>
> Referência da API: [Entregar um Prazo](https://docs.lerian.studio/pt/reference/products/reporter/deliver-deadline.md)

## Como os prazos se encaixam no workflow

***

Uma obrigação típica passa por estes estados:

**1. Criar o prazo**

Registre a obrigação com a data de vencimento, a frequência e o template opcional dela.

**2. Rastrear o status dele**

Aparece como `pending` até a data de vencimento, depois `overdue` se você não entregar o relatório a tempo.

**3. Gerar o relatório**

Produza o relatório pelo [ciclo de vida da geração de relatórios](https://docs.lerian.studio/pt/products/reporter/reporter-quick-start.md) normal, usando o template vinculado.

**4. Marcá-lo como entregue**

Chame o endpoint de entrega para definir o `status` como `delivered` e registrar `deliveredAt`.

## Próximos passos

***

> [card] [Primeiros passos com o Reporter](https://docs.lerian.studio/pt/products/reporter/reporter-quick-start.md)
>
> Percorra o ciclo de vida da geração de relatórios que os prazos rastreiam.

> [card] [Usando o Reporter](https://docs.lerian.studio/pt/products/reporter/using-reporter.md)
>
> Construa os templates que cumprem seus prazos.

> [card] [Templates do BACEN](https://docs.lerian.studio/pt/products/reporter/reporter-bacen-templates)
>
> Templates prontos para uso para geração de relatórios regulatórios brasileiros.

> [card] [API de Prazos](https://docs.lerian.studio/pt/reference/products/reporter/create-deadline.md)
>
> Referência completa de requisição e resposta para cada endpoint de prazo.


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