Pular para o conteúdo
Salesbud Developers

Changelog

Mudanças que quebram uma versão já publicada são anunciadas antes de entrar. Mudanças aditivas — campo novo, endpoint novo, código de erro novo — podem chegar a qualquer momento, então faça parse defensivo: ignore campos que você não reconhece.

Não publicado — primeira entrega

Seção intitulada “Não publicado — primeira entrega”

A versão v1 ainda não foi liberada para parceiros. O que segue é a forma da primeira entrega.

  • O acesso ao produto passa a usar as features persistidas da empresa e as permissões do dono igualmente em contas diretas e parceiras. Ofertas comerciais não revogam features concedidas. Novos tokens exigem a feature do aplicativo; tokens emitidos mantêm a duração normal, com revogação da credencial ainda imediata.

  • A atribuição de reuniões e chamadas segue a empresa padrão atual do dono em contas diretas e parceiras; marcadores históricos do evento não fixam a empresa. Permanecem os limites da empresa da credencial e de visibilidade. O WhatsApp usa a empresa salva da sessão de forma uniforme; sessões sem empresa mantêm sua resolução legada autorizada.

  • Nomes de templates de reunião fora do escopo da empresa atual passam a usar o rótulo estável Template; respostas históricas e referências de template restritas à empresa continuam disponíveis. Nomes de templates pessoais e atualmente autorizados são preservados.

  • Respostas e visibilidade por origem do WhatsApp incluem umbler_talk e antonella, junto de WhatsApp Web e RD Conversas, respeitando a integração habilitada na conta e as permissões do dono.

  • O metadata do recurso protegido do OAuth passa a nomear o recurso como MCP server em resource_name, e a página de erro e os textos de error_description do /oauth/authorize deixam de citar uma marca.

Ferramentas

  • Um servidor MCP oficial acompanha a v1: @salesbud/mcp no npm, uma tool por operação pública de leitura, para Claude Desktop, Claude Code e Cursor. Ele é cliente desta API e não acrescenta capacidade nenhuma. Veja Servidor MCP.
  • Servidor MCP 0.2.0: novas tools list_accounts, list_teams e list_tags; as tools de listagem aceitam os filtros novos; o texto das listagens mostra todas as contas de cada registro, até três (o nome, senão o domínio), inclusive nas conversas de e-mail, que antes saíam com a conta em branco.
  • Servidor MCP: get_api_context diz se a credencial é da empresa ou de um usuário e mostra o dono.
  • Servidor MCP 0.3.0: autentica com OAuth (Bearer), para que o Claude e o ChatGPT conectem fazendo a pessoa entrar. Sem credencial, POST /mcp responde 401 com um challenge WWW-Authenticate cujo resource_metadata aponta para /.well-known/oauth-protected-resource. Token inválido, expirado ou revogado vira um pedido para reconectar, e uma conexão que aguarda aprovação do administrador é descrita assim pelas tools. Os headers fixos X-Client-Id/X-Client-Secret continuam funcionando. Veja Conectar o Claude ou o ChatGPT.
  • Servidor MCP 0.4.0: novas find_meetings e find_calls, que acham os registros de uma conta pelo nome, domínio, CNPJ ou id; uma chamada lê no máximo 30 páginas em 20 segundos e devolve o próprio next_cursor quando um teto a para. Uma chamada que o cliente cancela para as leituras que começou, e todo parâmetro de data declara format: "date-time". O texto das respostas das tools que já existiam não muda. Veja Servidor MCP.
  • GET /mcp/tools lista as tools da MCP sem credencial — os mesmos campos do tools/list, mais serverVersion — com cache de cinco minutos. Veja Servidor MCP.
  • Servidor MCP 0.3.1: toda tool declara destructiveHint: false e openWorldHint: false junto de readOnlyHint: true, para que os assistentes saibam que as tools só leem o workspace Salesbud conectado.
  • O Salesbud está no diretório de conectores do Claude: quem usa o Claude conecta pelo diretório, com o conector personalizado como alternativa. Veja Conectar o Claude ou o ChatGPT.

