# SiteUp API · Cursor Rules

Cole esse conteúdo num arquivo `.cursorrules` (ou `.cursor/rules/siteup-api.md`) na raiz do seu projeto pra que o Cursor entenda a API SiteUp ao gerar código.

---

# SiteUp API Integration Guide

You are working with the SiteUp API. Reference docs: https://www.siteup.com.br/docs

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

## Authentication
- Maioria dos endpoints: header `api_access_token: <token-do-usuario>`
- Endpoints públicos (`/public/api/v1/*` e `/api/leads/capture/*`): sem auth — usam slug/identifier

## Convenções da API
- Todos os endpoints retornam JSON
- Datas em ISO 8601 UTC
- Telefones no formato E.164 com `+55` pra Brasil
- IDs são integers exceto onde indicado (uuid em alguns casos)
- Custom attributes da CONVERSA (não do contato) são onde tracking IDs como `leadgen_id`, `ctwa_clid`, `fbclid`, `gclid`, `utm_*` devem ser salvos pra integração CAPI Meta funcionar
- Tracking auxiliar do contato vai em `additional_attributes` (não `custom_attributes`)

## Padrões importantes

### Lead Capture (formulários web)
- POST público: `/api/leads/capture/{slug}` — recebe submissão
- Pra integradores: salvar `leadgen_id` em `conversation.custom_attributes` e `contact.additional_attributes` (ambos)
- O `tracking` no body deve incluir todos os IDs disponíveis (gclid, fbclid, utm_*)

### CAPI Meta (Meta Conversions API)
- Disparado automaticamente quando card move pelo Kanban
- Lê `leadgen_id`, `ctwa_clid`, `fbclid` da conversa/contato pra atribuição
- Configurado por funil em settings.meta_capi (pixel_id, access_token)

### Kanban Items
- Estrutura: funnel > stages > kanban_items
- `funnel_stage` indica posição atual do item
- `item_details.value` é usado pelo CAPI como valor de Purchase

### VOIP
- Chamadas: POST `/api/v1/accounts/{id}/conversations/{cid}/voip_calls`
- Webhook recebe eventos em `/webhooks/wavoip/{device_token}`
- Analytics: 13+ endpoints em `/voip_analytics/*`

### Captain (Agente IA)
- Knowledge base: `/api/v1/accounts/{id}/ai_agent_documents` (CRUD)
- Tipos: file (PDF), url, text

## Quando gerar código de integração
1. Sempre incluir error handling (401 = token errado, 404 = recurso não existe)
2. Hash SHA256 de email/telefone normalizado pra dados pessoais quando enviar pra CAPI
3. Usar `event_id` determinístico pra deduplicação em CAPI
4. Pra forms públicos, sempre passar `tracking` mesmo que vazio

## Recursos adicionais
- OpenAPI spec: https://www.siteup.com.br/specs/siteup-api.yml
- llms.txt (índice): https://www.siteup.com.br/llms.txt
- llms-full.txt (verbose): https://www.siteup.com.br/llms-full.txt
- Postman: https://www.siteup.com.br/specs/siteup-api.postman.json
## WhatsApp Groups (Gestão) — 2026-08

- Spec: https://www.siteup.com.br/specs/whatsapp-groups-api.yml
- Manual IA: https://www.siteup.com.br/ajuda/canais/api-grupos-manual-ia
- Ajuda: https://www.siteup.com.br/ajuda/canais/gestao-grupos-whatsapp
- Auth: `api_access_token`
- Fluxo: WAHA sessions → create group → create campaign (group_ids) → broadcast
- Audio: mp3; no audio caption; capacity 1024; phones without +
- Do not blind-retry after HTTP 201