API pública de leads: OAuth2 e exemplos

O Portal Hero lança um novo endpoint na sua API pública que permite aos dealers receber leads a partir de qualquer fonte externa diretamente no seu CRM. Formulários web, landing pages, campanhas de Google Ads, integrações com terceiros... todos os leads centralizados num só lugar.

Para o negócio: todos os teus leads num só sítio

Até agora, os leads que chegavam ao teu CRM do Portal Hero provinham exclusivamente das conversas nos marketplaces onde publicas os teus produtos. O sistema detetava-os automaticamente e convertia-os em oportunidades de venda.

Com o novo endpoint de ingestão de leads, essa limitação desaparece. Agora podes ligar qualquer fonte de captação de clientes ao teu CRM do Portal Hero:

• Formulário de contacto no teu site: cada envio cria automaticamente um lead no teu CRM com os dados do cliente e o produto que lhe interessa.
• Landing pages de campanhas de Google Ads: configura um webhook que, ao receber um formulário, envie os dados diretamente para o Portal Hero.
• Ferramentas de automatização (Zapier, Make, n8n): liga qualquer fonte de leads com um simples conector HTTP.
• Centralização total: independentemente de onde venha o lead, todos são geridos a partir do mesmo painel.

O resultado é uma visão completa de todas as tuas oportunidades de venda, sem teres de alternar entre plataformas nem perder leads pelo caminho.

Sem duplicados, sem complicações

O endpoint é inteligente: se um cliente já existe no teu CRM (identificado pelo seu telefone ou email), não se cria um novo. Se já tem uma oportunidade de venda aberta, os novos produtos são adicionados a essa oportunidade existente. E se um produto já estava associado, é simplesmente ignorado. Tudo isto acontece de forma automática, sem que tenhas de te preocupar com duplicados.

Para o programador: guia de integração

O endpoint está disponível na API pública do Portal Hero. De seguida tens tudo o que é necessário para o integrar.

Autenticação

A API usa OAuth2 com Bearer token. Primeiro obtém um token com as credenciais da conta Portal Hero:

curl -X POST https://public.api.portalhero.pro/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=tu_email@ejemplo.com" \
  -d "password=tu_contraseña"

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

Enviar um lead

Com o token, já podes enviar leads para o CRM. O body tem três campos principais:

• customer (obrigatório): dados do cliente. É necessário pelo menos phone ou email.
• items (opcional): array de produtos do catálogo referenciados pelo seu external_id.
• source (opcional): origem do lead (por exemplo "web_form", "google_ads"). Por defeito é "api".

Se a conta tiver múltiplas lojas, adiciona o query param user_id para indicar para qual enviar o lead.

curl -X POST https://public.api.portalhero.pro/leads \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
  "customer": {
    "phone": "+34612345678",
    "email": "cliente@example.com",
    "first_name": "Carlos",
    "last_name": "García"
  },
  "items": [
    { "external_id": "MOTO-001" }
  ],
  "source": "web_form"
}'

Resposta

A API devolve um JSON com o resultado da operação, indicando se foi criado um cliente novo ou reutilizado um existente, e o mesmo com a oportunidade de venda:

{
  "customer_id": 42,
  "opportunity_id": 15,
  "items_added": 1,
  "created_customer": true,
  "created_opportunity": true
}

Comportamento idempotente

• Se o cliente (por telefone ou email) já existe, é reutilizado.
• Se já tem uma oportunidade de venda aberta, os items são adicionados à existente.
• Se um item já está na oportunidade, é ignorado sem erro.
• Items com external_id não encontrado no catálogo são saltados com warning, sem que o request falhe.

Exemplo completo: do token ao lead

Este é o fluxo completo para obter um token e criar um lead a partir de um formulário web:

Passo 1: Obter o token de acesso

curl -X POST https://public.api.portalhero.pro/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=tu_email@ejemplo.com" \
  -d "password=tu_contraseña"

Passo 2: Enviar o lead

curl -X POST https://public.api.portalhero.pro/leads \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
  "customer": {
    "phone": "+34612345678",
    "email": "carlos.garcia@email.com",
    "first_name": "Carlos",
    "last_name": "García"
  },
  "items": [
    { "external_id": "MOTO-001" }
  ],
  "source": "web_form"
}'

Passo 3: Verificar no dashboard

Acede ao CRM do Portal Hero e verifica que o lead aparece com os dados do cliente e o produto associado. Se o cliente já existia, verás o produto adicionado à sua oportunidade aberta.

Se precisares de ajuda com a integração ou tiveres dúvidas sobre algum caso de uso, a nossa equipa de suporte técnico está à tua disposição.