NL/EN
Aanmelden

Introductie

SDK's & integraties

Officiële clientbibliotheken voor de Puntjes API. Ze halen je OAuth2-tokens op en vernieuwen ze, proberen een call veilig opnieuw met een idempotency key, geven je getypeerde fouten terug en lopen je pagina's af. In je integratie schrijf je dus je eigen logica en geen HTTP-afhandeling.

Officiële pakketten

PakketVoorVereist
puntjes/php-sdkElke PHP-applicatie: WooCommerce/WordPress-plugins, kassakoppelingen, cronjobsPHP 8.1+
puntjes/laravelLaravel-applicatiesPHP 8.2+, Laravel 11–13

puntjes/laravel is een dunne laag bovenop de core SDK: configuratie, een facade en een token store in je cache, zodat je applicatie één token grant per uur doet in plaats van één per request.

Beide pakketten staan op Packagist, volgen SemVer en zijn stabiel op v1.0.0. Pin met ^1.0: fixes en nieuwe endpoints komen vanzelf binnen, en een breaking change wacht op 2.0.0.

Een klant registreren

De identifiers-array accepteert email en loyalty_card, en je mag ze volledig weglaten zodat Puntjes zelf de kaart uitgeeft. Dat is de kortste juiste oproep en wat de meeste integraties willen.

Stuur je wel een loyalty_card mee, dan moet die waarde een kaart zijn die de handelaar heeft laten drukken en nog aan niemand gaf. Zie Klant-endpoints.

Op puntjes/php-sdk onder 1.0.0 werkt geen van beide: de oproep zonder kaart wordt geweigerd voor er een request vertrekt, en de SDK kent geen loyalty_card als identifiertype. Werk bij in plaats van eromheen.

Gewoon PHP (elk framework)

composer require puntjes/php-sdk

De SDK praat PSR-18 en gebruikt de HTTP-client die je project al heeft. Heb je er geen:

composer require guzzlehttp/guzzle

Maak je credentials aan in het beheerportaal (zie API-clients beheren). Het secret zie je één keer.

use Puntjes\Puntjes;
use Puntjes\Request\SubmitTransaction;

$puntjes = Puntjes::make(
    clientId:     getenv('PUNTJES_CLIENT_ID'),
    clientSecret: getenv('PUNTJES_CLIENT_SECRET'),
    baseUrl:      'https://puntjes.app/api/v1',
);

// Een klant scant zijn kaart aan de kassa.
$customer = $puntjes->customers->lookup(identifier: $scannedCard);

echo $customer->walletBalance;

// Registreer de aankoop. Bedragen zijn in centen.
$transaction = $puntjes->transactions->submit(new SubmitTransaction(
    identifier:     $scannedCard,
    totalAmount:    4200,
    idempotencyKey: 'order-'.$orderId,
));

echo $transaction->pointsEarned;

De SDK regelt de authenticatie: ze haalt bij de eerste call een client_credentials-token op, houdt het in cache tot het vervalt, en haalt zonder iets te zeggen één keer een nieuw token op als de API het oude afwijst.

Laravel

composer require puntjes/laravel

PUNTJES_CLIENT_ID=your-client-id
PUNTJES_CLIENT_SECRET=your-client-secret
PUNTJES_BASE_URL=https://puntjes.app/api/v1

Meer is er niet aan. Laravel vindt de service provider en de facade vanzelf, en de tokens staan in de cache store van je applicatie.

use Puntjes\Laravel\Facades\Puntjes;
use Puntjes\Request\SubmitTransaction;

$customer = Puntjes::customers()->lookup(identifier: $card);

Puntjes::transactions()->submit(new SubmitTransaction(
    identifier:     $card,
    totalAmount:    $order->total_cents,
    idempotencyKey: 'order-'.$order->id,
));

Je kunt Puntjes\Puntjes ook uit de container injecteren in plaats van de facade te gebruiken. Zie de README van het pakket voor configuratieopties, eigen HTTP-clients en testadvies.

WordPress / WooCommerce

Bouw rechtstreeks op puntjes/php-sdk: het heeft bewust geen harde dependency op Guzzle of op een framework, dus je kunt het veilig in een plugin meeleveren. Twee dingen tellen zodra je die plugin verdeelt:

  1. Scope je dependencies met PHP-Scoper of Strauss, zodat je gebundelde bibliotheken niet kunnen botsen met andere plugins in het gedeelde WordPress-proces.
  2. Bewaar tokens in een transient, zodat niet elke paginalading een token grant doet. De SDK-README bevat een kant-en-klare TransientTokenStore-implementatie en de volledige richtlijnen.

Wat de SDK voor je afhandelt

  • Tokens: ophalen, cachen en opnieuw ophalen van client_credentials-tokens, met een token store die je per platform zelf invult.
  • Veilige retries: reads en idempotente writes gaan opnieuw de deur uit met exponential backoff. De SDK maakt de idempotency key zelf aan en stuurt bij elke nieuwe poging dezelfde mee, zodat een opnieuw verstuurde POST /transactions nooit twee keer punten toekent. Requests zonder die bescherming probeert ze nooit uit zichzelf opnieuw.
  • Getypeerde fouten: elke foutcode komt terug als een getypeerde exception, met de machineleesbare code, de HTTP-status en de request_id erbij. Bij een rate limit staat retryAfter() klaar.
  • Paginering: een gepagineerd endpoint geeft een lazy iterator terug, die een pagina pas ophaalt wanneer je ze nodig hebt:
foreach ($puntjes->products->list() as $product) {
    // pagina's worden opgehaald wanneer nodig
}

Andere talen

Alleen PHP heeft vandaag een officiële SDK. Vanuit elke andere taal werk je rechtstreeks tegen de REST API. Elk endpoint is gewone JSON over OAuth2, en de referentiepagina's in deze documentatie beschrijven de vorm van elke request en elke response.

Volgende
Klanten