API pública de leads: OAuth2 y ejemplos

Portal Hero lanza un nuevo endpoint en su API pública que permite a los dealers recibir leads desde cualquier fuente externa directamente en su CRM. Formularios web, landing pages, campañas de Google Ads, integraciones con terceros... todos los leads centralizados en un solo lugar.

Para el negocio: todos tus leads en un solo sitio

Hasta ahora, los leads que llegaban a tu CRM de Portal Hero provenían exclusivamente de las conversaciones en los marketplaces donde publicas tus productos. El sistema los detectaba automáticamente y los convertía en oportunidades de venta.

Con el nuevo endpoint de ingesta de leads, esa limitación desaparece. Ahora puedes conectar cualquier fuente de captación de clientes con tu CRM de Portal Hero:

• Formulario de contacto en tu web: cada envío crea automáticamente un lead en tu CRM con los datos del cliente y el producto que le interesa.
• Landing pages de campañas de Google Ads: configura un webhook que al recibir un formulario envíe los datos directamente a Portal Hero.
• Herramientas de automatización (Zapier, Make, n8n): conecta cualquier fuente de leads con un simple conector HTTP.
• Centralización total: sin importar de dónde venga el lead, todos se gestionan desde el mismo panel.

El resultado es una visión completa de todas tus oportunidades de venta, sin tener que alternar entre plataformas ni perder leads por el camino.

Sin duplicados, sin complicaciones

El endpoint es inteligente: si un cliente ya existe en tu CRM (identificado por su teléfono o email), no se crea uno nuevo. Si ya tiene una oportunidad de venta abierta, los nuevos productos se añaden a esa oportunidad existente. Y si un producto ya estaba asociado, simplemente se ignora. Todo esto ocurre de forma automática, sin que tengas que preocuparte de duplicados.

Para el desarrollador: guía de integración

El endpoint está disponible en la API pública de Portal Hero. A continuación tienes todo lo necesario para integrarlo.

Autenticación

La API usa OAuth2 con Bearer token. Primero obtén un token con las credenciales de la cuenta 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 un lead

Con el token, ya puedes enviar leads al CRM. El body tiene tres campos principales:

• customer (obligatorio): datos del cliente. Se requiere al menos phone o email.
• items (opcional): array de productos del catálogo referenciados por su external_id.
• source (opcional): origen del lead (por ejemplo "web_form", "google_ads"). Por defecto es "api".

Si la cuenta tiene múltiples tiendas, añade el query param user_id para indicar a cuál enviar el 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"
}'

Respuesta

La API devuelve un JSON con el resultado de la operación, indicando si se creó un cliente nuevo o se reutilizó uno existente, y lo mismo con la oportunidad de venta:

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

Comportamiento idempotente

• Si el cliente (por teléfono o email) ya existe, se reutiliza.
• Si ya tiene una oportunidad de venta abierta, se añaden los items a la existente.
• Si un item ya está en la oportunidad, se ignora sin error.
• Items con external_id no encontrado en el catálogo se saltan con warning, sin que falle la request.

Ejemplo completo: de token a lead

Este es el flujo completo para obtener un token y crear un lead desde un formulario web:

Paso 1: Obtener el token de acceso

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"

Paso 2: Enviar el 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"
}'

Paso 3: Verificar en el dashboard

Accede al CRM de Portal Hero y comprueba que el lead aparece con los datos del cliente y el producto asociado. Si el cliente ya existía, verás el producto añadido a su oportunidad abierta.

Si necesitas ayuda con la integración o tienes dudas sobre algún caso de uso, nuestro equipo de soporte técnico está a tu disposición.