# API de Resumos

Estão disponíveis dois tipos de resumos escritos por IA através da API:

- **Resumos de chat** — uma breve recapitulação da conversa de um contacto, gerada a pedido. É a mesma funcionalidade que o controlo de resumo num chat (ver [Resumo de Chat](../chats/chat-interface.md#chat-summary)).
- **Resumos diários** — o resumo diário de todas as suas conversas que os [Resumos Diários](../daily-summaries/daily-summaries.md) criam todas as manhãs: estatísticas, um bloco markdown por secção e quaisquer tarefas que a IA tenha criado a partir dele.

- **URL Base** — `https://api.dmchamp.com/v1`
- **Autenticação** — a sua chave de API (ver [Autenticação](authentication.md)). Uma [chave com âmbito definido](api-keys.md#scoped-keys) necessita da secção `Summaries`.
- **Erros e paginação** — ver [Erros e Paginação](errors-and-pagination.md)

Todos os exemplos abaixo mostram o formato de consulta `?apiKey=` em cURL e o cabeçalho `X-API-Key` em JavaScript e Python — qualquer um funciona em todos os endpoints.

---

## Gerar um resumo de chat

`POST /summaries` — envie o `phoneNumber` do contacto (com código de país) ou o `email`; um dos dois é obrigatório.

A IA lê a conversa mais recentemente **fechada** do contacto, ou a que ainda está aberta caso nenhuma tenha sido fechada, e escreve uma recapitulação da mesma. A recapitulação é guardada no contacto (aparece em **Resumos** no painel do contacto na aplicação) e devolvida na resposta, para que a possa reencaminhar diretamente para um CRM, um canal do Slack ou um e-mail.

**Custo:** o mesmo que uma resposta de IA no nível de Qualidade de IA do Agente — Pro 1 crédito, Max 0,25, Mini 0,15; com a sua própria chave Anthropic ligada, o Pro custa 0. O pedido é recusado antes de qualquer geração se o saldo não for suficiente.

**cURL**

```bash
curl -X POST "https://api.dmchamp.com/v1/summaries?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+31612345678"}'
```

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.com/v1/summaries", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ email: "jane@example.com" }),
});
const { summary } = await res.json();
```

**Python**

```python
import requests

r = requests.post(
    "https://api.dmchamp.com/v1/summaries",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phoneNumber": "+31612345678"},
)
print(r.json()["summary"])
```

**Resposta**

```json
{
  "success": true,
  "message": "Chat summary generated successfully",
  "summary": "Jane asked about the 10-session package for her two children (ages 6 and 9) and preferred Saturday mornings. She booked a trial lesson for Saturday at 10:00 and wants to know whether siblings get a discount."
}
```

| Estado | Significado |
|---|---|
| `400` | Nem `phoneNumber` nem `email` foram enviados. |
| `404` | Nenhum contacto corresponde, o contacto ainda não tem conversas ou a conversa não tem mensagens. O `message` do corpo indica qual. |
| `500` | A geração falhou (por exemplo, saldo de créditos insuficiente). |

> **Receita de automatização: e-mail de marcação com recapitulação.** Numa [automatização](../automations/automations.md) no gatilho **Marcação efetuada**, adicione um passo de **Pedido HTTP** que chame este endpoint com `${trigger.contact.phone_number}` (ou o e-mail do contacto), seguido de um passo de **E-mail** que insira o `summary` da resposta do passo HTTP, juntamente com uma ligação para o chat (o endereço da sua aplicação seguido de `/chats/` e o ID do contacto do gatilho). A sua equipa recebe o contexto da marcação no mesmo e-mail, sem ter de abrir a caixa de entrada.

> **Ler resumos guardados.** Não existe um endpoint que liste os resumos de chat guardados. Guarde o texto da resposta se precisar dele mais tarde, ou gere-o novamente (cada chamada é faturada).

### Alternativa: por ID de contacto

`POST /summaries/chat-summary` com `{"contactId": "..."}` efetua a mesma geração para um contacto cujo ID já possui. Apenas confirma o sucesso (`{"success": true, "data": "Chat summary generated successfully"}`) e **não** devolve o texto, por isso utilize `POST /summaries` quando pretender a recapitulação propriamente dita. Um membro da equipa cuja chave esteja limitada aos seus contactos atribuídos receberá `404` para um contacto fora desse âmbito.

---

## Obter um resumo diário

`GET /summaries/daily/{date}` — `date` é `YYYY-MM-DD`. Devolve o resumo para esse dia, ou `null` em `summary` quando ainda não foi gerado nenhum, além da configuração da sua secção.

**cURL**

```bash
curl "https://api.dmchamp.com/v1/summaries/daily/2026-09-08?apiKey=YOUR_API_KEY"
```

**Resposta**

```json
{
  "success": true,
  "data": {
    "summary": {
      "date": "2026-09-08",
      "status": "completed",
      "generated_at": "2026-09-09T05:02:11.000Z",
      "stats": {
        "total_conversations": 42,
        "total_messages_sent": 310,
        "total_messages_received": 268,
        "human_alerts": 3,
        "bookings": 5,
        "new_contacts": 11,
        "sales": 2
      },
      "sections": {
        "wins_losses_improvements": "## Wins\n- ...",
        "tasks_action_items": "- Call Jane back about the sibling discount",
        "human_alerts_reviews": "...",
        "sentiment_analysis": "...",
        "booked_meetings_sales": "..."
      },
      "contact_map": { "Jane Doe": "uid_whatsapp_31612345678" },
      "auto_tasks": [],
      "created_task_ids": []
    },
    "section_configs": [
      { "id": "wins_losses_improvements", "name": "Wins, Losses & Improvements", "enabled": true, "position": 0 }
    ]
  }
}
```

- **`status`** — `pending`, `generating`, `completed` ou `failed` (com `error` definido). Consulte este endpoint após uma regeneração até que indique `completed`.
- **`sections`** — uma string markdown por secção, identificada pelo ID da secção. As cinco secções padrão são `wins_losses_improvements`, `tasks_action_items`, `human_alerts_reviews`, `sentiment_analysis` e `booked_meetings_sales`; as secções que adicionar em **Configurar** na página de Resumos Diários recebem um ID `custom_…`. Os nomes e a ordem são repetidos em `section_configs`.
- **`contact_map`** — nome de visualização para ID de contacto, para que possa transformar os nomes no texto em hiperligações.
- **`auto_tasks`** / **`created_task_ids`** — os itens de ação que a IA extraiu e as tarefas que criou a partir deles (quando **Criar cartões de tarefa a partir de itens de ação** está ativado).

| Estado | Significado |
|---|---|
| `400` | `date` não está `YYYY-MM-DD`, ou é no futuro. |
| `403` | Os Resumos Diários estão desativados para a conta. |

> Prefere um push em vez de consulta (polling)? O [evento de webhook](../integrations/webhooks.md) **Resumo Diário Criado** entrega o mesmo payload no momento em que um resumo matinal termina.

---

## Regenerar um resumo diário

`POST /summaries/daily/{date}/regenerate` — inicia uma nova geração para esse dia em segundo plano e retorna imediatamente com `status: "generating"` e `sections` vazio. Consulte `GET /summaries/daily/{date}` até que esteja concluído. Aplicam-se as mesmas regras que para a ligação **Tentar novamente** na aplicação.

O corpo opcional `{"deleteTasks": false}` mantém as tarefas que a execução anterior criou; por predefinição, são eliminadas e recriadas a partir do novo resumo. Envie um booleano real — a string `"false"` é ignorada e tratada como a predefinição.

```bash
curl -X POST "https://api.dmchamp.com/v1/summaries/daily/2026-09-08/regenerate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deleteTasks": false}'
```

---

## Referência rápida

| Tarefa | Endpoint |
|---|---|
| Gerar um resumo de chat e obter o texto | `POST /summaries` |
| Gerar um resumo de chat por ID de contacto (sem retorno de texto) | `POST /summaries/chat-summary` |
| Ler o resumo de um dia | `GET /summaries/daily/{date}` |
| Regenerar o resumo de um dia | `POST /summaries/daily/{date}/regenerate` |