HubSpot

Documentation Index

Fetch the complete documentation index at: https://docs.useaira.com/llms.txt

Use this file to discover all available pages before exploring further.

A integração com o HubSpot permite que seu time comercial mantenha o CRM como fonte de verdade dos dados de cliente e, ao fechar um deal, dispare automaticamente a criação do cliente, conta de pagamento e contrato correspondentes na Aira.

​

O que é possível

• Criar cliente, conta de pagamento e contrato na Aira a partir de um deal fechado no HubSpot
• Registrar expansões (novos produtos) em contratos já existentes
• Vincular registros entre os dois sistemas via externalId e contractId
• Anexar rastreabilidade de receita (proposta + data efetiva) por produto, quando o módulo está habilitado

​

Como funciona

​

Autenticação

curl -X POST https://api.useaira.com/v1/webhooks/hubspot/new-deal \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

​

Webhook: Novo deal

​

Corpo da requisição

{
  "customer": {
    "externalId": "hubspot_deal_12345",
    "name": "Empresa Exemplo Ltda",
    "customFields": {
      "segment": "enterprise"
    }
  },
  "paymentAccount": {
    "businessName": "Empresa Exemplo Ltda",
    "taxId": "12345678000190",
    "taxIdType": "cnpj",
    "emails": ["financeiro@empresaexemplo.com"]
  },
  "contract": {
    "startDate": "2026-05-01",
    "endDate": "2027-04-30",
    "rateAdjustmentIndex": "ipca",
    "customFields": {
      "sales_owner": "maria@useaira.com"
    }
  },
  "products": [
    {
      "productId": "7f3a5d2c-...-uuid",
      "revenueTraceability": [
        {
          "proposal": "PROP-2026-0042",
          "effectiveDate": "2026-05"
        }
      ]
    }
  ]
}

​

Campos

​

Comportamento

• Cliente com externalId já existente é reutilizado. Conta de pagamento com taxId já existente para o cliente também é reutilizada.
• O contrato é criado com alocação de 100% para a conta de pagamento informada.
• Ciclo de faturamento padrão: mensal, ancorado no primeiro dia do mês.
• Para cada produto, uma instância do plano mapeado é criada no contrato.
• Se o módulo de rastreabilidade de receita estiver habilitado, os itens de revenueTraceability são persistidos.

​

Webhook: Expansão

​

Corpo da requisição

{
  "contractId": "a1b2c3d4-...-uuid",
  "customerExternalId": "hubspot_deal_12345",
  "products": [
    {
      "productId": "9e8d7c6b-...-uuid",
      "revenueTraceability": [
        {
          "proposal": "PROP-2026-0088",
          "effectiveDate": "2026-07"
        }
      ]
    }
  ]
}

​

Campos

​

Comportamento

• Valida que o contractId existe e que o customerExternalId pertence ao cliente daquele contrato (caso contrário retorna 400 ou 404).
• Para cada produto: se o plano correspondente ainda não está no contrato, uma nova instância é criada. Produtos já presentes são ignorados.
• Itens de rastreabilidade de receita são deduplicados pela combinação contractId + productId + proposal + effectiveDate. Duplicatas são ignoradas silenciosamente.

​

Configuração

​

Erros comuns

​

Próximos passos

• Contratos — estrutura e ciclo de vida de contratos na Aira
• Clientes — modelo de clientes e uso do externalId
• Autenticação da API — como solicitar e usar API keys