Eine eigene Integration mit der Leat API bauen

Sie brauchen einen API-Schlüssel für ein System, das im Marktplatz steht, etwa eine Kasse, einen Kiosk, einen Webshop oder ein E-Mail-Tool? Dann erstellen Sie keine Private App. Installieren Sie diese Integration und erstellen Sie den Schlüssel dort. Siehe Wo Sie Ihren API-Schlüssel oder Ihr Zugriffstoken finden, und für eine Kasse Eine Kasse und ein Zugangstoken für jede Kasse erstellen.

Leat hat eine öffentliche REST API, die mit denselben Daten arbeitet wie das Dashboard: Kontakte, Punkte, Stufen, Belohnungen, Vouchers, Geschenkkarten, Bestellungen, Geschäfte und mehr. Die vollständige Referenz finden Sie unter docs.leat.com/v3.

Wenn keine der fertigen Integrationen im Marktplatz das kann, was Sie brauchen, bauen Sie es auf diese Weise selbst oder geben es an eine Entwicklerin oder einen Entwickler weiter.

Was Sie damit bauen können

Was Teams häufig mit der API bauen:

• Eine Kasse, die nicht in unserer Integrationsliste steht, damit Ihr Personal an der Kasse einen Kontakt findet und Punkte vergibt.
• Ein Selbstbedienungs-Kiosk, an dem sich Kontakte identifizieren und eine Belohnung einlösen.
• Eine Bestell-App oder eine Bestellung am Tisch, die Aktionen und Vouchers anwendet.
• Eine Website oder ein Webshop, der einem Kontakt sein Guthaben zeigt und ihn Belohnungen einlösen lässt.
• Interne Tools: Kontakte aus einem System anlegen, das Sie bereits nutzen, oder Treuetransaktionen in Ihr eigenes Reporting holen.

Die Dokumentation enthält unter Tutorials Schritt-für-Schritt-Anleitungen für eine Kasse, einen Kiosk und die Bestellung am Tisch.

Eine Private App und ein persönliches Zugriffstoken erstellen

Jede Anfrage wird mit einem persönlichen Zugriffstoken authentifiziert, und ein Token gehört zu einer Private App in Ihrem Konto:

1. Gehen Sie im Dashboard zu Apps und dann zu Integrationen.
2. Klicken Sie auf der Seite Marktplatz oben rechts auf Private App erstellen.
3. Benennen Sie sie nach dem System, das Sie verbinden, und klicken Sie dann auf Erstellen.
4. Öffnen Sie den Tab Authentifizierung und klicken Sie auf Persönlichen Zugriffstoken erstellen.
5. Wählen Sie eine Gültigkeitsdauer: nie ablaufend, 1 Monat, 1 Jahr, 2 Jahre oder 3 Jahre.
6. Kopieren Sie das Token sofort. Es wird nur einmal angezeigt und kann später nicht mehr abgerufen werden.

Geben Sie jedem System, das Sie verbinden, eine eigene Private App. So sehen Sie, was verbunden ist, und wenn Sie ein Token rotieren oder löschen, fällt nichts anderes aus. Auf dem Tab Authentifizierung können Sie ein Token später rotieren: Entweder funktioniert das alte noch 14 Tage weiter, oder es läuft sofort ab.

Ihre erste Anfrage senden

Senden Sie das Token als Bearer-Token im Authorization-Header:

curl https://api.leat.com/api/v3/oauth/clients/contacts \
  -H "Authorization: Bearer {{ access_token }}"

Alle Endpunkte liegen unter https://api.leat.com/api/v3/oauth/clients/.

Was die API abdeckt

Die Referenz gruppiert die Endpunkte nach Thema:

• Kontakte, ihre Attribute, Identifier, Abonnements und Verifizierung.
• Das Treueprogramm: Punktegutschriften, Treuetransaktionen, Stufen, Einheiten und Vorteile.
• Belohnungen, sammelbare Belohnungen, Belohnungseinlösungen, Aktionen, Vouchers und Empfehlungen.
• Geschenkkartenprogramme, Geschenkkarten, Geschenkkartentransaktionen und Prepaid-Transaktionen.
• Bestellungen, Retouren, Produkte, Kategorien, Geschäfte, Kassentransaktionen, Besuche und Buchungen.
• Schichten, Schichttypen und Schichtteams.
• Formulare, Automatisierungen, benutzerdefinierte Attribute, das Brand Kit, das Kontaktportal und Portalsitzungen.

Mit Webhooks benachrichtigt werden

Statt die API regelmäßig nach Änderungen abzufragen, lassen Sie sich von uns benachrichtigen. Öffnen Sie Ihre Private App, gehen Sie zum Tab Webhooks und klicken Sie auf Neuer Webhook: Wählen Sie das Ereignis, geben Sie einen Namen ein und tragen Sie die URL auf Ihrer Seite ein.

Zu den Ereignissen gehören contact_created, contact_updated, tier_reached, credit_reception_created, giftcard_transaction_created, voucher_redeemed, reward_redeemed, order_created, visit_created, form_submission_completed und referral_completed.

Ein dort erstellter Webhook sendet immer ein Array von Ereignissen, bis zu 100 pro Anfrage, und jede Anfrage ist signiert. Bauen Sie von Anfang an dafür. Webhooks: Ereignisse aus Leat an Ihr eigenes System senden enthält die vollständige Liste der Ereignisse, das Payload, die Prüfung der Signatur und was passiert, wenn Ihr Endpunkt nicht antwortet.

Nutzen Sie ein Webhook-Abonnement statt der Aktion Webhook in einer Automatisierung. Der Webhook einer Automatisierung ist weder signiert noch wird er wiederholt.

Testen, ohne Ihre Daten durcheinanderzubringen

Es gibt keine separate Sandbox: Sie testen in der Live-Umgebung. Legen Sie ein eigenes Konto zum Testen an, damit Testdaten nicht in Ihrem echten Dashboard landen, und verwenden Sie dabei keine echten E-Mail-Adressen von Kontakten. Wenn in diesem Konto Automatisierungen oder Kampagnen aktiv sind, werden diese E-Mails tatsächlich versendet.

Fehler

Eine fehlgeschlagene Anfrage kommt mit Statuscode 400 und jedes Mal derselben Struktur zurück:

{
    "message": "<message>",
    "code": <code>,
    "status_code": 400
}

Jeder Endpunkt in der Referenz listet die Fehler auf, die er zurückgeben kann, und die Seite Error handling enthält die vollständige Liste an einer Stelle.

Ein schneller Start in PHP

Wenn Sie in PHP entwickeln, gibt es ein SDK, das Sie mit composer require piggy/piggy-php-sdk einbinden können, damit Sie die HTTP-Schicht nicht selbst schreiben müssen.

Wenn Sie die Register API nutzen

Die ältere Register API wird schrittweise abgeschaltet. Persönliche Zugriffstokens funktionieren jetzt auch auf den v3-Routen, es gibt also keinen Grund mehr für ein separates Token. Bestehende Register-API-Endpunkte funktionieren vorerst weiter, aber bauen Sie alles Neue auf v3 und planen Sie, Bestehendes umzustellen.

Hilfe bekommen

Schreiben Sie bei Fragen zur API an partners@leat.com. Wir antworten in der Regel innerhalb eines Tages und können Sie auch in einen Slack-Kanal mit dem Entwicklungsteam aufnehmen, was während der Geschäftszeiten meist schneller geht. Fragen Sie per E-Mail danach.