Endpoints da API

Zenovay oferece vários grupos de endpoints de API para acessar seus dados de análise programaticamente.

Autenticação

Todas as solicitações de API requerem autenticação. O método depende de qual API você usa:

Consulte Autenticação para detalhes sobre gerenciamento de chaves de API.

API Externa

URL base: https://api.zenovay.com/api/external/v1

API do lado do servidor para acessar dados de análise com autenticação de chave de API (header X-API-Key).

Endpoints Disponíveis

Cada endpoint tem uma página de referência dedicada com parâmetros, esquemas de resposta, interfaces TypeScript e exemplos de código em cURL, JavaScript, Python e TypeScript.

Consulte também a visão geral da API Externa para uma introdução de alto nível.

Widgets Incorporáveis

URL base: https://api.zenovay.com/widgets

Widgets prontos para usar que não requerem autenticação. Use seu código de rastreamento para identificar o site.

Consulte Widgets para exemplos de incorporação.

Dados em Tempo Real

URL base: https://api.zenovay.com/e

Endpoints JSON públicos para estatísticas ao vivo. Nenhuma autenticação necessária.

Consulte Dados em Tempo Real para guias de integração.

Limites de Taxa

Os limites de taxa da API variam por plano:

Os headers de limite de taxa são incluídos em todas as respostas:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1642771200

O valor X-RateLimit-Limit reflete o limite por minuto do seu plano (por exemplo, 10 para Free, 30 para Pro, 60 para Scale, 120 para Enterprise).

Consulte Limites de Taxa para detalhes sobre como lidar com erros de limite de taxa.

Códigos de Erro

{
"success": true,
"data": { ... },
"timestamp": "2026-02-07T12:00:00.000Z"
}

{
"success": false,
"error": {
  "message": "The provided API key is missing or invalid",
  "code": "UNAUTHORIZED",
  "timestamp": "2026-02-07T12:00:00.000Z"
}
}

Webhooks

Configure webhooks para receber notificações em tempo real:

Eventos Disponíveis

• visitor.identified - Quando um visitante é identificado
• visitor.high_value - Quando a pontuação de visitante atinge 80+
• event.tracked - Quando qualquer evento é rastreado
• goal.completed - Quando uma meta é concluída
• visitor.converted - Quando um visitante se converte

Payload do Webhook

{
"event": "visitor.high_value",
"timestamp": "2025-01-20T15:30:00Z",
"data": {
  "visitor_id": "vis_abc123",
  "score": 92,
  "current_page": "/pricing",
  "time_on_site": 420
}
}

Visão Geral da Dashboard API

Os seguintes grupos de API alimentam o painel Zenovay. Todos os endpoints requerem um token JWT Bearer no header Authorization. As respostas usam um envelope padrão:

{ "success": true, "data": { ... }, "timestamp": "..." }

Permissões Baseadas em Função

Os endpoints da API de Configurações do Site aplicam acesso baseado em função. Funções em ordem de privilégio:

API de Conversas

URL base: https://api.zenovay.com/api/conversations

Autenticação: Bearer JWT obrigatório. Associação à equipe verificada para todas as solicitações.

Operações CRUD para conversas alimentadas por IA dentro de equipes. O parâmetro de consulta team_id padrão para a organização do usuário autenticado, se não fornecido.

Endpoints

GET /conversations

Retorna conversas sem conteúdo de mensagem para desempenho.

Parâmetros de consulta:

• team_id (opcional) — padrão para a organização do usuário

{
"success": true,
"data": [
  {
    "id": "uuid",
    "team_id": "uuid",
    "title": "Analytics Q3 review",
    "created_at": "2026-02-01T10:00:00Z",
    "updated_at": "2026-02-07T14:30:00Z"
  }
]
}

GET /conversations/:id

Retorna a conversa completa incluindo o array de mensagens.

{
"success": true,
"data": {
  "id": "uuid",
  "team_id": "uuid",
  "title": "Analytics Q3 review",
  "messages": [
    { "role": "user", "content": "Show top pages", "timestamp": "2026-02-07T14:30:00Z" },
    { "role": "assistant", "content": "Here are your top pages...", "timestamp": "2026-02-07T14:30:01Z" }
  ],
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-07T14:30:01Z"
}
}

POST /conversations

{
"title": "New conversation",
"team_id": "uuid"
}

• title (obrigatório) — string não vazia
• team_id (opcional) — padrão para a organização do usuário

Resposta: 201 com a conversa criada (inclui messages: [] vazio).

PUT /conversations/:id

