Integrar o WhatsApp ao HubSoft: credenciais, permissões e o que dá para automatizar

Integrar o WhatsApp ao HubSoft exige cinco dados que só o administrador do provedor consegue gerar dentro do ERP: host, client_id, client_secret, username e password, com grant_type igual a password. Eles nascem de um usuário de API dedicado, criado em Configuração > Geral > Usuários — e é nesse usuário, não na credencial, que moram as permissões que decidem o que a automação vai poder ler e escrever. É esse detalhe que faz um chatbot pronto e testado "não achar" o contrato do assinante no primeiro dia em produção.

Este artigo é para quem opera um provedor no HubSoft e quer saber, na prática, o que a integração exige, quais limites a API impõe e o que dá para automatizar no atendimento. Tudo o que se afirma aqui sobre o HubSoft vem da documentação oficial da API e da Wiki HubSoft, consultadas em 6 de setembro de 2026.

O que a API do HubSoft entrega

A documentação oficial descreve o HubSoft como um ERP com foco em provedores de internet e empresas de telecomunicações, construído desde o início voltado a integrações. A API é REST sobre HTTP, e o método define a operação: GET consulta, POST adiciona, PUT edita, DELETE remove. A ressalva está na própria documentação — nem todo endpoint libera o CRUD completo; parte deles hoje só aceita GET.

Os endpoints são organizados em grupos que espelham a operação de um ISP: Atendimento, Clientes, CRM, Financeiro, Ordem de Serviço, Tarefas, Estoque, Mapeamento, Nota Fiscal, PBX, Prospectos, Rede e Configuração. Para um fluxo de atendimento no WhatsApp, os quatro primeiros são os que importam — é de lá que saem identificação do assinante, segunda via, status de contrato e abertura de chamado.

Dois detalhes que economizam retrabalho na primeira integração: a paginação começa em 0, não em 1, e o retorno traz um bloco paginacao com ultima_pagina e total_registros — quem assume página 1 perde silenciosamente o primeiro lote. E existe também uma API GraphQL, cuja autenticação é a mesma da API pública, baseada em OAuth.

As cinco credenciais — e por que cada integrador precisa do próprio usuário

Desde 13 de novembro de 2023, o HubSoft passou a exigir que cada usuário conectado à API tenha o seu próprio client_id e client_secret, além de usuário e senha próprios. A mudança está publicada na nota de atualização de segurança da autenticação, e a orientação do fabricante é explícita: cada software integrado deve ter o seu usuário, e o mesmo usuário nunca deve ser compartilhado entre aplicações diferentes.

Na prática, isso é bom para o provedor. Com um usuário por integrador, trocar de plataforma de atendimento, revogar um fornecedor ou investigar um pico de consultas vira uma operação isolada — você desliga um acesso sem derrubar o hotspot, o app de campo e o disparador de cobrança junto.

É isto que a plataforma de atendimento precisa receber:

Campo	Onde sai
Host	aba API, na edição do usuário
Client ID	aba API, gerado pelo sistema
Client Secret	aba API, gerado pelo sistema
Username	e-mail definido no cadastro do usuário
Password	senha definida no cadastro do usuário
Grant Type	a palavra password

Um alerta que vale anotar antes de clicar em salvar: a Wiki avisa que a senha não pode ser visualizada depois que o usuário é criado. Esqueceu de anotar, o caminho é editar o usuário e definir uma nova — o que significa reenviar credencial para o integrador e, se ninguém avisar, uma janela de atendimento fora do ar.

A permissão mora no usuário de API, não na credencial

Esse é o ponto em que a integração costuma travar depois de tudo "pronto". Criar o usuário e habilitar o acesso à API não libera dado nenhum: existe uma terceira etapa, a de definir as permissões dos recursos acessíveis àquele usuário. A documentação recomenda liberar o acesso com cautela e alinhar com o integrador exatamente quais dados serão consumidos, "para garantir que somente os dados essenciais sejam consumidos da API".

A própria seção de problemas frequentes da Wiki confirma o sintoma: quando o usuário de API não consegue consultar determinada informação, a causa apontada é falta da permissão específica para aquele tipo de consulta. Não é erro de credencial, não é erro de código — é escopo.

O jeito de não descobrir isso em produção é inverter a ordem. Liste antes os fluxos que o WhatsApp vai atender — segunda via, desbloqueio de confiança, abertura de ordem de serviço, consulta de status — e derive as permissões a partir deles. É o mesmo raciocínio que vale para a integração com o IXC, onde a permissão vive no grupo de usuários, e para o chat integrado ao SGP. Muda a mecânica de cada ERP; não muda a pergunta.

Rate limit: 20 requisições por segundo e o que fazer com o 429

A API do HubSoft aplica limitação de requisições por IP, com duas políticas distintas, publicadas na documentação oficial:

Rota	Limite	Burst
Autenticação (oAuth)	30 requisições/minuto	20
Integração (demais endpoints)	20 requisições/segundo	200

