Aan de slag - Puntjes Docs

Integreer de Puntjes loyalty- en beloningen-API in je kassasysteem of applicatie.

Authenticatie

Stel je OAuth2 client credentials in en doe je eerste request met authenticatie.

Kernconcepten

Hoe klanten, wallets, verdienregels, beloningen en campagnes samenhangen.

API-referentie

Elk endpoint, met de vorm van elke request en elke response.

Foutafhandeling

Foutcodes, de response waarin ze aankomen, en hoe je ze opvangt.

Wat is Puntjes?

Puntjes is een platform voor loyalty en beloningen: een handelaar (een winkel, een zaak) voert er een loyaliteitsprogramma mee uit voor zijn klanten. Via de Puntjes API kan je kassasysteem:

Klanten registreren en opzoeken via klantenkaart of e-mail
Transacties vastleggen en automatisch punten toekennen op basis van instelbare verdienregels
Campagnes uitvoeren met puntenvermenigvuldigers tijdens promotieperiodes
Beloningen aanbieden die klanten kunnen inwisselen met hun opgespaarde punten
Walletsaldo's bijhouden met een volledig append-only-grootboek van alle puntenbewegingen

Snel aan de slag

1. Je client credentials ophalen

Bij je Puntjes-account hoort een OAuth2-client. Om te authenticeren heb je de client-ID en het client-secret nodig. Je beheert ze in het beheerportaal op /admin/api-clients.

2. Toegangstoken ophalen

Vraag een toegangstoken aan met de OAuth2 client credentials-flow:

curl -X POST https://puntjes.app/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=JOUW_CLIENT_ID \
  -d client_secret=JOUW_CLIENT_SECRET

De response bevat een access_token dat 60 minuten geldig blijft:

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJ0eXAiOiJKV1Q..."
}

3. Je eerste API-aanroep

Zoek een klant op met de identifier van zijn klantenkaart:

curl https://puntjes.app/api/v1/customers/lookup?identifier=K7M2QX4P \
  -H "Authorization: Bearer JOUW_ACCESS_TOKEN"

{
    "data": {
        "id": 1,
        "first_name": "Jan",
        "last_name": "De Vries",
        "email": "jan@example.com",
        "status": "active",
        "wallet_balance": 1500
    }
}

4. Een transactie indienen

Registreer een aankoop, dan kent Puntjes de punten vanzelf toe:

curl -X POST https://puntjes.app/api/v1/transactions \
  -H "Authorization: Bearer JOUW_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "K7M2QX4P",
    "idempotency_key": "order-2024-001",
    "total_amount": 2500,
    "description": "Lunchbestelling"
  }'

{
    "data": {
        "id": 42,
        "customer_id": 1,
        "total_amount": 2500,
        "points_earned": 25,
        "rules_applied": [{ "rule_id": 3, "rule_name": "Basistarief", "rule_type": "base_rate", "points_earned": 25 }]
    }
}

rules_applied-items dragen meer dan vier velden

Ingekort voor de leesbaarheid. Elk item draagt ook family, moment, campaign_version, suppressed_by, reason en line_breakdown: allemaal null voor een verdienregel, en gevuld voor een campagne. Zie Transactie-endpoints voor het volledige contract.

Bedragen zijn in centen

Alle geldbedragen in de API worden uitgedrukt in centen (eurocenten). Een total_amount van 2500 staat voor EUR 25,00. Puntensaldo's worden ook als gehele getallen opgeslagen.

Belangrijke concepten

Concept	Beschrijving
Handelaar	De winkel of zaak die via Puntjes een loyaliteitsprogramma uitvoert
Klant	Iemand die meedoet aan het loyaliteitsprogramma van een handelaar
Identifier	Een waarde waarmee je een klant terugvindt: zijn kaartcode of zijn e-mailadres
Wallet	Het puntensaldo van een klant, ondersteund door een append-only-grootboek
Verdienregel	Een regel die bepaalt hoeveel punten een transactie oplevert
Campagne	Een tijdgebonden promotie die verdiende punten vermenigvuldigt
Beloning	Een item (korting of product) dat een klant kan inwisselen met punten
Inwisseling	Een registratie van een klant die punten uitgeeft aan een beloning

Basis-URL

Alle endpoints staan onder:

https://puntjes.app/api/v1

Elke request draagt een Authorization: Bearer {token} header. Zie Authenticatie voor details.