> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Falhas de sincronização do HubSpot

> Diagnostique submissões HubSpot em falta, ações de fluxo paradas, envios de modelo suprimidos por deduplicação e propriedades que não chegam ao HubSpot.

A maioria dos problemas do HubSpot enquadra-se num destes três grupos: a **integração está desligada**, um **mapeamento de campo está errado** ou uma **ação de fluxo de trabalho está mal configurada**. Esta página analisa-os por ordem.

Para a configuração inicial, consulte [HubSpot setup](/pt/hubspot/setup). Para acções de fluxo de trabalho, consulte [Acções de fluxo de trabalho](/pt/hubspot/workflow-actions).

## 1. Verificar a ligação

<Steps>
  <Step title="Abrir Definições → HubSpot">
    A partir da aplicação Flowella, aceda a **Configurações → HubSpot**.
  </Step>

  <Step title="Ler o distintivo de estado">
    Um emblema verde **Ligado** significa que o token OAuth é válido. Uma faixa vermelha **Reconectar** significa que o token foi revogado ou expirou.
  </Step>

  <Step title="Voltar a ligar, se necessário">
    Clique em **Reconectar** e execute novamente o HubSpot OAuth. Em seguida, tente novamente a ação que falhou.
  </Step>
</Steps>

<Info>
  Causas comuns para o mau funcionamento de uma ligação HubSpot:

  * O utilizador HubSpot que autorizou o Flowella foi removido do portal.
  * O HubSpot rodou o token porque não tinha sido utilizado recentemente.
  * Um Super Admin desactivou a integração do Flowella nas definições da aplicação do HubSpot.
</Info>

## 2. Os envios de formulários não aparecem no HubSpot

Se um contacto completar um WhatsApp Flow mas não conseguir ver a submissão no HubSpot:

### Incompatibilidade no mapeamento de campos

O fluxo pode incluir um campo que não é mapeado para uma propriedade HubSpot de um tipo compatível. Abra o formulário na página [Forms](/pt/app/flows) e reveja o mapeamento de cada campo.

### O campo obrigatório está vazio

Se um campo do formulário HubSpot estiver marcado como obrigatório e o WhatsApp Flow permitir que o utilizador o ignore, a submissão será rejeitada pelo HubSpot. Tornar o campo opcional no HubSpot, ou obrigatório no Fluxo.

### Formato do número de telefone

O HubSpot é rigoroso quanto ao formato do número de telefone. Ver [Phone number format](/pt/hubspot/phone-number-format) - a maior parte dos problemas de "contacto em falta" resumem-se ao formato E.164 vs. nacional.

### A pesquisa ocorre após a execução da ação do fluxo de trabalho

Se o seu fluxo de trabalho HubSpot for executado imediatamente após a submissão do formulário, as condições de corrida podem fazer com que o fluxo de trabalho seja disparado antes de o Flowella ter terminado de escrever o contacto. Adicione um pequeno atraso (1-2 minutos) no início do fluxo de trabalho, ou dispare a alteração da propriedade do contacto em vez da submissão do formulário.

## 3. Acções de fluxo de trabalho paradas ou a falhar

Se um fluxo de trabalho HubSpot que inclui uma ação Flowella estiver bloqueado:

### Abrir o histórico de acções do fluxo de trabalho

No HubSpot, localize o contacto, desloque-se para **Histórico do fluxo de trabalho** e clique na execução que falhou. O HubSpot mostra a resposta que o Flowella devolveu para cada ação.

### Respostas de erro comuns

