API pubblica dei lead: OAuth2 ed esempi

Portal Hero lancia un nuovo endpoint nella sua API pubblica che permette ai dealer di ricevere lead da qualsiasi fonte esterna direttamente nel proprio CRM. Moduli web, landing page, campagne di Google Ads, integrazioni con terze parti... tutti i lead centralizzati in un unico posto.

Per l'attività: tutti i tuoi lead in un unico posto

Finora, i lead che arrivavano al tuo CRM di Portal Hero provenivano esclusivamente dalle conversazioni sui marketplace dove pubblichi i tuoi prodotti. Il sistema li rilevava automaticamente e li convertiva in opportunità di vendita.

Con il nuovo endpoint di ingestione dei lead, questo limite scompare. Ora puoi collegare qualsiasi fonte di acquisizione di clienti con il tuo CRM di Portal Hero:

• Modulo di contatto sul tuo sito web: ogni invio crea automaticamente un lead nel tuo CRM con i dati del cliente e il prodotto che gli interessa.
• Landing page di campagne di Google Ads: configura un webhook che, alla ricezione di un modulo, invii i dati direttamente a Portal Hero.
• Strumenti di automazione (Zapier, Make, n8n): connetti qualsiasi fonte di lead con un semplice connettore HTTP.
• Centralizzazione totale: indipendentemente da dove provenga il lead, tutti si gestiscono dallo stesso pannello.

Il risultato è una visione completa di tutte le tue opportunità di vendita, senza dover passare da una piattaforma all'altra né perdere lead per strada.

Senza duplicati, senza complicazioni

L'endpoint è intelligente: se un cliente esiste già nel tuo CRM (identificato dal suo telefono o email), non ne viene creato uno nuovo. Se ha già un'opportunità di vendita aperta, i nuovi prodotti si aggiungono a quell'opportunità esistente. E se un prodotto era già associato, viene semplicemente ignorato. Tutto questo avviene in modo automatico, senza che tu debba preoccuparti dei duplicati.

Per lo sviluppatore: guida all'integrazione

L'endpoint è disponibile nell'API pubblica di Portal Hero. Di seguito trovi tutto il necessario per integrarlo.

Autenticazione

L'API usa OAuth2 con Bearer token. Per prima cosa ottieni un token con le credenziali dell'account 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"
}

Inviare un lead

Con il token, puoi già inviare lead al CRM. Il body ha tre campi principali:

• customer (obbligatorio): dati del cliente. È richiesto almeno phone o email.
• items (opzionale): array di prodotti del catalogo referenziati tramite il loro external_id.
• source (opzionale): origine del lead (ad esempio "web_form", "google_ads"). Per impostazione predefinita è "api".

Se l'account ha più negozi, aggiungi il query param user_id per indicare a quale inviare il 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"
}'

Risposta

L'API restituisce un JSON con il risultato dell'operazione, indicando se è stato creato un nuovo cliente o ne è stato riutilizzato uno esistente, e lo stesso con l'opportunità di vendita:

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

Comportamento idempotente

• Se il cliente (per telefono o email) esiste già, viene riutilizzato.
• Se ha già un'opportunità di vendita aperta, gli items si aggiungono a quella esistente.
• Se un item è già presente nell'opportunità, viene ignorato senza errore.
• Gli items con external_id non trovato nel catalogo vengono saltati con warning, senza che la request fallisca.

Esempio completo: dal token al lead

Questo è il flusso completo per ottenere un token e creare un lead da un modulo web:

Passo 1: Ottenere il token di accesso

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: Inviare il 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: Verificare nel dashboard

Accedi al CRM di Portal Hero e verifica che il lead appaia con i dati del cliente e il prodotto associato. Se il cliente esisteva già, vedrai il prodotto aggiunto alla sua opportunità aperta.

Se hai bisogno di aiuto con l'integrazione o hai dubbi su qualche caso d'uso, il nostro team di supporto tecnico è a tua disposizione.