# O relatório semanal do cliente, escrito por um agente toda segunda antes de você acordar

_2026-09-25 · Monte um relatório semanal que um agente compila a partir do Shager: o que saiu, o que falhou, cliques por conta e por post e como cruzar com os leads do CRM._

Um agente consegue escrever o relatório semanal de distribuição de um cliente puxando três coisas do Shager: os posts publicados na semana e o resultado de cada um por conta, os cliques por conta e por post vindos de `get_analytics` e a lista de tudo o que falhou. Depois, ele cruza esses cliques com os leads do CRM do cliente usando o valor de `utm_content` que identifica cada conta. Rode isso de forma agendada, com uma chave só de leitura, e o relatório estará esperando numa pasta na segunda de manhã.

A parte que exige reflexão não é o código. É decidir o que o cliente realmente precisa ver e ser honesto sobre o que os números medem.

## O que um relatório semanal de distribuição deve conter?

Quatro seções bastam. O resto fica para a revisão mensal.

1. **Entrega.** Quantos posts saíram, para quantas contas e quais contas falharam. Os clientes raramente perguntam sobre isso até algo sumir, e aí é a única coisa que perguntam.
2. **Cliques por conta.** Quais páginas, filiais ou canais mandaram gente para o site. É a seção que muda orçamentos.
3. **Cliques por post.** Qual conteúdo funcionou, somando todas as contas.
4. **Ações.** O que o cliente precisa fazer: reconectar uma conta, aprovar os rascunhos da próxima semana, enviar materiais que faltam.

Repare no que ficou de fora: alcance, impressões, curtidas. O Shager mede os cliques nos próprios links rastreáveis, por conta e por post. Ele não se apresenta como uma suíte de analytics de redes sociais, e o relatório não deve fingir que é.

## As chamadas de dados