{
"title": "Updated title",
"messages": [...]
}

Ambos os campos são opcionais. Aceita atualizações parciais.

DELETE /conversations/:id

Resposta: 200 com { "deleted": true }.

POST /conversations/:id/messages

Anexa uma mensagem à conversa. O servidor adiciona um timestamp a cada mensagem.

{
"role": "user",
"content": "What were last week's top referrers?"
}

• role (obrigatório) — função da mensagem (por exemplo, "user", "assistant")
• content (obrigatório) — texto da mensagem

Resposta: 201 com a conversa completa atualizada incluindo todas as mensagens.

API de Configurações do Site

URL base: https://api.zenovay.com/api/websites

Autenticação: Bearer JWT obrigatório. Cada endpoint aplica uma função mínima.

Gerenciar a configuração do site incluindo configurações gerais, notificações, exclusões de tráfego, rastreamento de receita, domínios e membros da equipe. Todos os caminhos estão no escopo por :websiteId.

Endpoints

PUT /:websiteId/general

{
"domain": "example.com",
"name": "My Website",
"timezone": "America/New_York",
"primary_color": "#4F46E5",
"kpi_goal": 10000,
"public_dashboard": true,
"allowed_domains": ["example.com", "www.example.com"]
}

{
"success": true,
"data": {
  "id": "uuid",
  "domain": "example.com",
  "name": "My Website",
  "timezone": "America/New_York",
  "primary_color": "#4F46E5",
  "kpi_goal": 10000,
  "public_dashboard": true,
  "allowed_domains": ["example.com", "www.example.com"],
  "updated_at": "2026-02-07T12:00:00Z"
}
}

GET /:websiteId/notifications

Retorna preferências de notificação. Se nenhuma tiver sido configurada, retorna um objeto padrão com apenas o website_id.

PUT /:websiteId/notifications

Aceita campos de preferência de notificação. Usa um padrão upsert: cria o registro na primeira chamada, atualiza em chamadas subsequentes.

GET /:websiteId/exclusions

Retorna exclusões de IP e caminho em uma única resposta.

{
"success": true,
"data": {
  "ip_exclusions": [
    { "id": "uuid", "website_id": "uuid", "ip_address": "192.168.1.1", "description": "Office IP", "created_at": "..." }
  ],
  "path_exclusions": [
    { "id": "uuid", "website_id": "uuid", "path_pattern": "/admin/*", "description": "Admin pages", "created_at": "..." }
  ]
}
}

POST /:websiteId/exclusions/ip

{
"ip_address": "192.168.1.1",
"description": "Office IP"
}

• ip_address (obrigatório)
• description (opcional)

Resposta: 201. Retorna 409 se o IP já estiver excluído.

POST /:websiteId/exclusions/path

{
"path_pattern": "/admin/*",
"description": "Admin pages"
}

• path_pattern (obrigatório)
• description (opcional)

Resposta: 201. Retorna 409 se o padrão de caminho já estiver excluído.

PUT /:websiteId/revenue

Requer função admin.

{
"revenue_provider": "stripe",
"revenue_currency": "USD"
}

{
"success": true,
"data": {
  "id": "uuid",
  "revenue_provider": "stripe",
  "revenue_currency": "USD",
  "updated_at": "2026-02-07T12:00:00Z"
}
}

GET /:websiteId/domains

{
"success": true,
"data": {
  "primary_domain": "example.com",
  "allowed_domains": ["example.com", "www.example.com"],
  "verification_status": "verified"
}
}

PUT /:websiteId/domains

Requer função admin.

{
"domain": "example.com",
"allowed_domains": ["example.com", "www.example.com"]
}

allowed_domains deve ser um array se fornecido.

GET /:websiteId/team-members

Retorna membros da equipe enriquecidos com dados de perfil do usuário.

{
"success": true,
"data": [
  {
    "id": "membership_uuid",
    "user_id": "user_uuid",
    "role": "admin",
    "created_at": "2026-01-15T10:00:00Z",
    "deactivated_at": null,
    "user": {
      "id": "user_uuid",
      "email": "[email protected]",
      "full_name": "Jane Doe",
      "avatar_url": "https://..."
    }
  }
]
}

POST /:websiteId/team-members

Convidar um usuário por email. Requer função admin.

{
"email": "[email protected]",
"role": "editor"
}

• email (obrigatório) — deve ser um usuário Zenovay registrado
• role (opcional) — padrão para "viewer". Deve ser um de: owner, admin, editor, viewer

Resposta: 201. Retorna 404 se o email não for encontrado, 409 se já for um membro.

