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

# Relatórios operacionais

> Puxe eventos operacionais em nível de linha — como falhas de entrega no WhatsApp — dentro de uma janela de tempo limitada.

## O que são os relatórios operacionais

Os relatórios operacionais expõem **eventos em nível de linha** do seu workspace no endpoint `GET /v1/reports/{report}`. Diferente do [analytics agregado](/api-reference/export/analytics), aqui cada linha é um evento individual — pronto para investigação, auditoria ou reconciliação no seu próprio destino.

O primeiro relatório é o **`message_errors`**: as falhas de entrega de mensagens no WhatsApp (webhooks de status `failed` da Cloud API da Meta), com o código e a descrição do erro reportado pela Meta.

<Info>
  Cada relatório reutiliza o mesmo motor de paginação por cursor da exportação de entidades: mesmo envelope `{ data, next_cursor, count }`, mesma semântica de upsert por `id`, mesma chave de acesso do workspace.
</Info>

## Janela de tempo obrigatória

Ao contrário da exportação de entidades, o relatório `message_errors` **exige uma janela de tempo limitada**. Você informa `updated_since` (limite inferior, inclusivo) e, opcionalmente, `to` (limite superior; padrão: agora).

<Warning>
  `updated_since` é **obrigatório** em `message_errors`. Uma chamada sem ele é rejeitada com `400`. A janela (`to` − `updated_since`) **não pode exceder 31 dias** — para períodos maiores, faça várias chamadas em janelas consecutivas.
</Warning>

A janela mantém o relatório rápido e previsível — por isso o teto de 31 dias.

## Como paginar

<Steps>
  <Step title="Defina a janela">
    Escolha `updated_since` (e opcionalmente `to`), respeitando o teto de 31 dias. Use o timestamp da última sincronização como `updated_since`.
  </Step>

  <Step title="Puxe a primeira página">
    Chame `GET /v1/reports/message_errors?updated_since=<ISO 8601>`. Aplique os filtros que precisar (`deal_id`, `conversation_id`, `agent_id`, `external_id`, `error_code`).
  </Step>

  <Step title="Grave e pagine">
    Faça **upsert por `id`** das linhas de `data`. Se `next_cursor` não for `null`, chame de novo passando `cursor=<next_cursor>` até `next_cursor` retornar `null`.
  </Step>

  <Step title="Avance a janela">
    Na próxima sincronização, use como `updated_since` o maior `cursor_at` já processado. Para varrer um histórico longo, itere janelas de até 31 dias.
  </Step>
</Steps>

## Filtros do relatório

Os filtros abaixo são ANDados após o escopo do workspace. Chaves de filtro desconhecidas são simplesmente ignoradas.

| Filtro            | Corresponde a                         |
| ----------------- | ------------------------------------- |
| `deal_id`         | Id do deal da conversa                |
| `conversation_id` | Id da conversa                        |
| `agent_id`        | Agente responsável pela conversa      |
| `external_id`     | Id da mensagem no WhatsApp (wamid)    |
| `error_code`      | Código do erro de entrega do WhatsApp |

<Tip>
  Os filtros por índice (`deal_id`, `conversation_id`) são os mais eficientes: eles ajudam a podar a consulta cedo. `external_id` e `error_code` são filtros residuais — úteis, mas aplicados sobre as linhas com falha da janela.
</Tip>

O significado de cada coluna retornada está na referência do endpoint [Falhas de mensagens](/api-reference/export/message-errors).

<Warning>
  `recipient_id` é o telefone do seu cliente final (E.164). Ele é liberado porque o dado de contato é do seu workspace — mas é PII: trate-o com o mesmo cuidado dos demais dados de contato ao gravar e compartilhar.
</Warning>

## Referência e playground

Consulte [Falhas de mensagens](/api-reference/export/message-errors) para todos os parâmetros, formatos de resposta e códigos de erro — e para testar a chamada direto no playground.