> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Anotações

> Marque os momentos que explicam um gráfico: um lançamento, uma campanha, uma queda do site.

![Lista de anotações com entradas manuais e anotações automáticas de broadcasts, filtrada por Todos, Manual ou Broadcast](https://www.notifuse.com/docs/assets/screenshots/web_analytics/annotations.png)

Uma anotação marca um momento, como o dia em que você lançou algo, a manhã em que o site caiu ou a hora em que uma campanha foi enviada. Ela aparece como uma linha vertical com rótulo nos gráficos do Web Analytics, de modo que um pico ou uma queda fica com a explicação ao lado.

As anotações pertencem ao workspace e são gerenciadas em **Web Analytics** → **Anotações**.

## Adicionar uma anotação

Clique em **Adicionar** e preencha o formulário:

| Campo        | Obrigatório | Observações                                                                                                     |
| ------------ | ----------- | --------------------------------------------------------------------------------------------------------------- |
| Data         | Sim         | O dia que está sendo marcado.                                                                                   |
| Hora         | Sim         | O padrão é 12:00, o que costuma bastar para um gráfico diário.                                                  |
| Fuso Horário | Sim         | Começa no fuso horário em que os seus gráficos são desenhados.                                                  |
| Título       | Sim         | Até 100 caracteres. É o que aparece no gráfico.                                                                 |
| Descrição    | Não         | Até 500 caracteres, exibida na dica do gráfico e na lista.                                                      |
| Cor          | Não         | Predefinições: verde, vermelho, âmbar, azul e o roxo usado pelos broadcasts. Azul se você não escolher nenhuma. |

> [!NOTE]
>
> O fuso horário é armazenado com a anotação, então o momento aparece exatamente como foi digitado: uma queda registrada às 9h em Tóquio continua aparecendo às 9h para um colega em Paris.

## Onde elas aparecem

No gráfico do **Dashboard** e no gráfico dentro do painel lateral de uma meta, na seção **Metas**.

Cada anotação é desenhada como uma linha vertical pontilhada na sua própria cor, com o título no alto da área do gráfico (truncado se for longo). Passar o mouse sobre esse ponto do gráfico acrescenta o título e a descrição da anotação à dica, abaixo dos valores das métricas.

A linha cai no intervalo que contém o momento, então a precisão da posição depende da granularidade que você está vendo. As anotações fora do período exibido na tela não são desenhadas.

> [!NOTE]
>
> Várias anotações que caem no mesmo intervalo se juntam em uma única linha, com o primeiro título e um `+N`. Passe o mouse sobre ela e a dica lista todas por completo.

## Anotações de broadcasts

Quando um broadcast começa a ser enviado, o Notifuse grava uma anotação com o nome dele, marcada como **Broadcast** na lista e desenhada em roxo nos gráficos. Assim, um aumento de tráfego e a campanha que o causou aparecem no mesmo gráfico.

- Ela só é gravada quando o envio começa, depois que as verificações do workspace, do provedor e do template passam. Um broadcast que não consegue carregar os templates não envia nada a ninguém e nunca recebe anotação.
- Há uma anotação por broadcast, não importa quantas vezes a tarefa de envio seja retomada.
- Elas sempre aparecem nos gráficos, e por decisão de projeto nenhuma configuração as esconde.
- Depois de criada, a anotação é independente do broadcast: excluir o broadcast mantém a anotação, já que o envio aconteceu, e excluir a anotação não afeta o broadcast.

O filtro **Todos / Manual / Broadcast** acima da lista filtra só a lista, e não os gráficos.

## Editar e excluir

Qualquer anotação pode ser editada ou excluída a partir da lista, inclusive as de broadcasts, por exemplo para reescrever um título automático de um jeito que você vá reconhecer daqui a seis meses.

A edição muda apenas o momento e o fuso horário, o texto e a cor. Uma anotação de broadcast mantém a origem e a marcação, por mais que você a reescreva, e uma anotação que você mesmo digitou nunca pode virar uma de broadcast.

A exclusão é imediata e não pode ser desfeita.

## Gerenciar pela API

As anotações têm cinco endpoints, documentados na [Referência da API](https://www.notifuse.com/docs/api-reference.md):

| Endpoint                       | Finalidade                                                 |
| ------------------------------ | ---------------------------------------------------------- |
| `GET /api/annotations.list`    | Listar, com filtro opcional por `start`, `end` e `sources` |
| `GET /api/annotations.get`     | Buscar uma pelo id                                         |
| `POST /api/annotations.create` | Criar                                                      |
| `POST /api/annotations.update` | Editar                                                     |
| `POST /api/annotations.delete` | Excluir                                                    |

O acesso segue a permissão de Web Analytics: leitura para `list` e `get`, escrita para os demais.

Conecte o seu pipeline de deploy ou a sua página de status a esses endpoints, para que lançamentos e incidentes cheguem ao gráfico sem ninguém precisar digitá-los.

> [!WARNING]
>
> A API só cria anotações do tipo **manual** (quem chama não pode criar uma de broadcast), e não há chave de idempotência. Um job que repete uma criação grava uma segunda anotação. Faça a deduplicação do seu lado ou limpe na página Anotações.

## Observações

- `list` retorna por padrão as 100 anotações mais recentes, e no máximo 1.000. A página Anotações e os gráficos pedem o máximo.
- A página Anotações funciona mesmo antes de o rastreador ser instalado, ao contrário do resto do Web Analytics: um workspace que só envia broadcasts continua acumulando anotações de broadcasts.
- [Referência da API](https://www.notifuse.com/docs/api-reference.md)
