Öffentliche Leads-API: OAuth2 und Beispiele

Portal Hero führt einen neuen Endpunkt in seiner öffentlichen API ein, der es Händlern ermöglicht, Leads aus jeder externen Quelle direkt in ihr CRM zu empfangen. Webformulare, Landingpages, Google-Ads-Kampagnen, Integrationen mit Drittanbietern... alle Leads an einem einzigen Ort zentralisiert.

Für das Geschäft: alle Ihre Leads an einem Ort

Bisher stammten die Leads, die in Ihr Portal-Hero-CRM gelangten, ausschließlich aus den Konversationen in den Marktplätzen, in denen Sie Ihre Produkte veröffentlichen. Das System erkannte sie automatisch und wandelte sie in Verkaufschancen um.

Mit dem neuen Endpunkt zur Lead-Erfassung verschwindet diese Einschränkung. Jetzt können Sie jede Quelle der Kundengewinnung mit Ihrem Portal-Hero-CRM verbinden:

• Kontaktformular auf Ihrer Website: Jede Übermittlung erstellt automatisch einen Lead in Ihrem CRM mit den Daten des Kunden und dem Produkt, das ihn interessiert.
• Landingpages von Google-Ads-Kampagnen: Konfigurieren Sie einen Webhook, der beim Empfang eines Formulars die Daten direkt an Portal Hero sendet.
• Automatisierungstools (Zapier, Make, n8n): Verbinden Sie jede Lead-Quelle mit einem einfachen HTTP-Konnektor.
• Vollständige Zentralisierung: Unabhängig davon, woher der Lead kommt, werden alle über dasselbe Panel verwaltet.

Das Ergebnis ist ein vollständiger Überblick über all Ihre Verkaufschancen, ohne zwischen Plattformen wechseln oder Leads unterwegs verlieren zu müssen.

Ohne Duplikate, ohne Komplikationen

Der Endpunkt ist intelligent: Wenn ein Kunde bereits in Ihrem CRM existiert (identifiziert durch seine Telefonnummer oder E-Mail), wird kein neuer erstellt. Wenn er bereits eine offene Verkaufschance hat, werden die neuen Produkte zu dieser bestehenden Chance hinzugefügt. Und wenn ein Produkt bereits zugeordnet war, wird es einfach ignoriert. All dies geschieht automatisch, ohne dass Sie sich um Duplikate kümmern müssen.

Für den Entwickler: Integrationsleitfaden

Der Endpunkt ist in der öffentlichen API von Portal Hero verfügbar. Nachfolgend finden Sie alles, was Sie für die Integration benötigen.

Authentifizierung

Die API verwendet OAuth2 mit Bearer-Token. Holen Sie zunächst ein Token mit den Zugangsdaten des Portal-Hero-Kontos:

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

Einen Lead senden

Mit dem Token können Sie nun Leads an das CRM senden. Der Body hat drei Hauptfelder:

• customer (erforderlich): Daten des Kunden. Mindestens phone oder email ist erforderlich.
• items (optional): Array von Katalogprodukten, referenziert über ihre external_id.
• source (optional): Herkunft des Leads (zum Beispiel "web_form", "google_ads"). Standardmäßig ist es "api".

Wenn das Konto mehrere Shops hat, fügen Sie den Query-Parameter user_id hinzu, um anzugeben, an welchen der Lead gesendet werden soll.

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

Antwort

Die API gibt ein JSON mit dem Ergebnis des Vorgangs zurück und gibt an, ob ein neuer Kunde erstellt oder ein bestehender wiederverwendet wurde, und ebenso bei der Verkaufschance:

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

Idempotentes Verhalten

• Wenn der Kunde (per Telefon oder E-Mail) bereits existiert, wird er wiederverwendet.
• Wenn er bereits eine offene Verkaufschance hat, werden die Items zur bestehenden hinzugefügt.
• Wenn ein Item bereits in der Chance ist, wird es ohne Fehler ignoriert.
• Items mit einer im Katalog nicht gefundenen external_id werden mit einer Warnung übersprungen, ohne dass die Anfrage fehlschlägt.

Vollständiges Beispiel: vom Token zum Lead

Dies ist der vollständige Ablauf, um ein Token zu erhalten und einen Lead aus einem Webformular zu erstellen:

Schritt 1: Das Zugriffstoken erhalten

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"

Schritt 2: Den Lead senden

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

Schritt 3: Im Dashboard überprüfen

Greifen Sie auf das Portal-Hero-CRM zu und prüfen Sie, dass der Lead mit den Daten des Kunden und dem zugeordneten Produkt erscheint. Wenn der Kunde bereits existierte, sehen Sie das Produkt zu seiner offenen Chance hinzugefügt.

Wenn Sie Hilfe bei der Integration benötigen oder Fragen zu einem Anwendungsfall haben, steht Ihnen unser technisches Support-Team zur Verfügung.