API-overzicht

De Puntjes API is een RESTful JSON API. Elk endpoint verwacht een OAuth2 bearer token en geeft alleen de gegevens van de handelaar waarvoor dat token is uitgegeven.

---

Basis-URL

https://puntjes.app/api/v1

Alle endpoints in deze referentie staan onder deze basis-URL.

---

Requestformaat

• Gebruik Content-Type: application/json voor request bodies
• Stuur Authorization: Bearer {token} mee bij elk request (zie Authenticatie)
• Alle geldbedragen zijn in eurocenten (bv. 2500 = EUR 25,00)
• Alle puntwaarden zijn gehele getallen

---

Response-envelope

Elke geslaagde response zit in een data-envelope:

{
    "data": {
        "id": 1,
        "first_name": "Jan",
        "last_name": "De Vries"
    }
}

Gepagineerde endpoints bevatten paginering-metadata:

{
  "data": [...],
  "links": {
    "first": "...",
    "last": "...",
    "prev": null,
    "next": "..."
  },
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 72
  }
}

Volg links.next zoals je die krijgt. Die bevat de queryparameters die je zelf hebt meegestuurd (filters, sorteervolgorde en per_page), dus pagina 2 van een gefilterde lijst heeft hetzelfde filter als pagina 1. Bouw je de URL zelf op uit meta.current_page, dan raak je ze kwijt: een doorloop die met per_page=5 start, krijgt bij het tweede request stilzwijgend 15 rijen terug.

---

Foutresponses

Elke fout heeft dezelfde vorm:

{
    "error": {
        "code": "CUSTOMER_NOT_FOUND",
        "message": "No customer found with the given identifier.",
        "status": 404,
        "request_id": "550e8400-e29b-41d4-a716-446655440000"
    }
}

Validatiefouten (422) bevatten een details-veld:

{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "The given data was invalid.",
        "status": 422,
        "request_id": "...",
        "details": {
            "email": ["The email field must be a valid email address."],
            "identifiers.0.type": ["The identifier type must be one of: email, loyalty_card."]
        }
    }
}

Zie Foutafhandeling voor de volledige lijst met foutcodes.

---

Idempotentie

Elk endpoint dat punten verplaatst vereist een idempotency_key (max. 255 tekens). Stuur je een request opnieuw met een sleutel die je al gebruikt hebt, dan krijg je de oorspronkelijke resource terug en wordt er niets een tweede keer verwerkt. Deze aanroepen zijn dus veilig te herhalen na een netwerkfout of een time-out:

Endpoint	Sleutel uniek per	Wat een herhaling teruggeeft
POST /transactions	handelaar	De oorspronkelijke transactie; geen punten opnieuw toegekend
POST /redemptions	handelaar	De oorspronkelijke verzilvering; geen punten opnieuw afgeschreven, voorraad ongewijzigd
POST /customers/{customer}/wallet/adjust	wallet van de klant	De oorspronkelijke grootboekregel; saldo niet opnieuw verplaatst

Gebruik een waarde die de handeling in jouw eigen systeem aanwijst (een order-ID, of een UUID die je één keer per afrekening genereert en bij elke retry hergebruikt). Willekeurige waarden die bij elke poging veranderen maken idempotentie zinloos.

Dat vangt netwerkproblemen op, en kassasystemen die hetzelfde request twee keer versturen.

---

Overzicht van endpoints

Methode	Endpoint	Beschrijving
GET	/me	Branding van de handelaar ophalen
GET	/customers/lookup	Een klant opzoeken
POST	/customers	Een klant registreren
PUT PATCH	/customers/by-external-id/{externalId}	Een klant bijwerken
POST	/customers/link-external-id	Een external ID koppelen
POST	/customers/by-external-id/{externalId}/send-card	De klantenkaart versturen via je eigen id
POST	/customers/{customer}/send-card	De klantenkaart naar de klant sturen
GET	/customers/{customer}	Klantgegevens ophalen
POST	/transactions	Een transactie indienen
GET	/customers/{customer}/wallet	Wallet-saldo ophalen
GET	/customers/{customer}/ledger	Grootboekregels opvragen
GET	/customers/{customer}/wallet-pass	Een wallet-pas downloaden
GET	/customers/{customer}/transactions	Klanttransacties weergeven
POST	/customers/{customer}/wallet/adjust	Wallet-saldo aanpassen
GET	/campaigns	Campagnes weergeven
GET	/rewards	Beloningen weergeven
POST	/redemptions	Een beloning verzilveren
GET	/redemptions/{code}	Een verzilvering opzoeken
POST	/redemptions/{code}/verify	Een verzilvering verifiëren
POST	/vouchers/{code}/verify	Een bon verifiëren
GET	/products	Producten weergeven
POST	/products	Een product aanmaken
POST	/products/batch	Producten in bulk upserten
POST	/products/{externalId}/reward	Een beloning maken van een product
GET	/products/{externalId}	Een product ophalen
PUT	/products/{externalId}	Een product aanmaken of bijwerken (upsert)
PATCH	/products/{externalId}	Een product bijwerken
DELETE	/products/{externalId}	Een product verwijderen

---

Branding van de handelaar ophalen

GET /api/v1/me

Geeft de branding terug van de handelaar waar je token bij hoort. Kleur er een kassascherm of een webshopwidget mee zoals de klanten van die handelaar het al kennen, zonder per handelaar iets hard te coderen.

Example request

curl https://puntjes.app/api/v1/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
    "data": {
        "display_name": "Koffiebar De Hoek",
        "logo_url": "https://cdn.example.com/logo.png",
        "brand_color_primary": "#4F46E5",
        "brand_color_accent": "#06B6D4"
    }
}