Ao estourar, a API devolve HTTP 429 com o campo retry_after em segundos e o cabeçalho X-RateLimit-Policy indicando qual política foi aplicada. A recomendação do fabricante é implementar backoff respeitando esse valor, sob risco de bloqueios adicionais.

Duas consequências operacionais que raramente aparecem na proposta comercial. A primeira: o limite mais apertado é o da autenticação, não o das consultas — 30 por minuto. Uma integração que pede token novo a cada mensagem, em vez de reaproveitar o token válido, quebra num pico de tarde de segunda-feira e não no teste de mesa. A segunda: o limite é por IP, então disparo de cobrança em massa e consultas do bot de atendimento competem pela mesma cota se saírem do mesmo lugar.

O que dá para automatizar no WhatsApp

Segundo a página de integrações da API oficial, as integrações de chatbot existem para que o assinante resolva sozinho, sem atendente: solicitar segunda via de boleto, pedir desbloqueio em confiança, abrir atendimento. É a lista curta do que tira volume da fila, e ela cobre a maior parte do que chega no WhatsApp de um provedor.

Na Talqui, a integração com o HubSoft trabalha exatamente sobre esses fluxos: emissão de boleto e PIX dentro da conversa, desbloqueio de confiança com validação via API, lembretes de vencimento, diagnóstico do status da conexão e abertura de ordem de serviço a partir do que o cliente escreveu — sem ninguém abrir o ERP para atender.

Vale medir o efeito no lugar certo. Cada rodada de "me informa seu CPF, por favor" é tempo de atendente e, na API oficial do WhatsApp, também é conversa cobrada. Quando o bot já identificou o assinante e devolveu a segunda via, some a rodada — e some o custo dela. Para dimensionar isso na sua base antes de assinar qualquer contrato, use a calculadora de preços da API do WhatsApp; o desenho da cobrança está detalhado em o que muda no faturamento em outubro de 2026.

O HubSoft publica quem integra — e o que perguntar a cada fornecedor

A Wiki mantém uma lista pública de plataformas que integram pela API oficial, separada por categoria: chatbot, CRM, hotspot, mapeamento, PBX e SVA. Na categoria de chatbot havia 13 plataformas listadas na consulta de 6 de setembro de 2026. A mesma página registra que, se a integração desejada não estiver ali, o caminho é falar com a equipe do HubSoft — ou seja, estar fora da lista não impede integrar pela API aberta, e estar na lista não descreve profundidade.

Por isso a lista é ponto de partida, não critério de decisão. Quatro perguntas que separam integração real de página de marketing, e que servem para qualquer fornecedor:

• Quais endpoints o fornecedor consome — e quais permissões ele vai pedir no seu usuário de API. Resposta genérica aqui costuma virar surpresa depois.
• O que a plataforma faz ao receber um 429. Existe backoff respeitando o retry_after, ou a mensagem do assinante simplesmente se perde?
• O token é reaproveitado ou a integração autentica a cada requisição? É a diferença entre caber e não caber nas 30 autenticações por minuto.
• O que volta para o ERP. Uma conversa que resolve mas não registra protocolo, ordem de serviço ou histórico no HubSoft deixa a operação com dois lugares de verdade — e nenhum confiável.

Perguntas frequentes

Preciso criar um usuário de API só para o chatbot?

Sim. A orientação publicada pelo HubSoft é que cada software integrado tenha o seu próprio usuário, com client_id e client_secret próprios, e que o mesmo usuário nunca seja compartilhado entre aplicações diferentes.

Quantas requisições a API do HubSoft aceita?

Por IP: 30 requisições por minuto na rota de autenticação (burst 20) e 20 requisições por segundo nos demais endpoints (burst 200). Acima disso, a resposta é HTTP 429 com o tempo de espera em retry_after.

Qual a diferença entre a API REST e a GraphQL do HubSoft?

A autenticação é a mesma, baseada em OAuth, conforme a documentação da API GraphQL. O que muda é o formato da consulta — a REST é a rota documentada por padrão em docs.hubsoft.com.br.

Preciso da API oficial do WhatsApp para integrar com o HubSoft?

São duas coisas distintas: a API do HubSoft dá acesso ao ERP, e a API oficial do WhatsApp dá o canal de mensagem. Uma automação de atendimento estável em volume de provedor depende das duas.

Já uso IXC ou SGP em outra base. Muda alguma coisa?

Muda a mecânica de credencial e de permissionamento de cada ERP, não o desenho do atendimento. No HubSoft a permissão está no usuário de API; no IXC, no grupo de usuários vinculado ao token.

Próximo passo

Se o seu provedor roda no HubSoft e o WhatsApp ainda é uma caixa de entrada que alguém responde no braço, o gargalo não é o ERP — é a camada de atendimento em cima dele. Veja como a Talqui atende provedores de internet, com identificação do assinante, segunda via e abertura de O.S. dentro da conversa, e compare com a sua operação de hoje em planos e preços. Se preferir tirar dúvida antes, fale com um especialista — leva menos tempo que abrir um chamado.