# Sábio Adv API — Documentação completa (LLM-friendly)

> Versão expandida em Markdown puro otimizada para ingestão por modelos de linguagem (Perplexity, Claude, ChatGPT, Gemini, Cursor). Contém **toda** a referência da API REST pública da plataforma Sábio Adv — CRM jurídico, WhatsApp oficial (Meta Cloud API) e gestão de leads para escritórios de advocacia brasileiros.

- **Produto**: Sábio Adv — SaaS jurídica brasileira com IA conversacional, CRM, WhatsApp oficial Meta + Uazapi, follow-up automatizado, monitoramento de processos.
- **Base URL**: `https://api.sabioadv.com`
- **Documentação interativa**: https://plataforma.sabioadv.com.br/api-docs
- **OpenAPI 3.1**: https://plataforma.sabioadv.com.br/openapi.json
- **Site institucional**: https://sabioadv.com.br

---

## Autenticação

Todas as chamadas exigem header HTTP:

```
Authorization: Bearer <SUA_API_KEY>
Content-Type: application/json
```

- A API key é **única por usuário** e gerada em **Conta → API** dentro da plataforma.
- Resolve automaticamente WABA, `phone_number_id`, empresa e funil padrão associados ao perfil.
- Sem expiração — pode ser revogada e regerada na mesma tela.

---

## Endpoint 1 — Enviar mensagem WhatsApp

`POST /functions/v1/send-message-api`

Endpoint unificado para envio de mensagens WhatsApp via Meta Cloud API com fallback automático para Uazapi quando a janela de 24 horas da Meta expira. Suporta três modos via campo `type`:

### Modo 1: Texto livre (`type: "text"`)

Use quando há janela 24h aberta (cliente respondeu nas últimas 24h).

**Request:**

```json
{
  "type": "text",
  "contato": "5511999998888",
  "content_text": "Olá! Recebemos seu contato e em breve responderemos.",
  "keep_ai_active": false
}
```

**Campos:**

- `contato` (string, obrigatório): número do destinatário no formato `55DDDNNNNNNNNN` (apenas dígitos, com DDI 55).
- `content_text` (string, obrigatório): texto da mensagem. Suporta emojis e formatação WhatsApp (`*negrito*`, `_itálico_`, `~riscado~`, ` ``` `monospace` ``` `).
- `keep_ai_active` (boolean, default `false`): se `false`, marca a thread como `inativa` após envio (recomendado para integrações externas que controlam a conversa).

### Modo 2: Template oficial Meta (`type: "template"`)

Use para reativar conversas **fora** da janela 24h. Templates precisam estar aprovados pela Meta.

**Request:**

```json
{
  "type": "template",
  "contato": "5511999998888",
  "template_name": "boas_vindas_v2",
  "language": "pt_BR",
  "parameters": ["João", "Direito Trabalhista"],
  "keep_ai_active": false
}
```

**Campos:**

- `template_name` (string, obrigatório): nome exato do template aprovado.
- `language` (string, obrigatório): código do idioma (`pt_BR`, `en_US`, etc).
- `parameters` (array de strings, opcional): valores das variáveis `{{1}}`, `{{2}}`, etc., na ordem.

### Modo 3: Listar templates aprovados (`type: "list_templates"`)

Retorna todos os templates aprovados da conta WABA, com componentes e parâmetros.

**Request:**

```json
{ "type": "list_templates" }
```

**Response (exemplo):**

```json
{
  "success": true,
  "templates": [
    {
      "name": "boas_vindas_v2",
      "language": "pt_BR",
      "status": "APPROVED",
      "category": "UTILITY",
      "components": [
        { "type": "BODY", "text": "Olá {{1}}, recebemos seu pedido sobre {{2}}." }
      ]
    }
  ]
}
```

### Response geral

```json
{
  "success": true,
  "message": "Mensagem enviada",
  "data": { "wamid": "wamid.HBgL..." }
}
```

### Códigos de erro

- `400`: parâmetros inválidos (ex: `contato` malformado).
- `401`: API key ausente ou inválida.
- `404`: WABA não configurado para este usuário.
- `500`: erro interno (consultar logs).

### Exemplo cURL

```bash
curl -X POST https://api.sabioadv.com/functions/v1/send-message-api \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contato":"5511999998888","content_text":"Olá! Em breve responderemos."}'
```

---

## Endpoint 2 — Criar lead no CRM

`POST /functions/v1/create-lead-api`

Cria um novo lead no CRM da empresa. Se já existir lead com o mesmo `contato` (telefone normalizado), faz **merge automático** preservando histórico e thread existentes.

**Request completo:**