Recursos

  • Ligações são coleção própria em /v1/calls, com identificadores call_. Um registro capturado por integração de VoIP tem object: "call"; o resto é meeting. Ids não resolvem entre coleções.
  • As cinco rotas são espelhadas nas duas coleções: listar, obter, transcrição, respostas de template e avaliação geral.
  • A ligação não carrega bot_history: captura de VoIP não tem bot de gravação, então o campo é omitido em vez de voltar vazio, e um schema que valida ligação o recusa. enablement.meeting_type fica e costuma vir null — esse nulo é legítimo, diferente do bot.
  • Conversas de WhatsApp dos vendedores da empresa são uma coleção em /v1/whatsapp, com identificadores wa_ e mensagens wamsg_, atrás de whatsapp.read (metadado) e whatsapp.content.read (texto sanitizado, metadado de mídia, transcrição de áudio). last_message_at só anda com mensagem nova, então releia as mensagens para ver edições e apagamentos; mensagem apagada fica como lápide. Filtros de data comparam em segundos inteiros. Veja WhatsApp.
  • Adicionados GET /v1/accounts, GET /v1/teams e GET /v1/tags: catálogos paginados das contas (buscáveis por nome ou domínio com q, de 2 a 100 caracteres), times e tags da própria empresa, com os ids opacos que os filtros das listagens aceitam. Contas sem domínio utilizável e tags com nome vazio não são listadas.
  • As referências de conta em reuniões, ligações, e-mails e conversas de WhatsApp agora trazem name (null quando a conta ainda não tem nome).

Erros

  • O envelope de erro é { type, title, detail, code, request_id }. Todo campo é snake_case; o status HTTP fica na status line e não se repete no corpo. Ramifique pelo code.
  • POST /oauth/token mantém o formato de erro do OAuth 2.0 exigido pela RFC 6749 §5.2.
  • account_id, team_id ou tag_id malformado, score_min ou score_max que não seja inteiro de 0 a 10, score_min maior que score_max, ou q fora de 2 a 100 caracteres é INVALID_FILTER. Id bem formado que a empresa não possui devolve página vazia, não erro. Reusar um cursor com outro filtro é INVALID_CURSOR.
  • POST /oauth/token responde invalid_client com o error_description “The credential has no active owner.” para a credencial de usuário cujo dono não é mais membro ativo da empresa. Credenciais de usuário não trazem outro código de erro: recurso fora da visão do dono é 404.
  • Erro novo 403 API_CLIENT_PENDING_APPROVAL (“The API client is waiting for administrator approval.”): o token é de uma conexão que ainda aguarda aprovação do administrador.
  • O 403 API_ACCESS_DISABLED já existente (a empresa não tem acesso à API) agora está documentado em POST /oauth/token. Ele usa o envelope de erro acima, não o formato de erro OAuth.

Paginação e filtros

  • Os cursores são assinados e ordenados por id crescente; eles amarram os filtros da requisição que os gerou.
  • updated_after, updated_before e snapshot_at foram removidos. Sem carimbo dedicado de visibilidade não há sync incremental honesto; reconsulte por período. O updated_at continua nas respostas, como informativo.
  • Os filtros de data são meeting_after e meeting_before. Versões anteriores também aceitavam meeting_at_from e meeting_at_to; eles nunca chegaram a parceiro e foram removidos, em vez de nascerem descontinuados.
  • Adicionados account_id e team_id em /v1/meetings, /v1/calls, /v1/emails e /v1/whatsapp, e tag_id, score_min e score_max em /v1/meetings e /v1/calls. Veja Filtrar por conta, time, tag e nota.
  • team_id significa os vendedores cujo time padrão é aquele: um vendedor em vários times conta só para o time padrão, então as reuniões, ligações e conversas de WhatsApp de um vendedor caem em no máximo um time. Vendedores sem time e conversas do RD Conversas não pertencem a time nenhum, então somar os times pode ficar abaixo do total sem filtro. A atribuição é a atual, não o time na data do registro. Time sem membros devolve página vazia. Em e-mails, casa com a conversa quando qualquer uma das suas threads está na caixa de um membro do time, então uma conversa compartilhada entre times pode aparecer em mais de um. No WhatsApp, cobre só números que um membro do time conectou diretamente; as conversas do RD Conversas não têm dono e ficam de fora quando team_id é informado.
  • score_min e score_max são inclusivos e contam só avaliações concluídas: uma reunião em reavaliação some da listagem filtrada por nota até a nova avaliação terminar.
  • Cursores emitidos antes desta mudança continuam válidos: os filtros novos só entram no cursor quando presentes.

