> ## 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.
# Página de Formulários: sincronizar formulários HubSpot
> Consulte os formulários HubSpot acompanhados pelo Flowella, veja o estado de sincronização de cada WhatsApp Flow com o Meta e acione uma nova sincronização.
A página Formulários mostra todos os formulários HubSpot que o Flowella está a seguir para a sua organização, o WhatsApp Flow que o Flowella construiu a partir de cada um deles e se esse Fluxo está em sincronia com o Meta.
Para saber como configurar a integração do HubSpot em primeiro lugar, consulte [Configuração do HubSpot](/pt/hubspot/setup). Esta página abrange o ecrã **Formulários** da aplicação, não a configuração da integração.
## Como abrir
Aceda a **Formulários** na navegação à esquerda, ou:
```text theme={null}
/{org}/forms
```
Também é possível abrir Formulários com escopo para um canal específico no `/{org}/{waba}/{phone}/forms`. A lista é a mesma - o escopo do canal é usado quando você sincroniza um Fluxo com o Meta.
## O que a lista mostra
Cada linha representa um formulário HubSpot. As colunas incluem:
* **Nome do formulário** e um ID de formulário HubSpot truncado com um botão de cópia com um clique.
* Contagem de campos\*\* - quantos campos o formulário tem, com um sinalizador se algum não for suportado.
* Última modificação no HubSpot\*\* - extraído do próprio HubSpot do `updatedAt` para que possa saber quando a definição do formulário foi alterada.
* **Catalog updated** - quando o Flowella actualizou pela última vez a definição do formulário a partir do HubSpot.
* Status do WhatsApp Flow\*\* - sincronizado, rascunho ou obsoleto (o HubSpot foi alterado desde a última sincronização).
* **Criar WhatsApp Flow / Sincronizar WhatsApp Flow** - a ação principal. A etiqueta muda para **Sync** quando um Fluxo já existe e para **Stale - Sync needed** quando o formulário HubSpot foi editado desde a última sincronização.
O botão é **pré-desativado** com uma dica de ferramenta quando não pode ser executado - por exemplo: HubSpot não ligado, nenhum canal WhatsApp ativo, faturação inativa, ou o formulário contém tipos de campos não suportados. A dica de ferramenta explica exatamente qual o pré-requisito em falta.
Se a sua conta HubSpot ainda não tiver formulários sincronizados, o Flowella **bootstraps o catálogo automaticamente** na primeira visita, para que não tenha de ativar um pull inicial.
Pode filtrar e pesquisar a lista para encontrar rapidamente um formulário específico.
## Detalhe do formulário
Clique numa linha para abrir a respectiva página de detalhes. O cabeçalho de detalhe mostra a mesma ação primária **Criar / Sincronizar WhatsApp Flow** que a linha da lista, para que não tenha de voltar atrás para fazer alterações. A partir da página de detalhes, é possível:
* Rever o mapeamento campo a campo entre o formulário HubSpot e o WhatsApp Flow.
* Ver as **execuções de sincronização** anteriores - quando cada uma foi iniciada, o estado (em fila de espera, em execução, bem sucedida, falhada) e quaisquer erros devolvidos pelo Meta.
* Acione uma nova sincronização, **repetir** uma execução com falha ou **cancelar** uma sincronização que ainda está em andamento.
* Abrir o Fluxo correspondente no Meta Business Suite.
## Sincronizando um formulário para um WhatsApp Flow
Ao clicar em **Criar WhatsApp Flow** ou **Sincronizar WhatsApp Flow**, o Flowella:
1. Executa uma **verificação prévia** - confirma que o HubSpot está ligado, o canal ativo é verificado, o formulário tem pelo menos um campo suportado e a faturação está ativa.
2. Lê a definição de formulário mais recente do HubSpot.
3. Gera o JSON equivalente do WhatsApp Flow.
4. Carrega-o para o Meta no canal que selecionou (channel-scoped).
5. Regista a execução de sincronização na página de detalhes.
A maioria das sincronizações demora alguns segundos. Se o Meta rejeitar o Fluxo, o motivo da falha aparece na linha de execução como uma **mensagem de erro segura para o utilizador** (traduzida do Gráfico do Meta) - normalmente devido a um tipo de campo não suportado, a um problema de verificação no canal ou a uma incompatibilidade de categoria. Tente novamente a partir da mesma linha quando tiver corrigido a causa.
## Gating por escopo de canal
Os formulários são **abrangentes à organização na lista**, mas **têm escopo de canal quando sincroniza** — um Fluxo tem de ser carregado para uma combinação específica de WABA + número de telefone.
| URL que abre | O que acontece |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/{org}/forms` | Lista todos os formulários que o Flowella segue. Se estiver ligado exatamente **um** canal WhatsApp, o Flowella utiliza-o automaticamente quando sincroniza. Com mais do que um canal, é necessário abrir Formulários num escopo de canal antes de sincronizar. |
| `/{org}/{waba}/{phone}/forms` | A mesma lista, mas as sincronizações têm como alvo este canal diretamente. A página **espera que o ID do canal no URL seja resolvido** antes de executar as suas consultas ao HubSpot, para que não veja um esqueleto a piscar com resultados do canal errado quando o canal em cache na sessão está desactualizado. |
Se clicar em **Sincronizar** a partir do URL abrangente à organização e o Flowella não conseguir decidir que canal utilizar (nenhum canal ligado, vários canais sem escopo definido ou uma sessão entre organizações desactualizada), o botão permanece pré-desativado com uma dica de ferramenta a explicar o que falta. Mude para o canal correto a partir do [alternador de canais](/pt/essentials/multi-channel#mudanca-de-canal), ou abra `/{org}/{waba}/{phone}/forms` diretamente.
## UX de erros de sincronização
Quando uma sincronização falha, o Flowella transforma a linha da execução num único botão de ação delineado para que possa corrigir avançando a partir da mesma linha:
| Estado da execução | Botão | O que faz |
| --------------------- | -------------------- | ------------------------------------------------------------------------------------------ |
| Falhou | **Tentar novamente** | Volta a colocar na fila a mesma sincronização do formulário. |
| Em fila / em execução | **Cancelar** | Remove o trabalho na medida do possível e marca a execução como **`FLOW_SYNC_CANCELLED`**. |
| Nunca sincronizado | **Criar** | Executa a primeira sincronização para este formulário. |
A linha também transporta um **emblema de erro seguro para o utilizador**:
* **`FLOW_SYNC_PREFLIGHT` + erro Meta `#133010`** (telefone não registado) — o emblema mostra a mensagem armazenada do Meta e uma sugestão de **registo do telefone**, e não um genérico "não pronto". Conclua o registo do telefone em **Definições → Meta** e tente novamente.
* **`QUEUE_FAILED`** — a fila de sincronização não conseguiu pegar no trabalho. Normalmente transitório; tente novamente. Se persistir, a página de estado da plataforma é o próximo local a verificar (consulte [Estado e incidentes](/pt/essentials/status-and-incidents)).
* **`validation_errors` do Meta** — o emblema resume que campos o Meta rejeitou, para que possa ajustar o formulário HubSpot (ou o mapeamento de campos) e tentar novamente sem sair da linha.
O histórico de execuções é preservado entre as tentativas, para que possa ver quantas tentativas um formulário levou e o que mudou entre elas.
## As submissões de Flow ficam associadas ao contacto HubSpot inscrito
Quando um WhatsApp Flow é enviado a partir de um fluxo de trabalho HubSpot, a Flowella passa agora o id do contacto HubSpot inscrito através do Flow e inclui-o como `hs_object_id` quando a submissão é escrita de volta no HubSpot. Isto faz com que a submissão fique associada ao **contacto exato que o HubSpot inscreveu** — e não a um registo semelhante — mesmo quando o número de telefone corresponde a vários contactos, e elimina o último caso em que a pesquisa por telefone no HubSpot podia recair sobre o registo errado.
Se a sua organização já tem Flows publicados, **volte a sincronizar cada Flow uma vez** para que o novo campo oculto seja incluído no JSON do Flow carregado no Meta:
Aceda a **Formulários** e abra qualquer formulário cujo WhatsApp Flow tenha sido criado antes desta alteração.
Clique em **Sincronizar WhatsApp Flow** na linha (ou na ação principal da página de detalhes). A Flowella volta a carregar o JSON do Flow para o Meta com o campo oculto do id de contacto.
Só os formulários enviados a partir de fluxos de trabalho HubSpot precisam disto. Formulários enviados fora do contexto de um fluxo de trabalho não são afetados.
Os Flows criados ou sincronizados após a correção já incluem o campo, pelo que não é necessária qualquer ação para novos Flows.
## Texto da pergunta em blocos de rich text
O HubSpot permite colocar um **elemento de rich text** acima de um grupo de campos, para que o texto da pergunta apareça por cima do input em vez de estar dentro do rótulo do campo. O Flowella mapeia esses blocos para o WhatsApp Flow juntamente com os inputs:
| Rich text do HubSpot | Componente do Flow |
| --------------------------------------- | -------------------------------- |
| Título `H1` | Text heading |
| Título `H2` ou `H3` | Text subheading |
| Parágrafo, lista ou outro texto corrido | Text body (com markdown ativado) |
O rich text aparece **antes** dos inputs no grupo de campos, para que os clientes vejam a pergunta e depois a respondam. Os rótulos dos campos continuam a ser apresentados na aplicação, por isso mantenha-os curtos — consulte [Boas práticas de design de formulários](/app/form-design-best-practices).
Se já tiver formulários HubSpot que usam rich text acima de grupos de campos, **re-sincronize-os** a partir da [página de detalhe do formulário](#detalhe-do-formulário). Execuções de sincronização mais antigas só recolhiam os rótulos dos campos, pelo que o texto da pergunta em rich text ficava em falta no Flow publicado até voltar a sincronizar.
Um ecrã de WhatsApp Flow pode conter no máximo **50 componentes**. Em formulários muito grandes, o Flowella mantém todos os inputs e descarta blocos de rich text a partir do final do ecrã para se manter abaixo do limite — os inputs nunca são removidos, mas parte do texto da pergunta pode não aparecer. Divida o formulário por vários ecrãs (ou em dois formulários) se precisar que todo o texto seja apresentado.
## Dados de amostra
Se ainda não tiver uma ligação ao HubSpot, a página Formulários é apresentada com **linhas ilustrativas** por detrás de um texto explicativo "Dados de amostra". Ligue o HubSpot para mudar para os seus formulários reais.
Os formulários HubSpot com tipos de campo não suportados (carregamento de ficheiros, assinatura) não podem ser sincronizados tal como estão. Ajuste o formulário no HubSpot ou ignore esses campos no WhatsApp Flow.
## Relacionado
Ligar o portal a partir do qual o Flowella lê os formulários.
Desencadear fluxos a partir de um fluxo de trabalho HubSpot.
Receitas de ponta a ponta que combinam formulários, modelos e fluxos de trabalho.
Diagnosticar problemas de sincronização de formulários e envios em falta.
Os formulários são sincronizados por canal - entenda o escopo.
Como os envios de formulários são encriptados em trânsito e em repouso.