```json
{
  "nome": "Maria Souza",
  "contato": "5511988887777",
  "origem": "Google Ads - Previdenciário",
  "custom_column_id": "aaaa-bbbb-cccc-dddd",
  "descricao": "Quer revisar benefício do INSS",
  "tags": ["Previdenciário", "Aposentadoria"],
  "agendamento": {
    "data_hora": "2026-06-15T10:00:00-03:00",
    "link": "https://meet.google.com/xyz-abcd-efg"
  }
}
```

**Campos:**

- `nome` (string, obrigatório): nome do lead.
- `contato` (string, obrigatório): telefone com DDI+DDD+número. Normalizado para `55DDDNNNNNNNNN`.
- `origem` (string, opcional): canal de origem (Site, Google Ads, Facebook, etc.).
- `custom_column_id` (uuid, opcional): coluna do funil. Consulte via `get-funnels-api`.
- `descricao` (string, opcional): contexto adicional do lead.
- `tags` (array, opcional): IDs (uuid) **ou** nomes. Nomes inexistentes são criados como `company_tags`.
- `agendamento.data_hora` (ISO 8601 com timezone): cria evento vinculado.
- `agendamento.link` (string): link de reunião (Meet, Zoom, etc.).

**Response:**

```json
{
  "success": true,
  "lead_id": "uuid-do-lead",
  "merged": false
}
```

### Códigos de erro

- `400`: `nome` ou `contato` ausentes/inválidos.
- `401`: API key inválida.

---

## Endpoint 3 — Atualizar nome de contato

`POST /functions/v1/update-contact-name`

Atualiza o `nome` de um lead existente identificado por telefone. Útil para enriquecer cadastros vindos de canais anônimos (WhatsApp sem nome salvo) após qualificação.

O telefone é normalizado e busca variantes com/sem nono dígito (móveis BR).

**Request:**

```json
{
  "contato": "5511999998888",
  "nome": "João da Silva"
}
```

**Response:**

```json
{ "success": true, "message": "Nome atualizado" }
```

**Erros:**

- `401`: API key inválida.
- `404`: contato não encontrado.

---

## Endpoint 4 — Listar funis e colunas

`POST /functions/v1/get-funnels-api`

Retorna todos os funis da empresa associada à API key, com colunas. Use os IDs para movimentar leads programaticamente via `create-lead-api` (`custom_column_id`).

**Request:** body vazio (`{}`), auth via header apenas.

**Response:**

```json
{
  "success": true,
  "funnels": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "name": "Funil Principal",
      "is_default": true,
      "columns": [
        { "id": "aaaa-bbbb-cccc-dddd", "name": "Novo Lead", "position": 0 },
        { "id": "eeee-ffff-gggg-hhhh", "name": "Em Atendimento", "position": 1 },
        { "id": "iiii-jjjj-kkkk-llll", "name": "Convertido", "position": 2 }
      ]
    }
  ]
}
```

---

## Endpoint 5 — Listar leads

`POST /functions/v1/list-leads-api`

Lista leads da empresa com paginação e filtros. Body opcional:

```json
{ "limit": 50, "offset": 0, "custom_column_id": "uuid", "status": "ativo", "search": "Maria" }
```

Retorna `{ success, total, limit, offset, leads: [...] }`. Cada lead inclui `tags`.

---

## Endpoint 6 — Obter lead (por id ou telefone)

`POST /functions/v1/get-lead-api`

```json
{ "lead_id": "uuid" }
```

ou

```json
{ "contato": "5511999998888" }
```

Resposta inclui `lead` completo com `tags` e `agendamentos`. Normaliza nono dígito BR. `404` quando não encontrado.

---

## Endpoint 7 — Listar tags

`POST /functions/v1/list-tags-api`

Sem body. Retorna `{ success, tags: [{ id, name, color, created_at }] }` ordenadas por nome.

---

## Endpoint 8 — Listar conversa (mensagens por telefone ou lead)

`POST /functions/v1/list-conversations-api`

```json
{ "contato": "5511999998888", "limit": 200 }
```

ou

```json
{ "lead_id": "uuid", "limit": 200 }
```

Retorna mensagens mescladas de `whatsapp_official_messages` (Meta) e `whatsapp_uazapi_messages` (Uazapi), normalizadas no formato:

```json
{
  "id": "...", "source": "meta_official|uazapi",
  "message_id": "...", "from_number": "...", "to_number": "...",
  "is_from_me": false, "type": "text", "text": "...", "file_url": null,
  "timestamp": "ISO", "delivery_status": "delivered"
}
```

Ordenadas por timestamp ascendente. `lead` pode ser `null` se telefone não tem lead no CRM. `400` quando ambos parâmetros ausentes.

---

## Endpoint 9 — Adicionar tag a um lead

`POST /functions/v1/add-tag-to-lead-api`

```json
{ "lead_id": "uuid", "tag": "Urgente" }
```

