Integração HubSpot

O MIDDAG Account integra-se ao HubSpot como camada de CRM. O HubSpot acompanha o processo comercial -- negócios, cotações, contatos e empresas. Faturamento e pagamento acontecem no WooCommerce e no Stripe. O HubSpot acompanha receita, não transações.

Arquitetura de conta dupla

Conta	Entidade jurídica	Mercado	Moeda
HubSpot BR	MIDDAG Tecnologia LTDA	Brasil	BRL
HubSpot LLC	MIDDAG, LLC	Internacional	USD

Cada conta possui seu próprio token de acesso, portal ID e endpoint de webhook. A mesma organização cliente pode existir em ambos os HubSpots, vinculada através do registro de Organização do plugin.

Configuração

Credenciais da API

Configure no seu ambiente ou wp-config.php:

Variável	Descrição
HUBSPOT_BR_ACCESS_TOKEN	Token de acesso do HubSpot BR
HUBSPOT_BR_PORTAL_ID	Portal ID do HubSpot BR
HUBSPOT_LLC_ACCESS_TOKEN	Token de acesso do HubSpot LLC
HUBSPOT_LLC_PORTAL_ID	Portal ID do HubSpot LLC

Endpoints de webhook

Registre estas URLs no HubSpot em Settings > Integrations > Webhooks:

Conta	URL do Webhook
HubSpot BR	https://seusite.com/wp-json/middag-account/v1/webhooks/hubspot/br
HubSpot LLC	https://seusite.com/wp-json/middag-account/v1/webhooks/hubspot/llc

Pipelines de negócios

Configure estes pipelines em cada conta HubSpot:

Pipeline	Canal	Fluxo
self-serve	WooCommerce / Stripe	Automático: compra aciona negócio como closed-won
consultative	Gerenciado no HubSpot	Manual: representante comercial gerencia etapas
renewal	Automático	Automático: eventos de renovação atualizam negócios
upsell	Gerenciado no HubSpot	Manual: equipe de CS gerencia oportunidades de upgrade

Mapeamento Organização-para-Empresa

Cada organização no plugin armazena dois IDs de empresa do HubSpot:

Campo	Descrição
hubspot_company_id_br	ID da empresa no HubSpot BR
hubspot_company_id_global	ID da empresa no HubSpot LLC

O plugin é o ponto de deduplicação. Quando o mesmo cliente existe em ambos os HubSpots, o único registro de Organização contém ambos os IDs de empresa.

Fonte da verdade por campo

A sincronização acontece no nível do campo, não no nível da entidade. Cada campo possui um proprietário definido:

Dado	Fonte da verdade	Direção
Campos da organização	Plugin	Plugin para HubSpot
Negócios e etapas do pipeline	HubSpot	HubSpot para Plugin
Status da cotação (aceita/paga)	Plugin	Plugin para HubSpot
Dados de criação da cotação	HubSpot	HubSpot para Plugin
Dados comerciais do contato	HubSpot	HubSpot para Plugin
Status do pedido/pagamento	Plugin	Plugin para HubSpot

Quando um conflito é detectado (campo editado em ambos os sistemas), o plugin vence para dados da organização. Uma trilha de auditoria registra o campo, valor antigo, valor novo e qual fonte prevaleceu.

Fluxo de cotação

O ciclo de vida da cotação abrange ambos os sistemas:

Cada cotação pertence a uma entidade de faturamento (BR ou Global). A sincronização direciona para a conta HubSpot correta.

Eventos de webhook

Negócios

Evento	Ação do plugin
deal.creation	Registrar oportunidade localmente
deal.propertyChange (stage)	Atualizar etapa, valor e data de fechamento local
deal.deletion	Marcar negócio como removido

Cotações

Evento	Ação do plugin
quote.creation	Criar Cotação (status: draft)
quote.propertyChange	Atualizar cotação local
quote.deletion	Marcar cotação como cancelada

Contatos

Evento	Ação do plugin
contact.creation	Criar ou atualizar contato vinculado
contact.propertyChange	Atualizar dados do contato
contact.deletion	Desativar contato

Propriedades customizadas do HubSpot

As seguintes propriedades customizadas devem ser criadas nos produtos do HubSpot para sincronização correta:

Propriedade	Origem	Finalidade
middag_sku	SKU do produto	Vincula produto HubSpot ao YAML
middag_tier	Nível do produto	Relatórios por nível de funil
middag_entitlement_class	Classe de entitlement	Roteamento de provisionamento
middag_billing_model	Modelo de faturamento	Classificação do tipo de receita
middag_brand	Marca	Relatórios multi-marca

Serviços sincronizados

A integração utiliza sete classes de serviço, migradas do tema original:

Serviço	Função
CompanyService	Sincronizar Organização com Empresa do HubSpot
ContactService	Sincronizar Colaborador com Contato do HubSpot
DealService	Ler negócios do HubSpot para exibição no admin
QuoteService	Sincronização bidirecional de cotações
AssociationService	Vincular registros de empresa, contato e negócio
SearchService	Buscar empresas e contatos no HubSpot
LineItemService	Sincronizar itens de linha da cotação

Isolamento de negócios

Negócios no HubSpot BR permanecem no HubSpot BR. Negócios no HubSpot LLC permanecem no HubSpot LLC. Não há sincronização cruzada entre contas. O plugin lê negócios de ambas as contas para exibição na interface admin (somente leitura).

Solução de problemas

Sintoma	Causa provável	Correção
Organização não sincronizando	ID de empresa do HubSpot ausente	Verifique se a organização possui um ID de empresa definido
Status da cotação não atualizando	Válidação de assinatura do webhook	Confirme se o segredo HMAC está correto por conta
Contatos duplicados no HubSpot	Deduplicação não executando	Verifique se a organização vincula ambas as contas
Dados de negócio desatualizados	Endpoint de webhook não registrado	Registre o endpoint nas configurações do HubSpot