⚡ API Reference

Base URL: https://api.upbeez.com

Documentação interativa (Swagger): api.upbeez.com/docs

🔐 Autenticação

A API usa JWT Bearer Token. Obtenha um token via login:

POST/auth/register

Criar conta

{
  "email": "[email protected]",
  "password": "senha123",
  "company_name": "Minha Empresa"
}

POST/login

{
  "email": "[email protected]",
  "password": "senha123"
}

Resposta:

{
  "access_token": "eyJhbGci...",
  "token_type": "bearer"
}

GET/auth/me

Dados do usuário autenticado (requer Bearer token)

POST/auth/google

{ "id_token": "eyJhbGci..." }

Use o token em todas as requisições autenticadas:

curl -H "Authorization: Bearer SEU_TOKEN" https://api.upbeez.com/auth/me

🏢 Workspaces

Workspaces agrupam bots, fontes e integrações por empresa ou projeto. Um usuário pode pertencer a múltiplos workspaces com papéis diferentes. Veja Guia de Workspaces →

GET/workspaces

Lista todos os workspaces do usuário autenticado

Resposta:

[
  {
    "id": "ws_abc123",
    "name": "Restaurante X",
    "role": "owner",
    "created_at": "2024-01-15T10:00:00Z"
  },
  {
    "id": "ws_def456",
    "name": "Loja Y",
    "role": "admin",
    "created_at": "2024-02-01T08:30:00Z"
  }
]

POST/workspaces

Cria um novo workspace

{
  "name": "Minha Nova Empresa"
}

Resposta:

{
  "id": "ws_new789",
  "name": "Minha Nova Empresa",
  "role": "owner",
  "created_at": "2024-03-10T12:00:00Z"
}

POST/workspaces/{id}/switch

Muda o workspace ativo da sessão. O token continuará válido mas as chamadas subsequentes usarão o novo workspace.

Resposta:

{
  "workspace_id": "ws_abc123",
  "message": "Workspace alterado com sucesso"
}

Membros

GET/workspaces/{id}/members

Lista todos os membros do workspace

Resposta:

[
  {
    "user_id": "usr_001",
    "email": "[email protected]",
    "name": "João Silva",
    "role": "owner"
  },
  {
    "user_id": "usr_002",
    "email": "[email protected]",
    "name": "Maria Santos",
    "role": "member"
  }
]

POST/workspaces/{id}/invite

Convida um membro para o workspace. Um email com link de convite será enviado.

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

Resposta:

{
  "invite_id": "inv_xyz",
  "email": "[email protected]",
  "role": "member",
  "expires_at": "2024-04-10T12:00:00Z"
}

DELETE/workspaces/{id}/members/{user_id}

Remove um membro do workspace. Owners não podem ser removidos.

🐝 Bots

Cada workspace pode ter múltiplos bots com personalidades e bases de conhecimento distintas. A Bot API Key é usada para autenticar o widget e integrações de canal. Veja Guia de Bots →

GET/bots

Lista todos os bots do workspace ativo

Resposta:

[
  {
    "id": "bot_001",
    "name": "Atendimento",
    "system_prompt": "Você é um assistente amigável...",
    "created_at": "2024-01-20T09:00:00Z"
  },
  {
    "id": "bot_002",
    "name": "Delivery",
    "system_prompt": "Você cuida dos pedidos de delivery...",
    "created_at": "2024-02-05T14:00:00Z"
  }
]

POST/bots

Cria um novo bot no workspace ativo

{
  "name": "Suporte Técnico",
  "system_prompt": "Você é um especialista técnico. Responda de forma clara e objetiva. Quando não souber, diga que vai escalar para um humano."
}

Resposta:

{
  "id": "bot_003",
  "name": "Suporte Técnico",
  "system_prompt": "Você é um especialista técnico...",
  "api_key": "bk_live_xxxxxxxxxxxx",
  "created_at": "2024-03-10T11:00:00Z"
}

GET/bots/{id}

Retorna os detalhes de um bot específico

Resposta:

{
  "id": "bot_001",
  "name": "Atendimento",
  "system_prompt": "Você é um assistente amigável...",
  "api_key": "bk_live_xxxxxxxxxxxx",
  "sources_count": 5,
  "created_at": "2024-01-20T09:00:00Z",
  "updated_at": "2024-03-01T16:00:00Z"
}

PATCH/bots/{id}

Atualiza nome ou system_prompt do bot

{
  "name": "Atendimento Premium",
  "system_prompt": "Você é um assistente VIP, sempre educado e proativo."
}

DELETE/bots/{id}

Remove o bot e todos os seus dados. Ação irreversível.

POST/bots/{id}/regenerate-key