`tag` aceita UUID ou nome. Nomes inexistentes são criados como `company_tags`. Idempotente (vínculos duplicados ignorados).

Resposta: `{ success, lead_id, tag_id }`.

---

## Endpoint 10 — Mover lead para coluna do funil

`POST /functions/v1/move-lead-column-api`

```json
{ "lead_id": "uuid", "custom_column_id": "uuid" }
```

Valida que a coluna pertence à mesma empresa. Atualiza `custom_funnel_id` automaticamente quando a coluna está em outro funil. `403` quando ownership falha.

---

## Glossário

- **WABA** (WhatsApp Business Account): conta business oficial Meta vinculada ao número.
- **Phone Number ID**: identificador Meta do número WhatsApp business.
- **Janela 24h**: período em que mensagens livres podem ser enviadas após resposta do cliente. Fora dela, só templates aprovados.
- **Template Meta**: mensagem pré-aprovada pela Meta com variáveis `{{N}}`.
- **Fallback Uazapi**: rota não-oficial usada quando Meta bloqueia (fora janela 24h sem template adequado).
- **Funil**: pipeline de vendas com colunas (estágios). Cada empresa pode ter múltiplos.
- **Coluna (custom_column)**: estágio dentro de um funil.
- **Tag (company_tag)**: rótulo classificador de leads, criável dinamicamente.
- **Thread (chat_thread)**: agrupamento de mensagens de uma conversa com `status` (ativa/inativa) que controla se a IA responde.
- **Lead**: contato no CRM com histórico, tags, agendamentos e thread WhatsApp opcional.
- **API key**: token Bearer único por usuário, gerado em Conta → API.

---

## Casos de uso típicos

1. **Formulário do site → WhatsApp**: form envia POST para `create-lead-api` com `nome`+`contato`+tag "Site", depois POST para `send-message-api` (template `boas_vindas_v2`) para reativar conversa.
2. **CRM externo (HubSpot/Pipedrive) → Sábio Adv**: webhook bidirecional sincroniza leads via `create-lead-api` (merge automático evita duplicidade).
3. **Agente de IA (n8n/Make/Zapier)**: agente lê WhatsApp e responde via `send-message-api` com `keep_ai_active: false` para evitar conflito com IA nativa.
4. **Disparo em massa de reativação**: loop por leads frios chamando `send-message-api` com template aprovado, respeitando limite Meta.
5. **Enriquecimento pós-qualificação**: após coletar nome do cliente, `update-contact-name` atualiza o cadastro.

---

## Limites e SLA

- Sem rate limit hard de requisições.
- Sujeito ao **saldo de mensagens** da assinatura Asaas (R$ 997 base + R$ 1 por processo monitorado).
- Mensagens persistidas em `whatsapp_official_messages` para visibilidade no Multiatendimento.
- Fallback automático Meta → Uazapi quando janela 24h expira (sem ação manual).
- Webhooks de recebimento configurados via plataforma (não cobertos por esta API pública).

---

## Suporte

- Plataforma: https://plataforma.sabioadv.com.br
- Site: https://sabioadv.com.br
- Documentação interativa: https://plataforma.sabioadv.com.br/api-docs

---

## MCP Server (Model Context Protocol)

A Sábio Adv expõe um servidor MCP oficial que disponibiliza as 10 APIs públicas como tools nativas para Claude Desktop, Cursor, ChatGPT Desktop, Windsurf, Cline e qualquer cliente MCP compatível.

- **URL**: `https://oavhtlipjwctndgqdtdd.supabase.co/functions/v1/mcp-server`
- **Transport**: Streamable HTTP (MCP spec 2025-03-26)
- **Auth**: `Authorization: Bearer SUA_API_KEY` (mesma api_key das APIs REST, gerada em Conta → API)
- **Documentação**: https://plataforma.sabioadv.com.br/api-docs/mcp

### Configuração — Claude Desktop / Cursor

```json
{
  "mcpServers": {
    "sabio-adv": {
      "url": "https://oavhtlipjwctndgqdtdd.supabase.co/functions/v1/mcp-server",
      "headers": { "Authorization": "Bearer SUA_API_KEY" }
    }
  }
}
```

### Tools expostas

`send_message`, `create_lead`, `update_contact_name`, `get_funnels`, `list_leads`, `get_lead`, `list_tags`, `list_conversations`, `add_tag_to_lead`, `move_lead_column` — uma para cada endpoint REST documentado acima. Os JSON Schemas das tools espelham exatamente os payloads das APIs.

### Quando usar MCP vs REST

- **MCP**: quando o consumidor é um assistente de IA (Claude, Cursor, etc.) e você quer que o próprio LLM escolha e chame as ferramentas.
- **REST**: quando há código tradicional (backend, n8n, Make, scripts) integrando.