Solução de problemas da integração com HubSpot

Módulo: Plataforma

---

Comece sempre pelo Histórico

Quase todo problema de sincronização tem um registro na aba Histórico, dentro da integração. É de lá que sai o diagnóstico.

1. Em Plataforma > Integrações > HubSpot, clique em Configurar e abra a aba Histórico

2. Busque pelo nome, telefone ou ID do contato, o campo aceita também ID de conversa e IDs do HubSpot

3. Filtre por Status: Falha ou Parcial para ver só o que deu errado

4. Clique no evento para abrir o painel de detalhe

No detalhe, a seção Erro mostra a causa em português e o código do HubSpot ao lado, além do texto original devolvido pelo HubSpot.

Os campos pararam de ir para o HubSpot, sem erro visível

O que você vê: um contato foi atualizado na Nuvia, nada mudou no HubSpot e nenhuma mensagem apareceu na tela.

Causa mais comum: um campo de lista suspensa ou múltipla escolha com valor que não bate exatamente com as opções da propriedade no HubSpot. Diferença de maiúscula, acento ou espaço é suficiente. Quando isso acontece, o HubSpot reprova o registro inteiro, todos os outros campos daquele contato deixam de ser gravados junto.

Como confirmar: no Histórico, o evento aparece com status Falha ou Parcial e a mensagem “O valor enviado não é uma das opções aceitas pela propriedade X no HubSpot.”

Como resolver:

1. Abra a propriedade no HubSpot e copie o texto exato das opções

2. Na Nuvia, ajuste as opções do campo para ficarem idênticas

3. Altere um contato de teste e confirme no Histórico que o status voltou para Sucesso

O mesmo contato virou dois registros no HubSpot

Causa: antes de criar um contato, a Nuvia procura o registro no HubSpot por telefone e por e-mail. A busca por telefone cobre o número no formato internacional, com e sem espaço depois do +55. Se o número está gravado no HubSpot em outro formato, a busca não encontra e um contato novo é criado.

Formatos que não são encontrados pela busca:

• (11) 99999-9999 com parênteses e traço

• 11999999999 sem o código do país

• Número com nono dígito de um lado e sem nono dígito do outro

• Números de outros países gravados em formato local

Como resolver:

1. Padronize os telefones no HubSpot no formato internacional (+5511999999999)

2. Preencha o e-mail dos contatos na Nuvia sempre que possível, quando existe e-mail, ele tem prioridade sobre o telefone na busca e a vinculação fica muito mais precisa

3. Faça o merge dos registros duplicados no próprio HubSpot

O mesmo contato apareceu com dois deals no HubSpot

Causa: na Nuvia, o contato é único por telefone dentro da conta, falar com duas caixas de entrada diferentes não duplica o contato. O deal, por sua vez, é vinculado à conversa. Antes de criar um deal novo, a Nuvia procura no HubSpot um deal já associado àquele contato no mesmo funil e reaproveita esse registro. Ou seja: duas conversas do mesmo contato mapeadas para o mesmo funil compartilham o mesmo deal.

Dois deals aparecem quando:

• As conversas estão mapeadas para funis diferentes do HubSpot

• O contato ainda não estava vinculado a um registro do HubSpot quando o deal foi criado

• A consulta dos deals associados ao contato falhou naquele momento

Como resolver: revise na aba Funis quais etapas têm o interruptor Deal ligado e para quais funis do HubSpot elas apontam. Se o objetivo é um único deal por cliente, mantenha a criação de deal em uma única etapa e em um único funil. Deals já duplicados precisam ser mesclados no HubSpot.

Contatos do HubSpot não chegam na Nuvia

Causa provável: o telefone do contato no HubSpot está sem código de país ou em formato que a Nuvia não consegue interpretar. Contatos com telefone inválido são descartados na entrada e esse descarte não gera registro no Histórico.

Como resolver:

1. Abra a aba Avançado e localize Configurações de Telefone

2. Selecione o DDI padrão da sua operação (por exemplo, +55 - Brasil). A configuração é salva automaticamente ao selecionar

3. Confira se o contato tem telefone preenchido no HubSpot, contatos sem telefone não são criados na Nuvia

Como o DDI padrão funciona:

• Só se aplica a números que chegam do HubSpot sem código de país

• Só é aplicado quando o número tem 11 dígitos ou menos e ainda não começa com aquele DDI

• Números que já chegam no formato internacional (com +) não são alterados

• Para o Brasil, um número de 8 dígitos começando com 6, 7, 8 ou 9 recebe o nono dígito automaticamente

• Números com menos de 8 dígitos são descartados

Deixar a opção Nenhum (detectar automaticamente) faz a Nuvia tentar adivinhar o país pelos primeiros dígitos do número, o que pode errar em números sem código de país. Se sua operação é majoritariamente brasileira, defina +55 explicitamente.

O deal não muda de etapa no HubSpot

Verifique nesta ordem:

1. Existe mapeamento? Na aba Funis, confirme que há uma linha ligando aquela etapa do funil ao deal stage do HubSpot

2. O deal está fechado? A Nuvia não movimenta deal já marcado como ganho ou perdido no HubSpot

3. A etapa é anterior à atual? A Nuvia não move o deal para trás. Se o deal já está em uma etapa mais adiantada, a movimentação é ignorada

4. A conversa está vinculada a um deal? Sem vínculo, não há o que mover

Os itens 2 e 3 são proteções intencionais, nesses casos o deal fica como está e o evento é registrado no Histórico sem erro.

A conversa não avança quando eu movo o deal no HubSpot

Causa: por padrão, cada linha de mapeamento é Nuvia → HubSpot, ou seja, só o sentido de saída.

Como resolver: na aba Funis, mude a coluna Direção daquela etapa para ↔ Bidirecional (equivale a ligar o Hubspot → Nuvia da linha). A conversa também precisa estar vinculada a um deal.

Erros do HubSpot e o que fazer