1API-sleutel aanmaken

Ga naar Account › API-sleutels en maak een nieuwe sleutel aan. Geef hem een naam die aangeeft waar hij voor wordt gebruikt (bijv. "Zapier" of "Kassasysteem"). De sleutel wordt precies één keer getoond — sla hem op voordat je het venster sluit.

Naar Account › API-sleutels

2Authenticatie

Voeg bij elk API-verzoek de sleutel toe als Authorization-header:

Authorization: Bearer <jouw-api-sleutel>

Test of de sleutel werkt door je profiel op te vragen:

curl https://valucher.com/api/v1/me \
  -H "Authorization: Bearer <jouw-api-sleutel>"

Een succesvolle respons heeft HTTP 200 met je gebruikersgegevens en de lijst van organisaties waarbij je bent aangesloten.

3Organisatie-ID ophalen

Het aanmaken en oplijsten van kaarten vereist een X-Organisation-Id-header, zodat de API weet onder welke organisatie de kaart hoort. Acties op een bestaande kaart (uitgeven, inwisselen, opvragen) hebben de header niet nodig — de kaart is al aan een organisatie gekoppeld. Je vindt je organisatie-ID's in de respons van GET /me:

curl https://valucher.com/api/v1/me \
  -H "Authorization: Bearer <jouw-api-sleutel>" \
  | jq '.data.organisations[] | {id, name}'

Sla het ID op voor stap 4. In de onderstaande voorbeelden staat 42 als voorbeeld.

4Kaart aanmaken

Een Valucher wordt aangemaakt als concept (issued: false). Je bepaalt zelf wanneer je hem uitgeeft (stap 5), zodat je hem eerst kunt controleren of de klantgegevens kunt koppelen.

curl -X POST https://valucher.com/api/v1/vouchers \
  -H "Authorization: Bearer <jouw-api-sleutel>" \
  -H "X-Organisation-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "10 lessen Yoga — Jan de Vries",
    "unit_name": "les",
    "unit_amount": 10,
    "unit_value": 9.50,
    "reference": "KLANT-1234"
  }'

De respons bevat de nieuwe kaart met zijn unieke code (8 tekens, bijv. TGD596BC). Die code heb je nodig voor stappen 5, 6 en 7.

5Kaart uitgeven

Uitgeven activeert de kaart en trekt credits af van je saldo (kosten = unit_amount × unit_value in euro's). Na het uitgeven is de kaart zichtbaar op valucher.com/code/<code> en kan hij worden ingewisseld. De organisatie wordt automatisch bepaald vanuit de kaart — geen header nodig.

curl -X POST https://valucher.com/api/v1/vouchers/TGD596BC/issue \
  -H "Authorization: Bearer <jouw-api-sleutel>"

6Strip inwisselen

Wissel één of meer strippen in wanneer de klant gebruik maakt van de kaart. De description verschijnt in de gebruikshistorie op de kaart. De organisatie wordt automatisch bepaald vanuit de kaart — geen header nodig.

curl -X POST https://valucher.com/api/v1/vouchers/TGD596BC/redeem \
  -H "Authorization: Bearer <jouw-api-sleutel>" \
  -H "Content-Type: application/json" \
  -d '{
    "units": 1,
    "description": "Les dinsdag 01-07-2026"
  }'

7Kaart opvragen

Haal de actuele stand van een kaart op, inclusief gebruikshistorie en resterende strippen. De organisatie wordt automatisch bepaald vanuit de kaart — geen header nodig.

curl https://valucher.com/api/v1/vouchers/TGD596BC \
  -H "Authorization: Bearer <jouw-api-sleutel>"

Relevante velden in de respons:

Foutcodes

Alle foutresponsen hebben HTTP 4xx en bevatten een error.code-veld: