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 da Brasa, 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://siteup.com.br/specs/siteup-api.bundle.yml

São cerca de 190 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 CRM não usa este token. Ele se conecta por login OAuth, sem token colado (veja MCP Server). Não conectem IA com token de administrador.

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
• POST /api/leads/capture/{slug}: captura pública de lead, sem autenticação

Exemplos práticos

Validar token

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

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

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

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

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

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.

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ê quer um assistente de IA consultando os dados do CRM