Para o workspace de um cliente, o agente roda esta sequência. Os nomes são das ferramentas MCP reais; os equivalentes REST estão no [documento OpenAPI](https://app.shager.ai/api/v1/openapi.json).

1. `list_workspaces` para encontrar o workspace do cliente pelo nome.
2. `list_posts` com `status` igual a `PUBLISHED`, e depois de novo com `PARTIALLY_PUBLISHED` e `FAILED`. O `limit` vai até 100.
3. `get_post` para cada post da semana, para obter o estado por conta, as URLs publicadas e as mensagens de erro.
4. `get_analytics` com `from` e `to` cobrindo a semana.
5. `list_channels`, para associar os IDs dos canais a nomes de conta legíveis e identificar contas cujo status de conexão mudou.

A chamada de analytics via REST:

```bash
curl -s "https://app.shager.ai/api/v1/workspaces/ws_example/analytics?from=2026-09-14T00:00:00%2B03:00&to=2026-09-20T23:59:59%2B03:00" \
  -H "Authorization: Bearer $SHAGER_READ_KEY"
```

Dois detalhes dessa URL pegam muita gente. O `+` do offset precisa ser codificado como `%2B` numa query string, senão o servidor lê como espaço. E os limites da semana devem ser calculados no fuso horário do cliente, não no do servidor. Se `from` for omitido, `get_analytics` usa por padrão os últimos 30 dias, o que não é o que um relatório semanal quer.

## Cliques não são leads, então cruze os dados

O Shager dá a cada conta o próprio link curto e as próprias tags UTM, com `utm_content` identificando a conta. É isso que torna o cruzamento possível. O CRM registra os leads com os valores de UTM capturados no formulário da landing page; o agente os associa às contagens de cliques por conta do Shager pelo mesmo `utm_content`.

A tabela resultante é o coração do relatório:

| Conta | Posts | Cliques (Shager) | Leads (CRM) | Observação |
|---|---|---|---|---|
| Aurora Downtown | 4 | ... | ... | |
| Aurora Northside | 4 | ... | ... | precisa reconectar |

As diferenças entre as colunas já são informação. Muitos cliques e nenhum lead é um problema de landing page ou de oferta, e não de distribuição. Nosso guia sobre [atribuição de leads por conta](/en/blog/utm-per-account-lead-attribution) cobre os campos do formulário e o mapeamento no CRM que tornam a coluna de leads confiável, e [como medir os leads do conteúdo feito por agentes](/en/blog/measuring-leads-from-agent-content) cobre o lado do agente.

Se você não tem acesso ao CRM, o relatório funciona mesmo só com os cliques. Deixe isso claro no cabeçalho do relatório. Um relatório que chama cliques de "resultados" é o jeito como as agências perdem a confiança do cliente um trimestre depois.

## Rodando sem supervisão com o Claude Code

O Claude Code pode rodar de forma não interativa com `claude -p`, como descrito na [documentação do modo headless](https://code.claude.com/docs/en/headless). Isso transforma o relatório semanal num job do cron.

Primeiro, uma pasta de projeto para os relatórios, com um `.mcp.json` que lê a chave do ambiente. A [documentação de MCP](https://code.claude.com/docs/en/mcp) do Claude Code aceita expansão de `${VAR}` nos cabeçalhos:

```json
{
  "mcpServers": {
    "shager": {
      "type": "http",
      "url": "https://app.shager.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${SHAGER_READ_KEY}" }
    }
  }
}
```

Depois, as instruções, salvas como skill, para que a lógica fique num arquivo e não numa linha do crontab. O Claude Code carrega as skills do projeto a partir de `.claude/skills/<name>/SKILL.md`, segundo a [documentação de skills](https://code.claude.com/docs/en/skills):

```markdown
---
name: weekly-report
description: Compile the weekly distribution report for one client workspace from Shager. Use when asked for a weekly client report.
---

The argument is the client workspace name: $ARGUMENTS

1. Resolve the workspace with list_workspaces. Read its timezone.
2. Compute last Monday 00:00 to Sunday 23:59:59 in that timezone, with offsets.
3. Collect posts with list_posts (PUBLISHED, PARTIALLY_PUBLISHED, FAILED) and
   keep those published in the window. Call get_post for each.
4. Call get_analytics for the window. Map channel ids to names with list_channels.
5. If crm/<workspace>.csv exists, join leads on utm_content.
6. Write reports/<workspace>/<YYYY-MM-DD>.md with four sections: Delivery,
   Clicks by account, Clicks by post, Actions. Use tables. No adjectives about
   performance; numbers and one plain sentence per section.
7. Never call any tool that creates, schedules or cancels anything.
```

E o comando agendado, que pré-aprova só as ferramentas de leitura e a gravação de arquivos:

```bash
cd ~/agency-reports && claude -p "/weekly-report Aurora" \
  --allowedTools "mcp__shager__list_*,mcp__shager__get_*,mcp__shager__whoami,Write" \
  --output-format json > logs/aurora-$(date +%F).json
```

A sintaxe das regras de permissão com o prefixo `mcp__<server>__` e um curinga no final está documentada na [referência de permissões](https://code.claude.com/docs/en/permissions) do Claude Code. Nada que esteja fora dessa lista será aprovado automaticamente numa execução sem supervisão.

## Por que uma chave só de leitura importa aqui

A skill diz ao modelo para não escrever. A chave torna isso impossível. Crie no painel de agentes uma chave separada, só com o escopo `read`, para os relatórios, e não a use em mais nada. Se essa chave vazar um dia, o pior que pode acontecer é alguém ler contagens de cliques. Explicamos o modelo completo de escopos em [chaves de API, escopos e auditoria](/en/blog/api-keys-scopes-and-audit).

Cada chamada que o agente de relatórios faz também aparece no registro de auditoria desse painel, um bom jeito de confirmar, nas primeiras segundas-feiras, que ele chama o que você espera e nada mais.

## Escrevendo a parte em texto

Deixe o agente escrever uma ou duas frases por seção, mas com limites. Sem regras, os modelos descrevem uma variação de 4% como "um aumento significativo". Minha instrução é direta: diga o número, compare com a semana anterior se houver esse dado e não diga nada sobre a causa a menos que os dados mostrem. Se a página de uma filial não teve nenhum clique porque a conexão expirou na terça, essa é uma causa que os dados mostram. "Cansaço do público" não é.

## Perguntas frequentes

### O agente pode enviar o relatório direto para o cliente?

Pode, se você der a ele uma ferramenta de e-mail, mas eu não faria isso no primeiro dia. Peça que ele grave o arquivo, revise algumas semanas de resultados e só depois automatize o envio. O relatório é a forma como o cliente enxerga o seu trabalho, e um número errado enviado automaticamente custa mais do que o tempo economizado.

### O get_analytics inclui leads?

Não. Ele devolve os cliques nos links rastreáveis do Shager, por conta e por post, num intervalo de datas. Os leads vêm do CRM ou da ferramenta de formulários do cliente, associados pelo `utm_content`. O relatório deve manter as duas fontes visivelmente separadas.

### Até quando o relatório pode olhar para trás?

`get_analytics` aceita qualquer `from` e `to` que você enviar, com padrão dos últimos 30 dias quando `from` é omitido. Para comparações mês a mês, rode a mesma skill com outra janela, em vez de guardar relatórios antigos como fonte da verdade.

## Próximos passos

Se você ainda não tem uma chave, a [página para agentes](/en/agents) mostra como criar uma ou deixar um agente se cadastrar sozinho. Comece com um cliente, leia você mesmo os relatórios de três segundas-feiras e só então inclua os outros.

---
Source: https://shager.ai/pt/blog/weekly-client-report-by-agent