Health API / Enrollment / PetLove Endpoints

2.1 O que viabiliza este fluxo

O middleware e um servico Node.js/Express controlado por nos. Nao depende de nenhum recurso especial do HubSpot — precisa apenas da API padrao do CRM (qualquer plano com acesso a API).

Capacidades do middleware:

• 4 endpoints REST proprios — recebe POST do site PetLove (wizard, checkout, ativacao)
• Chamadas ilimitadas para APIs externas (Enrollment API, Health API, HubSpot)
• Sem limite de tempo de execucao — pode processar logica complexa (simulate, proposal, MRR)
• Fila propria (Bull/Redis ou SQS) com retry, Dead Letter Queue, idempotencia
• Codigo versionado em Git — testavel, debugavel, auditavel
• DataSanitizer para CPF — intercepta e remove antes de enviar ao HubSpot
• EnrollmentService: client dedicado para toda a Enrollment API PetLove

2.2 Passo a passo (explicacao simplificada)

PASSO 1    Lead entra no site PetLove e completa o WIZARD
           (escolhe especie, raca, plano, preenche dados pessoais)
           ↓
PASSO 2    SITE faz POST /api/wizard para o Middleware
           ↓
PASSO 3    Middleware recebe e faz:
           a) Cria Contact no HubSpot (upsert por email, sanitiza CPF)
           b) Cria Pet (Custom Object: nome, especie, raca)
           c) Cria Deal (negocio) + Line Items (plano + preco)
           d) Cria Associations v4: Contact↔Deal, Pet↔Contact, Pet↔Deal
           e) Dispara evento: lead_wizard_gerado
           ↓
PASSO 4    Lead confirma e vai para CHECKOUT
           SITE faz POST /api/checkout para o Middleware
           ↓
PASSO 5    Middleware recebe e faz:
           a) Chama Enrollment API → POST /proposal/simulate → precos reais
           b) Atualiza Deal (stage, amount, MRR)
           c) Chama Enrollment API → POST /proposal → cria proposta
           d) Dispara evento: venda_concluida
           ↓
PASSO 6    Apos pagamento, lead preenche ATIVACAO
           SITE faz POST /api/ativacao/dados-pet e POST /api/ativacao/microchip
           ↓
PASSO 7    Middleware recebe e faz:
           a) Atualiza Pet com dados complementares e microchip
           b) Atualiza Deal → stage: Ativo
           c) Dispara evento: ativacao_concluida
           ↓
PASSO 8    HUBSPOT tem tudo: contato, pet, negocio, eventos, vendedor.

1. Fase 1 — Wizard (Lead)

O lead completa o formulario do site: nome, email, telefone, CEP, especie, raca, plano desejado. O site envia tudo em um POST /api/wizard para o middleware. O middleware cria Contact (upsert por email), Pet (Custom Object), Deal (stage: Lead), Line Items (plano + preco), todas as Associations v4, e dispara o evento lead_wizard_gerado que aparece na timeline do contato.

2. Fase 2 — Checkout (Venda)

O lead confirma o plano e vai para checkout. O site envia POST /api/checkout. O middleware chama a Enrollment API: primeiro /proposal/simulate para calcular precos reais (descontos, parcelas, addons), depois /proposal para submeter a proposta (com seller.sourceSellerId = ID do vendedor no HubSpot e source = 'Hubspot'). Atualiza Deal com amount, MRR e stage 'Proposta Enviada'. Dispara venda_concluida.

3. Fase 3 — Ativacao

Apos pagamento, o lead preenche dados complementares do pet e define microchip. Dois sub-endpoints: POST /api/ativacao/dados-pet (atualiza Pet Custom Object) e POST /api/ativacao/microchip (atualiza Pet + muda Deal para 'Ativo'). Dispara eventos: ativacao_iniciada, microchip_escolhido, ativacao_concluida.

2.3 Diagrama

                POST /api/wizard                    API CRM v3
 _______________  POST /api/checkout   _______________   _______________