Acesso

  • A API é gateada pela feature API_ACCESS da empresa, verificada na emissão de token e na criação de credencial.
  • Emails e domínios de conta são normalizados para minúsculo em todos os campos, então um endereço pode ser usado como chave de junção independentemente de onde apareça.
  • Os catálogos aceitam qualquer escopo de leitura de coleção: meetings.read, calls.read, emails.read ou whatsapp.read.
  • Adicionadas as credenciais de usuário: solicitadas por qualquer membro de uma empresa com API_ACCESS que não aprova credenciais, aprovadas por um administrador, 3 ativas e 1 pendente por usuário em cada empresa, válidas por 30, 90, 180 ou 365 dias contados da aprovação e limitadas ao que o dono vê no Salesbud, inclusive as reuniões compartilhadas com ele. As credenciais de empresa não mudam. Veja Duas espécies de credencial, Solicitando uma credencial de usuário e A credencial de usuário vê o que o dono vê.
  • Rotacionar uma credencial de usuário, o que só o dono pode fazer, encerra o secret anterior na hora e define uma validade nova.
  • GET /v1/context agora devolve client.kind (company ou user) e client.owner, o dono da credencial de usuário (null na credencial de empresa).
  • O token de uma credencial de usuário carrega só os escopos que o dono pode usar no momento da emissão, e mudanças nos times, compartilhamentos ou permissões do dono chegam à API em até 60 segundos.
  • Com a feature ACCOUNTS desligada, a credencial de usuário recebe /v1/accounts vazio, accounts: [] em reuniões, ligações e conversas de email e WhatsApp, e página vazia ao filtrar por account_id.
  • Login OAuth para conectores: GET /oauth/authorize, os grants authorization_code e refresh_token do POST /oauth/token (a resposta do token traz um refresh_token rotativo para eles, e o erro OAuth invalid_grant é novo) e metadados de descoberta em /.well-known/oauth-authorization-server e /.well-known/oauth-protected-resource. A conexão é uma credencial de usuário que lê o que a pessoa que entrou vê, aguarda aprovação do administrador quando essa pessoa não aprova credenciais e aparece na tela de credenciais da API com o nome do app. O client_credentials não mudou. Veja Conectar o Claude ou o ChatGPT.
  • Os apps da própria Salesbud, como os Colaboradores IA, conectam pelo mesmo login OAuth sob a feature de colaboradores no lugar do acesso à API, e o POST /oauth/token responde 403 AI_COLLABORATORS_DISABLED sem ela. A conexão deles nasce ativa, sem aprovação, e fica fora dos limites por usuário. Veja Solicitando uma credencial de usuário.
  • Novo POST /oauth/revoke (RFC 7009): um refresh token ou um access token de uma conexão feita com login revoga a conexão inteira, e a resposta é 200 com corpo vazio mesmo para um token desconhecido. Os metadados do servidor de autorização anunciam a rota em revocation_endpoint. Veja /oauth/revoke.
  • Renovar uma conexão que um administrador desativou responde invalid_grant com "error_description": "The connection was disabled by a company administrator."; ela volta a renovar quando é reativada.
  • POST /oauth/revoke e a revogação pelo dono não transformam mais em revogada uma conexão que um administrador desativou: os refresh tokens acabam e ela continua desativada até um administrador revogá-la.