Filtrar por conta, time, tag e nota

As listagens de reuniões, ligações, e-mails e WhatsApp aceitam o id opaco de uma conta ou de um time. Reuniões e ligações aceitam também uma tag e uma faixa de nota da avaliação geral. Os ids vêm de três catálogos, GET /v1/accounts, GET /v1/teams e GET /v1/tags, e são os mesmos que aparecem dentro dos registros.

Encontre o id primeiro

Contas podem ser buscadas por nome ou por domínio de e-mail com q (2 a 100 caracteres, sem distinguir maiúsculas de minúsculas, em qualquer posição do nome ou do domínio). Times e tags são listas curtas; basta paginar.

curl -sS -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.salesbud.com.br/v1/accounts?q=acme"

{
  "data": [
    {
      "id": "acc_01JPUBLICAPI",
      "object": "account",
      "name": "Acme Ltda",
      "domain": "acme.com.br",
      "cnpj": "12.345.678/0001-90"
    }
  ],
  "pagination": { "limit": 50, "has_more": false, "next_cursor": null },
  "request_id": "req_01JPUBLICAPI"
}

Os catálogos paginam como qualquer listagem (limit até 100, cursor vindo de next_cursor; veja Paginação) e aceitam qualquer escopo de leitura de coleção: meetings.read, calls.read, emails.read ou whatsapp.read. Devolvem só as contas, times e tags da própria empresa. Uma credencial de usuário vê só os times e tags que o dono vê (Segurança). Veja o objeto conta, o objeto time e o objeto tag.

Algumas entradas ficam de fora de propósito. O catálogo de contas omite contas sem domínio utilizável, e o de tags omite tags com nome vazio. Um time sem nome aparece como Unnamed team (valor literal da API, em inglês).

Filtre uma listagem

curl -sS -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.salesbud.com.br/v1/meetings?account_id=acc_01JPUBLICAPI&score_min=7"

Filtro	/v1/meetings, /v1/calls	/v1/emails, /v1/whatsapp
account_id	sim	sim
team_id	sim	sim
tag_id	sim	não
score_min, score_max	sim	não

Os filtros se combinam entre si e com os demais filtros de cada listagem; o registro precisa satisfazer todos. Os filtros mais antigos existem só em algumas listagens: data, dono, tipo, audiência e transcrição em reuniões e ligações, e as datas last_message_after e last_message_before em e-mails e WhatsApp.

O que cada filtro significa

• account_id devolve os registros vinculados àquela conta. Uma reunião pode estar vinculada a mais de uma conta e entra no resultado se qualquer uma delas for a pedida.
• team_id devolve os registros cujo dono tem aquele time como time padrão. Vendedor em vários times conta uma única vez, pelo 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 do vendedor, não a da data da reunião. Um 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.
  • Em WhatsApp, casa só com as conversas de números que um membro do time conectou diretamente. As conversas que chegam pelo RD Conversas não têm dono e ficam de fora sempre que team_id é informado.
• tag_id devolve as reuniões ou ligações que carregam aquela tag.
• score_min e score_max são inteiros de 0 a 10, inclusive, comparados com a nota da avaliação geral. Um limite sozinho funciona; score_min não pode passar de score_max. Só contam avaliações concluídas: registro sem avaliação, ou com a avaliação sendo refeita, fica de fora sempre que algum limite é informado.

Ids desconhecidos ou malformados

• Id que não segue o padrão do prefixo (acc_…, team_…, tag_…), nota fora de 0 a 10, nota vazia ou não inteira, ou score_min acima de score_max é recusado com 400 INVALID_FILTER.
• Id bem formado que a empresa não possui devolve 200 com data vazio e has_more: false. A API nunca confirma se o id existe em outro lugar.
• O cursor fica preso aos filtros com que foi emitido. Mudar qualquer filtro, inclusive estes, e reaproveitar um cursor antigo devolve 400 INVALID_CURSOR; recomece sem cursor. Cursores emitidos antes de estes filtros existirem continuam válidos nas requisições que não os usam.

Nome da conta dentro dos registros

As referências de conta em reuniões, ligações, e-mails e conversas de WhatsApp agora trazem name ao lado de id, domain e cnpj. name é null quando a conta ainda não tem nome; use domain como rótulo alternativo.