API pública de leads: OAuth2 i exemples

Portal Hero llança un nou endpoint a la seva API pública que permet als dealers rebre leads des de qualsevol font externa directament al seu CRM. Formularis web, landing pages, campanyes de Google Ads, integracions amb tercers... tots els leads centralitzats en un sol lloc.

Per al negoci: tots els teus leads en un sol lloc

Fins ara, els leads que arribaven al teu CRM de Portal Hero provenien exclusivament de les converses als marketplaces on publiques els teus productes. El sistema els detectava automàticament i els convertia en oportunitats de venda.

Amb el nou endpoint d'ingesta de leads, aquesta limitació desapareix. Ara pots connectar qualsevol font de captació de clients amb el teu CRM de Portal Hero:

• Formulari de contacte a la teva web: cada enviament crea automàticament un lead al teu CRM amb les dades del client i el producte que li interessa.
• Landing pages de campanyes de Google Ads: configura un webhook que en rebre un formulari enviï les dades directament a Portal Hero.
• Eines d'automatització (Zapier, Make, n8n): connecta qualsevol font de leads amb un simple connector HTTP.
• Centralització total: sense importar d'on vingui el lead, tots es gestionen des del mateix panell.

El resultat és una visió completa de totes les teves oportunitats de venda, sense haver d'alternar entre plataformes ni perdre leads pel camí.

Sense duplicats, sense complicacions

L'endpoint és intel·ligent: si un client ja existeix al teu CRM (identificat pel seu telèfon o email), no se'n crea un de nou. Si ja té una oportunitat de venda oberta, els nous productes s'afegeixen a aquesta oportunitat existent. I si un producte ja hi estava associat, simplement s'ignora. Tot això passa de forma automàtica, sense que t'hagis de preocupar de duplicats.

Per al desenvolupador: guia d'integració

L'endpoint està disponible a l'API pública de Portal Hero. A continuació tens tot el necessari per integrar-lo.

Autenticació

L'API fa servir OAuth2 amb Bearer token. Primer obtén un token amb les credencials del compte 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

Amb el token, ja pots enviar leads al CRM. El body té tres camps principals:

• customer (obligatori): dades del client. Es requereix almenys phone o email.
• items (opcional): array de productes del catàleg referenciats pel seu external_id.
• source (opcional): origen del lead (per exemple "web_form", "google_ads"). Per defecte és "api".

Si el compte té múltiples botigues, afegeix el query param user_id per indicar a quina 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"
}'

Resposta

L'API retorna un JSON amb el resultat de l'operació, indicant si s'ha creat un client nou o s'ha reutilitzat un d'existent, i el mateix amb l'oportunitat de venda:

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

Comportament idempotent

• Si el client (per telèfon o email) ja existeix, es reutilitza.
• Si ja té una oportunitat de venda oberta, s'afegeixen els items a l'existent.
• Si un item ja és a l'oportunitat, s'ignora sense error.
• Items amb external_id no trobat al catàleg se salten amb warning, sense que falli la request.

Exemple complet: de token a lead

Aquest és el flux complet per obtenir un token i crear un lead des d'un formulari web:

Pas 1: Obtenir el token d'accés

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"

Pas 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"
}'

Pas 3: Verificar al dashboard

Accedeix al CRM de Portal Hero i comprova que el lead apareix amb les dades del client i el producte associat. Si el client ja existia, veuràs el producte afegit a la seva oportunitat oberta.

Si necessites ajuda amb la integració o tens dubtes sobre algun cas d'ús, el nostre equip de suport tècnic està a la teva disposició.