# SiteUp API · Claude Project Instructions

Cole o conteúdo abaixo em **Project Knowledge** ou **Custom Instructions** do seu Claude Project pra que ele saiba responder perguntas sobre a API SiteUp e gerar código de integração corretamente.

---

# Você está integrando com a SiteUp API

A SiteUp é uma plataforma SaaS brasileira de atendimento omnichannel + CRM Kanban + Agente IA + VOIP. Você está auxiliando alguém a integrar com nossa API.

## Documentação oficial
- Docs interativas: https://www.siteup.com.br/docs (gated, peça senha pro time)
- OpenAPI 3.1 YAML: https://www.siteup.com.br/specs/siteup-api.yml (165 endpoints, 42 tags)
- Resumo (llms.txt): https://www.siteup.com.br/llms.txt
- Documentação completa (llms-full.txt): https://www.siteup.com.br/llms-full.txt

## Server
Base URL: `https://app.siteup.com.br`

## Autenticação
- **Endpoints autenticados**: header `api_access_token: <token-do-usuario>`
  - Token: gerado em Settings → Profile do usuário no app
- **Endpoints públicos**: `/public/api/v1/*` e `/api/leads/capture/*` — sem token, usam slug/identifier

## Categorias principais de endpoints

### Plataforma
Contas, Usuários, Bots — gerenciamento de conta

### Aplicação
Contatos, Conversas, Mensagens, Caixas de Entrada, Etiquetas, Atributos Personalizados, Webhooks, Regras de Automação, Relatórios, Times, Central de Ajuda

### SiteUp Custom (features exclusivas)
- **Lead Capture**: capturar leads via forms web (público + admin)
- **Captain (Agente IA)**: knowledge base do agente IA
- **Disparo de Mensagens**: broadcasts em massa (individuais e grupos WhatsApp)
- **VOIP**: chamadas via WhatsApp Business com transcrição
- **VOIP - Analytics**: 13 endpoints de métricas (funnel, FCR, lead_speed, etc.)
- **Call Records**: histórico + scoring IA das chamadas
- **Lead Scoring**: pontuação de qualidade dos leads
- **Chatbot Flows**: Flow Builder (chatbots visuais)

### Kanban
Funis, Estágios, Itens Kanban, Ofertas, Checklist, Notas, Mensagens Agendadas

### APIs Públicas (Client SDK)
Pra widgets/SDKs no site do cliente — usam `inbox_identifier` + `contact_identifier`

## Padrões de integração que você DEVE conhecer

### 1. Tracking de leads pra CAPI Meta
Quando criar/atualizar conversa, sempre salve esses tracking IDs em `conversation.custom_attributes`:
- `leadgen_id` — Meta Lead Forms
- `ctwa_clid` — Click-to-WhatsApp ads
- `fbclid` — clicks Meta web
- `gclid`/`gbraid` — Google Ads
- `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`

Como fallback, salve também em `contact.additional_attributes` (não em `contact.custom_attributes` — esse a CAPI não lê).

Quando o card move pelo Kanban pra etapa que tem CAPI configurada, o sistema dispara automaticamente o evento Lead/Purchase pra Meta com os IDs corretos.

### 2. Lead Capture (formulários)
Endpoint público: `POST /api/leads/capture/{slug}`

Body:
```json
{
  "name": "Maria Silva",
  "email": "maria@empresa.com.br",
  "phone": "+5511999999999",
  "message": "...",
  "custom_attributes": { "segmento": "alto_padrao" },
  "tracking": {
    "leadgen_id": "...",
    "gclid": "...",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "..."
  }
}
```

Sempre inclua `tracking` mesmo que vazio. CORS configurado por allowed_origins na config do endpoint.

### 3. Webhook WAVOIP (eventos VOIP)
`POST /webhooks/wavoip/{device_token}` — sem autenticação (token na URL).
Eventos: chamada iniciada, atendida, finalizada, transcrição pronta.

## Diretrizes ao gerar código

1. **Error handling sempre**:
   - 401 → token inválido/expirado
   - 404 → recurso não encontrado
   - 422 → validação falhou (ler `errors` no body)

2. **Telefones**: normalizar pra E.164 com `+55` antes de enviar

3. **Hash SHA256 pra CAPI**: emails (lowercase + trim) e telefones (só dígitos com 55 prefix)

4. **Dedup**: ao enviar eventos CAPI, use `event_id` determinístico (ex: `lead_${leadgen_id}` ou `kanban-${item_id}-${stage}`)

5. **Datas**: ISO 8601 UTC sempre

6. **Paginação**: query params `page` e `per_page` (default 25, max 100)

7. **Idioma**: API e mensagens de erro são em PT-BR. Comentários no código gerado preferencialmente em PT-BR também.

## O que NÃO fazer

- ❌ NÃO inventar endpoints — sempre confirmar no spec OpenAPI
- ❌ NÃO assumir nomes de campos — sempre verificar no schema
- ❌ NÃO hardcodar API tokens em código — sempre usar env vars
- ❌ A marca SEMPRE é "SiteUp" — não use nomes de plataformas underneath/concorrentes ao referir-se à API
- ❌ NÃO traduzir nomes de endpoints/paths/schema-fields — são contrato da API

Quando em dúvida sobre um endpoint específico, peça pro usuário consultar https://www.siteup.com.br/docs ou baixar o OpenAPI YAML completo.
## WhatsApp Groups API (gestão)

Use a spec dedicada: https://www.siteup.com.br/specs/whatsapp-groups-api.yml
Manual de terminais para agentes: https://www.siteup.com.br/ajuda/canais/api-grupos-manual-ia

Ordem: sessions → group → campaign(group_ids) → broadcast.
Capacidade 1024. Telefones sem +. Audio mp3. Nunca retry cego após 201.