| Erro | O que fazer |
| - | - |
| `Channel not found` | O fluxo de trabalho aponta para um canal que não existe mais. Edite a ação e escolha um canal atual. Consulte [Multi-canal](/pt/essentials/multi-channel). |
| O modelo referenciado mudou de status para `REJECTED`, `PAUSED` ou `DISABLED`. Consulte [Template rejected](/pt/troubleshooting/template-rejected). | |
| `Contact opted out` | O contacto optou por sair deste canal. Honre o opt-out - não trabalhe em torno dele. |
| `Phone number invalid` | O telefone do contacto não está em E.164. Consulte [Formato do número de telefone](/pt/hubspot/phone-number-format). |
| `Subscription required` | O seu plano Flowella não inclui esta ação ou a sua subscrição expirou. Consulte [Faturação](/pt/account/billing). |
| `DUPLICATE_TEMPLATE_SEND_SUPPRESSED` | O mesmo modelo já tinha sido enviado ao mesmo número de telefone dentro da janela de deduplicação da Flowella. Trata-se de uma proteção intencional, não de uma falha de entrega. Consulte [Envio de modelo suprimido como duplicado](#template-send-suppressed-as-duplicate). |

### Template send suppressed as duplicate

Se o HubSpot mostrar uma ação **Enviar Modelo WhatsApp** concluída com o motivo de erro `DUPLICATE_TEMPLATE_SEND_SUPPRESSED`, a Flowella ignorou intencionalmente o envio porque o mesmo modelo já tinha sido enviado ao mesmo número de telefone dentro da sua janela de deduplicação.

O motivo mais comum é **dois contactos HubSpot partilharem um número de telefone** — por exemplo, um registo pessoal e um profissional, ou um agregado familiar com um único número WhatsApp — a serem inscritos no mesmo fluxo de trabalho com segundos de diferença. Apenas o primeiro envio segue para o WhatsApp; o segundo é suprimido para que o contacto não receba a mesma mensagem duas vezes.

Anteriormente, a segunda ação do fluxo de trabalho ficava em **Pendente** durante cerca de uma hora, até ao tempo limite do callback do HubSpot. A Flowella conclui agora o callback de imediato como falha, para que o contacto inscrito avance para o passo seguinte (ou para o ramo de "ação falhada") sem esperar.

**Como distinguir de uma falha real:**

* **Suprimido como duplicado** — o motivo de erro é exatamente `DUPLICATE_TEMPLATE_SEND_SUPPRESSED`. O modelo foi efetivamente enviado para esse número de telefone, apenas através de um contacto inscrito diferente. Não é necessária qualquer ação.
* **Falha real de envio** — o erro será um motivo específico, como `Template not approved`, `Phone number invalid`, `Contact opted out`, ou um código de erro do Meta Graph. Siga a linha correspondente da tabela acima.

Se precisar legitimamente de enviar o mesmo modelo ao mesmo número duas vezes (por exemplo, uma reconfirmação após um longo intervalo), espace as inscrições para além da janela de deduplicação ou utilize um modelo diferente.

### A ação existe mas não faz nada

Se o fluxo de trabalho for executado sem erros, mas não chegar nenhuma mensagem, verifique novamente:

* A ação está activada (não está em pausa).
* O destinatário está inscrito no fluxo de trabalho no passo correto.
* Os critérios de inscrição do HubSpot ainda correspondem ao contacto.

## 4. Confusão na direção da sincronização

A sincronização do Flowella é **bidirecional mas parcial**:

* Envios WhatsApp Flow → escrevem propriedades de contacto para o HubSpot.
* As acções de fluxo de trabalho do HubSpot → enviam mensagens e modelos do WhatsApp.
* Respostas de entrada do WhatsApp → registar na linha de tempo do contacto (não actualiza automaticamente as propriedades).

Se esperava que uma resposta WhatsApp de forma livre actualizasse uma propriedade, é necessário um passo extra da sua parte - um fluxo de trabalho HubSpot que observe o evento de conversação e analise a resposta, ou uma integração personalizada através da [API](/pt/api-reference/introduction).

## Ainda está preso?

<Note>
  Capture o seguinte antes de contactar o [suporte](https://flowella.io/support):

  * O carimbo de data e hora da **última sincronização** de **Configurações → HubSpot**
  * A mensagem de erro exacta (ou captura de ecrã) devolvida pelo Flowella ou HubSpot
  * O ID do contacto e o ID do fluxo de trabalho afectados
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.