Beloningen & Inwisselingen

Beloningen zijn wat je klanten met hun gespaarde loyaliteitspunten kunnen kopen. Besteedt een klant punten aan een beloning, dan legt Puntjes dat vast als een inwisseling, met een eigen bevestigingscode.

Beloningstypen

Korting

Korting in geld op een volgende aankoop:

Veld	Beschrijving
`discount_value`	Het kortingsbedrag
`discount_type`	`percent` (bv. 10% korting) of `fixed` (bv. EUR 5,00 korting)

Gratis product

Een gratis product of dienst:

Veld	Beschrijving
`product_reference`	Verwijzing naar het gratis product (die bepaal je zelf)

Beloningseigenschappen

Veld	Type	Beschrijving
`id`	integer	Uniek belonings-ID
`name`	string	Naam van de beloning
`description`	string	Omschrijving van de beloning
`type`	string	`discount` of `free_product`
`point_cost`	integer	Punten die het inwisselen kost
`total_stock`	integer	Totale voorraad (`null` = onbeperkt)
`remaining_stock`	integer	Voorraad die nog over is
`status`	string	`active` of `inactive`
`available_from`	datetime	Vanaf wanneer de beloning te krijgen is (optioneel)
`available_until`	datetime	Tot wanneer de beloning te krijgen is (optioneel)
`image_path`	string	De geüploade afbeelding van de beloning
`code_valid_for_hours`	integer	Hoeveel uur de bevestigingscode geldig blijft (optioneel)
`branches`	array\|null	De vestigingen waar klanten deze beloning kunnen inwisselen, elk `{ "external_id", "name", "type" }`. `null` betekent elke vestiging

Beschikbaarheid

Met available_from en available_until beperk je een beloning tot een periode. De API geeft alleen de beloningen terug die op dat moment lopen en nog voorraad hebben.

Inwisselproces

1. De klant kiest een beloning

Het kassasysteem toont de beloningen die te krijgen zijn en de klant kiest er een. Haal de actieve beloningen op met het beloningen-endpoint.

2. Dien een inwisseling in

POST /api/v1/redemptions

{
    "identifier": "CARD-001",
    "reward_id": 5,
    "idempotency_key": "redeem-2024-0042"
}

De API controleert:

of het walletsaldo van de klant volstaat
of de beloning actief en beschikbaar is
of er nog voorraad is
of de beloning de vestiging toestaat waar je de inwisseling boekt

Dankzij de idempotency_key kun je de aanroep gerust opnieuw sturen: dezelfde sleutel levert de oorspronkelijke inwisseling op, en schrijft geen punten een tweede keer af.

Waar de inwisseling plaatsvond

branch is je eigen sleutel voor de winkel: de external_id die je die vestiging gaf. De volgorde is dezelfde als bij een transactie: de sleutel in de payload wint, anders de standaardvestiging van de API-credential, anders geen vestiging. Een sleutel die bij geen van je vestigingen hoort, wordt geweigerd met BRANCH_NOT_FOUND (422). Zo gaat een typfout niet door voor een inwisseling zonder vestiging.

Een beloning die vestigingen noemt, kunnen klanten alleen daar inwisselen. Stuur je geen vestiging, of een vestiging die er niet bij staat, dan wordt de aanroep geweigerd met BRANCH_REQUIRED (422). Eén code voor allebei, want allebei hebben dezelfde oplossing: noem een vestiging die de beloning toestaat.

De vestiging wordt één keer vastgelegd. Stuur je dezelfde idempotency_key opnieuw, dan krijg je de oorspronkelijke inwisseling terug, met de vestiging van de eerste aanroep, ook als de herhaling een andere noemt.

3. De bevestigingscode komt terug

Lukt de aanroep, dan gaan de punten van de wallet van de klant af en krijg je een inwisseling terug met een bevestigingscode:

{
    "data": {
        "redemption_id": 12,
        "confirmation_code": "PNTJ-K4MP7QRS",
        "reward": {
            "name": "Gratis koffie",
            "type": "free_product"
        },
        "points_deducted": 500,
        "remaining_balance": 1000,
        "redeemed_at": "2024-03-15T12:30:00+00:00",
        "expires_at": "2024-03-15T14:30:00+00:00"
    }
}

4. Verifieer de inwisseling

Toont de klant de bevestigingscode, dan verifieer je die:

POST /api/v1/redemptions/{code}/verify

Daarmee gaat de inwisseling van pending naar verified.

Inwisselstatus

Status	Beschrijving
pending	Code uitgegeven, wacht op verificatie aan de kassa
verified	Code geverifieerd, beloning meegegeven

Hoe lang een bevestigingscode geldig is

Staat er op een beloning een code_valid_for_hours, dan verloopt de bevestigingscode na dat aantal uur. Daarna kun je hem niet meer verifiëren. Het veld expires_at in de response van de inwisseling zegt wanneer dat moment valt.

Inwisseling opzoeken

Je zoekt een inwisseling op met de bevestigingscode:

GET /api/v1/redemptions/{code}

Handig voor een kassasysteem dat de inwisseling eerst wil tonen en pas daarna verifieert.

Zie de endpoints voor inwisselen voor de volledige API-referentie.