Regenera a API Key do bot. A key antiga é invalidada imediatamente. Atualize o widget no site.

Resposta:

{
  "api_key": "bk_live_yyyyyyyyyyyy",
  "message": "API key regenerada. Atualize seu widget."
}

📚 Fontes (Knowledge Base)

As fontes são associadas ao bot ativo. Use ?bot_id=bot_001 para especificar o bot.

GET/sources/

Listar todas as fontes do bot ativo

POST/sources/url

Adicionar fonte via URL

{ "url": "https://meusite.com", "bot_id": "bot_001" }

POST/sources/upload

Upload de arquivo (PDF, DOC, imagem). Use multipart/form-data com campos 'file' e 'bot_id'

DELETE/sources/{id}

Remover uma fonte

POST/sources/{id}/rescrape

Re-extrair conteúdo da URL

POST/sources/{id}/reindex

Re-indexar chunks no vector DB

💬 Chat

POST/chat/simple

Enviar mensagem no chat do dashboard (autenticado)

{
  "message": "Qual o horário de funcionamento?",
  "bot_id": "bot_001",
  "conversation_id": "uuid-opcional"
}

POST/chat/widget

Endpoint público para o widget (autenticado via Bot API Key no header X-Bot-Key)

{
  "message": "Olá!",
  "conversation_id": "uuid-opcional"
}

Para o widget, envie a Bot API Key no header: X-Bot-Key: bk_live_xxxxxxxxxxxx

📱 Canais

Todos os endpoints de canal agora recebem bot_id para associar ao bot correto.

POST/bots/{bot_id}/whatsapp/connect

Conectar WhatsApp Business ao bot

{
  "phone_number_id": "123456",
  "access_token": "EAAxxxx...",
  "app_secret": "abc...",
  "welcome_message": "Olá! 👋",
  "auto_reply": true
}

GET/bots/{bot_id}/whatsapp/status

Status da conexão WhatsApp

PATCH/bots/{bot_id}/whatsapp/config

Atualizar configurações

{ "auto_reply": true, "max_response_length": 3 }

POST/bots/{bot_id}/whatsapp/disconnect

Desconectar WhatsApp

Instagram

POST/bots/{bot_id}/instagram/connect

Conectar Instagram DM ao bot

{ "page_id": "123", "access_token": "EAAxxxx..." }

GET/bots/{bot_id}/instagram/status

Status da conexão Instagram

POST/bots/{bot_id}/instagram/disconnect

Desconectar Instagram

Messenger

POST/bots/{bot_id}/messenger/connect

Conectar Messenger ao bot

{ "page_id": "123", "access_token": "EAAxxxx..." }

GET/bots/{bot_id}/messenger/status

Status da conexão Messenger

POST/bots/{bot_id}/messenger/disconnect

Desconectar Messenger

Webhooks (recebidos pela Meta)

GET/webhooks/whatsapp/{bot_id}

Verificação do webhook Meta (hub.challenge)

POST/webhooks/whatsapp/{bot_id}

Recebe mensagens WhatsApp

GET/webhooks/instagram/{bot_id}

Verificação do webhook Instagram

POST/webhooks/instagram/{bot_id}

Recebe DMs Instagram

GET/webhooks/messenger/{bot_id}

Verificação do webhook Messenger

POST/webhooks/messenger/{bot_id}

Recebe mensagens Messenger

💳 Billing (Stripe)

GET/billing/plans

Listar planos disponíveis

GET/billing/status

Status da assinatura atual

POST/billing/checkout

Criar sessão de checkout Stripe

{ "price_id": "price_xxx" }

POST/billing/portal

Abrir portal do cliente Stripe

POST/billing/cancel

Cancelar assinatura

📊 Analytics

GET/workspaces/{id}/usage

Uso do workspace (tokens, mensagens, custo)

GET/bots/{bot_id}/usage

Uso por bot específico

GET/workspaces/{id}/usage/storage

Uso de armazenamento (MB por tipo)

GET/usage/export

Exportar dados de uso em CSV

GET/conversations/export?format=csv&days=30&bot_id=bot_001

Exportar conversas (CSV ou JSON), filtrável por bot

🔔 Webhooks Outbound

Receba notificações quando eventos acontecem no UpBeez:

GET/workspaces/{id}/webhooks/outbound

Listar webhooks configurados no workspace

POST/workspaces/{id}/webhooks/outbound

Criar webhook outbound

{
  "url": "https://meusite.com/webhook",
  "events": ["message.received", "escalated"],
  "bot_id": "bot_001",
  "active": true
}

Eventos disponíveis: message.received, escalated, bot_resumed, created, *

Payloads assinados com X-UpBeez-Signature (HMAC-SHA256).

← Widget Início →