PUT /:websiteId/team-members/:memberId

Atualizar a função de um membro. Requer função admin.

{
"role": "admin"
}

• role (obrigatório) — deve ser um de: owner, admin, editor, viewer

DELETE /:websiteId/team-members/:memberId

Remove um membro da equipe (exclusão suave). Requer função admin.

Resposta: 200 com { "deleted": true }.

API de Onboarding

URL base: https://api.zenovay.com/api/onboarding

Autenticação: Bearer JWT obrigatório. No escopo do usuário (sem verificações de equipe ou função).

Rastrear o progresso de integração do usuário. Cada usuário tem um único registro de integração que persiste entre sessões.

Endpoints

GET /onboarding/progress

Retorna o estado de integração do usuário. Se nenhum registro existir, retorna padrões.

{
"success": true,
"data": {
  "user_id": "uuid",
  "current_step": "add_website",
  "completed": false,
  "data": { "welcomed": true },
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-07T14:00:00Z"
}
}

POST /onboarding/progress

Usa um padrão upsert: cria o registro na primeira chamada, atualiza em chamadas subsequentes.

{
"step": "install_tracking",
"data": { "welcomed": true, "website_added": true },
"completed": false
}

• step — salvo como current_step no banco de dados
• data — objeto JSON arbitrário para armazenar estado específico da etapa
• completed — padrão para false

API de Equipes

URL base: https://api.zenovay.com/api/teams

Autenticação: Bearer JWT obrigatório. Associação à equipe verificada (qualquer membro ativo pode acessar).

Endpoints de contexto de equipe somente leitura para permissões, estatísticas de uso e listas de membros. Para ações de gerenciamento de equipe (convidar, mudanças de função, remoção), use os endpoints team-members da API de Configurações do Site.

Endpoints

GET /teams/:id/permissions

Retorna a função do usuário autenticado, o plano da equipe, contagens de uso atuais e sinalizadores de permissão computados.

{
"success": true,
"data": {
  "team_id": "uuid",
  "role": "admin",
  "plan": "Pro",
  "plan_limits": {
    "maxWebsites": 5,
    "maxTeamMembers": 5,
    "eventsPerMonth": 10000,
    "dataRetentionDays": 730
  },
  "current_usage": {
    "websites": 3,
    "team_members": 5
  },
  "permissions": {
    "can_manage_billing": false,
    "can_manage_team": true,
    "can_edit_settings": true,
    "can_view": true
  }
}
}

GET /teams/:id/usage

Retorna estatísticas de uso do período de cobrança atual (mês até agora).

{
"success": true,
"data": {
  "team_id": "uuid",
  "plan": "Pro",
  "period": {
    "start": "2026-02-01T00:00:00.000Z",
    "end": "2026-02-07T12:00:00.000Z"
  },
  "usage": {
    "events": 4521,
    "events_limit": 10000,
    "websites": 3,
    "websites_limit": 10,
    "team_members": 5,
    "team_members_limit": 10
  }
}
}

GET /teams/:id/members

Retorna membros da equipe enriquecidos com dados de perfil do usuário.

{
"success": true,
"data": [
  {
    "id": "membership_uuid",
    "user_id": "user_uuid",
    "role": "admin",
    "created_at": "2026-01-15T10:00:00Z",
    "user": {
      "id": "user_uuid",
      "email": "[email protected]",
      "full_name": "Jane Doe",
      "name": "Jane",
      "avatar_url": "https://..."
    }
  }
]
}

API de Perfil do Usuário

URL base: https://api.zenovay.com/api/users

Autenticação: Bearer JWT obrigatório. No escopo do usuário (apenas perfil próprio).

Gerenciar o perfil do usuário autenticado e endereço de email.

Endpoints

PUT /users/me/email

Endpoint dedicado para mudanças de email com detecção de provedor de SSO. Se o usuário se registrou via um provedor OAuth (Google, GitHub, etc.), a solicitação é rejeitada com uma mensagem para atualizar o email através desse provedor.

{
"email": "[email protected]"
}

• email (obrigatório) — deve ser um email válido, diferente do atual

Resposta: 200 com o registro de usuário atualizado. Retorna 400 se o usuário for uma conta de SSO ou o email for inválido/inalterado.

Próximas Etapas

• API Externa - Análises do lado do servidor com autenticação de chave de API
• Widgets - Widgets incorporáveis pré-construídos
• Dados em Tempo Real - Endpoints de dados de visitantes ao vivo
• Autenticação - Gerenciamento de chaves de API
• Limites de Taxa - Entendendo limites