|               | POST /api/ativacao/*|               | |               |
| SITE PETLOVE  | ==================>| MIDDLEWARE    | |   HUBSPOT     |
| (frontend)    |                    | (Node.js)     |==>   CRM        |
|_______________|                    |               | |               |
                                     | - Valida dados| |  - Contact    |
                                     | - Upsert Cont.| |  - Deal       |
                                     | - Create Pet  |====>  - Pet (CO)    |
                                     | - Create Deal |   |  - Line Items |
                                     | - MRR calc    |   |  - Events     |
                                     | - CPF sanit.  |   |  - Assoc v4   |
                                     | - Events disp.|   |  - Owner      |
                                     |_______________|   |_______________|
                                           ||
                                     ______||______
                                    |              |
                                    | ENROLLMENT   |
                                    | API PetLove  |
                                    | (host ?)     |
                                    |______________|

2.4 Quem faz o que

2.5 Pros

• Funciona com QUALQUER plano HubSpot (nao precisa Operations Hub)
• Sem limite de timeout — pode fazer simulate + proposal + MRR em sequencia
• EnrollmentService dedicado: pode chamar 6 endpoints com retry/backoff
• Fila propria com retry, Dead Letter Queue, idempotencia
• DataSanitizer garante que CPF NUNCA chega ao HubSpot (compliance)
• Codigo versionado em Git, com unit tests, CI/CD, logging
• Custom Object Pet criado com schema controlado (especie, raca, microchip)
• 6 server-side events na timeline do contato (visibilidade total)
• Toda a logica em UM lugar — facil de debugar e auditar

2.6 Contras

• Precisa construir e manter um servico — middleware (infra + deploy + monitoramento)
• Desenvolvimento mais demorado: ~42 dias uteis para o Dominio A completo
• Pipeline CI/CD, logging, alertas, healthcheck necessarios
• Equipe Epic responsavel pela manutencao do codigo (updates, bug fixes)
• Depende da URL da Enrollment API (bloqueio D1) para Fase 2 e Integracao

3.1 O que o HubSpot oferece que viabiliza este fluxo

Tres capacidades do HubSpot permitem eliminar o middleware:

1. HubSpot Forms / Submit API

O site pode enviar dados do wizard diretamente para o HubSpot usando HubSpot Forms (embedded ou popup) ou a Forms Submit API (POST server-side). Quando o form e submetido, o HubSpot cria ou atualiza o Contact automaticamente e pode disparar um Workflow.

• Cria Contact automaticamente no submit (upsert por email)
• Dispara Workflow automaticamente apos submit
• Captura qualquer campo custom (especie, raca, plano, CEP)
• Funciona com HubSpot Forms gratuito (form embed) ou Marketing Hub (submit API)

2. Custom Code Actions (codigo serverless dentro do Workflow)

Dentro de um Workflow, e possivel rodar codigo Node.js ou Python como serverless function. O Custom Code pode chamar APIs externas (Enrollment API, Health API) e a API do HubSpot internamente.

• Chamar Enrollment API: simulate, proposal, proposal/{id}
• Chamar Health API: plans, regions, species (dados de referencia)
• Usar @hubspot/api-client para criar Deal, Pet (CO), Line Items, Associations
• Guardar secrets (tokens) em variaveis de ambiente seguras

3. Workflow Actions nativas

Alem do Custom Code, o Workflow oferece acoes nativas que substituem parte do que o middleware faria: criar Deal, criar associacao, definir propriedades, enviar notificacao, criar task.

• Create Deal (acao nativa do Workflow)
• Set Property em Contact, Deal, Custom Object
• Create Association entre objetos
• Send internal notification / Create task

3.2 Passo a passo (explicacao simplificada)

PASSO 1    Lead entra no site PetLove e completa o WIZARD
           (escolhe especie, raca, plano, preenche dados pessoais)
           ↓
PASSO 2    SITE submete um HubSpot Form (embed ou API submit)
           → HUBSPOT cria/atualiza o Contact automaticamente
           ↓
PASSO 3    WORKFLOW dispara (trigger: form submitted)
           ↓
PASSO 4    CUSTOM CODE #1 (Node.js) roda:
           a) Le dados do Contact (especie, raca, plano, CEP)
           b) Cria Pet (Custom Object) via @hubspot/api-client
           c) Cria Deal + Line Items
           d) Cria Associations v4
           ↓
PASSO 5    Lead confirma checkout (outro form submit ou webhook)
           ↓
PASSO 6    CUSTOM CODE #2 (Node.js) roda:
           a) Chama Enrollment API: simulate → precos reais
           b) Chama Enrollment API: proposal → cria proposta
           c) Atualiza Deal (stage, amount, MRR)
           ↓
PASSO 7    Apos pagamento, lead preenche ativacao (outro form/webhook)
           ↓
PASSO 8    CUSTOM CODE #3 (Node.js) roda:
           a) Atualiza Pet (dados complementares + microchip)
           b) Atualiza Deal → stage: Ativo
           ↓
PASSO 9    HUBSPOT tem tudo: contato, pet, negocio, vendedor.

1. Fase 1 — Wizard via HubSpot Form

O site da PetLove usa um HubSpot Form (embedded ou via Submit API) em vez de chamar o middleware. O form coleta: nome, email, telefone, CEP, especie, raca, plano desejado. Ao submeter, o HubSpot cria/atualiza o Contact automaticamente. Um Workflow e triggered pelo form submit.

2. Custom Code cria Pet + Deal + Associations

Dentro do Workflow, um bloco de Custom Code (Node.js) le os dados do Contact e usa @hubspot/api-client para criar: Pet (Custom Object), Deal (stage: Lead), Line Items (plano + preco), Associations v4 (Contact↔Deal, Pet↔Contact, Pet↔Deal). Tudo acontece dentro dos 20 segundos de timeout.

3. Checkout via Custom Code + Enrollment API

Quando o lead vai para checkout (outro submit ou webhook), um segundo Custom Code chama a Enrollment API via axios: POST /proposal/simulate (precos reais), depois POST /proposal (submete proposta). Atualiza o Deal com amount, MRR e stage. ATENCAO: simulate + proposal + update Deal precisam caber em 20 segundos.

4. Ativacao via Custom Code

Apos pagamento confirmado, o lead preenche ativacao. Um terceiro Custom Code atualiza Pet (dados complementares + microchip) e muda Deal para 'Ativo'.

3.3 Limitacoes deste fluxo

3.4 Diagrama

              HubSpot Form / Submit API
 _______________                         _________________________________
|               |                       | HUBSPOT (Operations Hub)        |
| SITE PETLOVE  | =====================>|                                 |
| (frontend)    |                       | 1. Form submit → Create Contact |
|_______________|                       | 2. Workflow triggered            |
                                        |    3. Custom Code #1:           |
                                        |       - @hubspot/api-client     |
 _______________                        |       - Pet, Deal, LI, Assoc v4 |
| ENROLLMENT   |                        |    4. Custom Code #2 (checkout):|
| API PetLove  | <==== axios =========|       - Enrollment: simulate    |
| (host ?)     |                        |       + proposal                |
|______________|                        |       - Update Deal (MRR,stage) |
                                        |    5. Custom Code #3 (ativacao):|
 _______________                        |       - Update Pet (microchip)  |
| HEALTH API   |                        |       - Update Deal → Ativo    |
| (publico)    | <==== axios =========|                                 |
|______________|                        | Resultado: Contact+Deal+Pet+LI  |
                                        |_________________________________|

3.5 Quem faz o que

3.6 Pros

• Zero middleware — sem nenhum servidor externo para construir ou manter
• Contact criado automaticamente pelo HubSpot Forms (upsert nativo)
• Logica de negocio visivel no HubSpot UI (Workflow visual)
• Workflow actions nativas disponiveis (send email, create task, notify)
• Custom Code pode chamar Enrollment API, Health API e HubSpot internamente
• Desenvolvimento mais rapido: ~20-30 dias uteis (sem middleware para construir)
• Sem deploy, sem CI/CD, sem monitoramento de servidor — menos operacional

3.7 Contras

• REQUER Operations Hub Professional — verificar se PetLove ja tem
• Timeout de 20 segundos por Custom Code — checkout precisa caber nesse tempo
• Memoria limitada a 128 MB por execucao
• CPF sanitization precisa ser feita manualmente no Custom Code (risco maior)
• Server-side events customizados consomem parte do timeout
• Sem DLQ dedicada — retry e do HubSpot (3 dias, sem visibilidade granular)
• Custom Code NAO e versionado em Git (edicao no HubSpot UI)
• Se Enrollment API demorar >10s, o Custom Code pode estourar
• Mudancas exigem edicao no HubSpot (nao e deploy de codigo)

5.1 Health API — endpoints publicos (sem autenticacao)

Host: https://health-api.petlove.com.br — Cloudflare + Laravel + Envoy. Requer User-Agent (ex: PostmanRuntime/7.36.0).

5.2 Health API — endpoints hook (requerem token)

5.3 Enrollment API — 6 endpoints (host desconhecido)

6.1 Customer → Contact HubSpot

6.2 Pet → Custom Object Pet HubSpot

6.3 Proposal Status → Deal Stage HubSpot

6.4 Proposal (body para simulate/submit)

7.1 Custom Object: Pet (schema)

7.2 Associations v4

7.3 Server-Side Events (Events API v3)

9.1 Bloqueios criticos (impedem desenvolvimento)

9.2 GAPs (definicoes pendentes)