API REST: autenticação e primeiros passos

A API REST do SiteUp expõe os recursos da plataforma, conversas, mensagens, contatos, atendentes, equipes, caixas de entrada, funis e cards do kanban, etiquetas, atributos customizados, integrações, formulários de captura, registros de chamadas VOIP, knowledge base do Capitão IA, entre outros. Esta página cobre o essencial para começar: host, autenticação, estrutura das URLs e onde encontrar a especificação completa.

Especificação oficial

A API é descrita em OpenAPI 3.1, disponível publicamente em:

https://app.siteup.com.br/specs/siteup-api.yml

São cerca de 167 paths agrupados por tags funcionais (Conversations, Contacts, Messages, Inboxes, Teams, Agents, Custom Attributes, Webhooks, Reports, Kanban, Funnels, VOIP, AI Agent, entre outras). O YAML pode ser importado em ferramentas como Insomnia, Postman, Bruno, Stoplight, ou usado para gerar clientes tipados com openapi-generator e openapi-typescript.

Host

Todas as chamadas vão para o host único de produção:

https://app.siteup.com.br

Não há host de homologação público, para testes não-destrutivos, recomenda-se uma conta dedicada dentro do mesmo host.

Gerando seu token

Cada usuário possui o seu próprio token de acesso, com escopo idêntico ao do papel do usuário no painel.

1. Acesse Perfil → Tokens de acesso
2. Copie o valor do token exibido (é gerado automaticamente quando o usuário é criado)
3. Armazene em variável de ambiente; nunca faça commit do valor literal

Quando o usuário é desativado ou tem o papel alterado, o token segue o novo escopo automaticamente. Para revogar, basta desativar o usuário ou regenerar o token.

Atenção: o api_access_token concede acesso completo aos recursos visíveis ao usuário. Não exponha o token em código frontend, repositórios públicos ou logs.

Autenticação

Toda requisição autenticada deve incluir o header:

api_access_token: SEU_TOKEN_AQUI

Sem o header (ou com token inválido), a resposta é 401 Unauthorized.

Observação: o servidor MCP do SiteUp aceita o mesmo valor de token, mas via header Authorization: Bearer .... Para a API REST tradicional, use sempre api_access_token.

Estrutura das URLs

A maior parte dos recursos é escopada por conta:

https://app.siteup.com.br/api/v1/accounts/{account_id}/{recurso}

O account_id é numérico e aparece na URL do painel quando o usuário está logado (ex.: app.siteup.com.br/app/accounts/142/...).

Existem também endpoints sem escopo de conta, como:

• GET /api/v1/profile, perfil do usuário do token (também usado pelo MCP para validar autenticação)
• POST /api/leads/capture/{slug}: captura pública de lead, sem autenticação

Exemplos práticos

Validar token

bash curl -X GET \ "https://app.siteup.com.br/api/v1/profile" \ -H "api_access_token: $SITEUP_TOKEN"

Resposta 200 com o JSON do perfil indica token válido.

Listar conversas abertas

bash curl -X GET \ "https://app.siteup.com.br/api/v1/accounts/142/conversations?status=open&page=1" \ -H "api_access_token: $SITEUP_TOKEN"

Buscar contato

bash curl -X GET \ "https://app.siteup.com.br/api/v1/accounts/142/contacts/search?q=%2B5511999998888" \ -H "api_access_token: $SITEUP_TOKEN"

Enviar mensagem outbound

bash curl -X POST \ "https://app.siteup.com.br/api/v1/accounts/142/conversations/5821/messages" \ -H "api_access_token: $SITEUP_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "content": "Olá! Recebi sua mensagem e já estou avaliando.", "message_type": "outgoing" }'

Para enviar uma nota interna (visível apenas a atendentes), use "message_type": "private".

Criar contato com atributos customizados e tracking

bash curl -X POST \ "https://app.siteup.com.br/api/v1/accounts/142/contacts" \ -H "api_access_token: $SITEUP_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "inbox_id": 12, "name": "Maria Silva", "phone_number": "+5511999998888", "email": "[email protected]", "custom_attributes": { "origem": "google-ads" }, "additional_attributes": { "ctwa_clid": "ARABCdefGhi...", "leadgen_id": "1234567890" } }'

custom_attributes armazena dados de negócio configuráveis pelo usuário. additional_attributes é o local recomendado para identificadores de tracking de mídia paga (ctwa_clid, leadgen_id, fbclid, gclid) que alimentam a integração CAPI/Conversions API.

Mover card no kanban

bash curl -X PUT \ "https://app.siteup.com.br/api/v1/accounts/142/kanban_items/9981" \ -H "api_access_token: $SITEUP_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "funnel_stage": "Fechamento" }'

Paginação

Endpoints de listagem retornam dados paginados com o parâmetro page. As respostas seguem o padrão da especificação OpenAPI, geralmente um envelope com data e meta (current_page, total_pages, total_count). Consulte o YAML para o schema exato de cada endpoint.

bash curl "https://app.siteup.com.br/api/v1/accounts/142/conversations?page=2" \ -H "api_access_token: $SITEUP_TOKEN"

Status codes mais comuns

Erros retornam corpo JSON com a descrição do problema sempre que possível.

Boas práticas

• Use variáveis de ambiente ou um cofre (Vault, Doppler, AWS Secrets Manager) para o token.
• Gere clientes a partir do OpenAPI (openapi-generator-cli, openapi-typescript), economiza tempo e elimina divergências de tipo.
• Trate 429 com backoff exponencial e jitter; respeite o header Retry-After quando presente.
• Cacheie GETs idempotentes (atendentes, equipes, caixas, atributos custom) para reduzir tráfego.
• Logue identificadores de correlação (header de resposta X-Request-Id, quando presente) para acelerar tickets de suporte.

Próximos passos

• Webhooks customizados, receber eventos da plataforma em tempo real
• MCP Server, quando você prefere agentes IA usando a API por você