Een eigen integratie bouwen met de Leat API

Heb je een API-sleutel nodig voor een systeem dat in de Marketplace staat, zoals een kassa, kiosk, webshop of e-mailtool? Maak dan geen privé-app aan. Installeer die integratie en maak de sleutel daar aan. Zie Waar je je API-sleutel of toegangstoken vindt, en voor een kassa Een kassa en toegangstoken aanmaken per kassa.

Leat heeft een openbare REST API die met dezelfde data werkt als het dashboard: contacten, punten, tiers, beloningen, vouchers, cadeaukaarten, bestellingen, vestigingen en meer. De volledige referentie staat op docs.leat.com/v3.

Doet geen van de kant-en-klare integraties in de Marketplace wat je nodig hebt? Dan bouw je het zo zelf, of laat je het een ontwikkelaar bouwen.

Wat je ermee kunt bouwen

Wat teams vaak op de API bouwen:

• Een kassa of kassasysteem dat niet in onze lijst met integraties staat, zodat je personeel bij het afrekenen een contact kan opzoeken en punten kan toekennen.
• Een zelfbedieningskiosk waar contacten zich identificeren en een beloning verzilveren.
• Een app voor bestellen aan tafel of een bestelapp die promoties en vouchers toepast.
• Een website of webshop die een contact zijn saldo laat zien en beloningen laat claimen.
• Interne tools: contacten aanmaken vanuit een systeem dat je al gebruikt, of loyaliteitstransacties naar je eigen rapportages halen.

De documentatie heeft onder Tutorials stapsgewijze handleidingen voor een kassasysteem, een kiosk en bestellen aan tafel.

Een privé-app en een persoonlijk toegangstoken aanmaken

Elk verzoek wordt geauthenticeerd met een persoonlijk toegangstoken, en een token hoort bij een privé-app in je account:

1. Ga in het dashboard naar Apps en dan naar Integraties.
2. Klik op de pagina Marketplace rechtsboven op Maak een privé-app.
3. Geef de app de naam van het systeem dat je koppelt en klik op Aanmaken.
4. Open het tabblad Auth en klik op Maak een personal access token aan.
5. Kies een geldigheid: nooit verlopen, 1 maand, 1 jaar, 2 jaar of 3 jaar.
6. Kopieer het token meteen. Het wordt maar één keer getoond en is later niet meer op te halen.

Geef elk systeem dat je koppelt een eigen privé-app. Zo zie je wat er gekoppeld is, en als je één token roteert of verwijdert, blijft de rest werken. Op het tabblad Auth kun je een token later roteren: het oude token blijft dan nog 14 dagen werken, of het vervalt meteen.

Je eerste verzoek versturen

Stuur het token mee als bearer-token in de Authorization-header:

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

Alle endpoints staan onder https://api.leat.com/api/v3/oauth/clients/.

Wat de API omvat

De referentie groepeert de endpoints per onderwerp:

• Contacten, hun attributen, identifiers, inschrijvingen en verificatie.
• Het loyaliteitsprogramma: kredietontvangsten, loyaliteitstransacties, tiers, eenheden en voordelen.
• Beloningen, spaarbare beloningen, beloningsontvangsten, promoties, vouchers en referrals.
• Cadeaukaartprogramma's, cadeaukaarten, cadeaukaarttransacties en prepaidtransacties.
• Bestellingen, retouren, producten, categorieën, vestigingen, kassatransacties, bezoeken en boekingen.
• Diensten, diensttypes en dienstteams.
• Formulieren, automatiseringen, aangepaste attributen, de brand kit, het contactportaal en portal sessions.

Meldingen krijgen met webhooks

In plaats van de API steeds te vragen of er iets veranderd is, laat je ons jou aanroepen. Open je privé-app, ga naar het tabblad Webhooks en klik op Nieuwe webhook: kies de gebeurtenis, geef hem een naam en vul de URL aan jouw kant in.

Gebeurtenissen zijn onder meer contact_created, contact_updated, tier_reached, credit_reception_created, giftcard_transaction_created, voucher_redeemed, reward_redeemed, order_created, visit_created, form_submission_completed en referral_completed.

Een webhook die je daar aanmaakt, stuurt altijd een array met gebeurtenissen, tot 100 per verzoek, en elk verzoek is ondertekend. Houd daar vanaf het begin rekening mee. Webhooks: gebeurtenissen van Leat naar je eigen systeem sturen heeft de volledige lijst met gebeurtenissen, de payload, hoe je de handtekening controleert en wat er gebeurt als je endpoint niet antwoordt.

Gebruik een webhookabonnement in plaats van de Webhook-actie in een automatisering. De webhook van een automatisering is niet ondertekend en wordt niet opnieuw geprobeerd.

Testen zonder je data te vervuilen

Er is geen aparte sandbox: je test tegen de live-omgeving. Maak een apart account aan om te testen, zodat testdata buiten je echte dashboard blijft, en gebruik daarbij geen echte e-mailadressen van contacten. Staan er in dat account automatiseringen of campagnes aan, dan gaan die e-mails echt de deur uit.

Fouten

Een verzoek dat mislukt, komt terug met statuscode 400 en altijd dezelfde vorm:

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

Elk endpoint in de referentie noemt de fouten die het kan teruggeven, en de pagina Error handling heeft de volledige lijst op één plek.

Een vliegende start in PHP

Bouw je in PHP? Dan is er een SDK die je binnenhaalt met composer require piggy/piggy-php-sdk, zodat je de HTTP-laag niet zelf hoeft te schrijven.

Als je de Register API gebruikt

De oudere Register API wordt uitgefaseerd. Persoonlijke toegangstokens werken nu ook op de v3-routes, dus er is geen reden meer om een apart token te hebben. Bestaande Register API-endpoints blijven voorlopig werken, maar bouw alles wat nieuw is op v3 en plan de overstap voor wat je al hebt.

Hulp krijgen

Mail je vragen over de API naar partners@leat.com. We reageren meestal binnen een dag, en we kunnen je ook toevoegen aan een Slack-kanaal met het ontwikkelteam, wat tijdens kantooruren meestal sneller is. Vraag er per e-mail om.