Een API-sleutel aanmaken

Een API is een deur aan de achterkant van je account. Waar jij in je beheerscherm klikt, kan een ander programma langs die deur rechtstreeks je gegevens ophalen: je producten, je prijzen, je vrije plaatsen, je verkoop.

Dat is handig wanneer je bijvoorbeeld:

• op je eigen website wil tonen welke rondleidingen er deze week nog plaats hebben;
• je boekhouder automatisch je omzetcijfers wil laten binnenhalen;
• je ledenlijst wil koppelen aan een ander programma.

Wie zo'n koppeling bouwt — je webbouwer, je boekhoudpakket, een vriend die kan programmeren — heeft twee dingen van je nodig: het adres en een sleutel. Allebei vind je op één scherm.

Goed om te weten: de API hoort bij een grotere formule. Zit je op een kleinere formule, dan staat API-toegang niet in je menu; kom je toch op het scherm terecht, dan zie je uitleg en een knop Naar Abonnement, en geen sleutels.

Waar je moet zijn

Open in het menu links Instellingen → API-toegang. Alleen de rol eigenaar ziet dit scherm.

Bovenaan staan twee tabbladen: Sleutels en Webhooks. Dit artikel gaat over het eerste; de webhooks staan in Webhooks instellen.

Op het tabblad Sleutels zie je drie blokken:

1. De koppeling — het adres en de technische beschrijving. Deze twee gegevens geef je door aan wie de koppeling bouwt.
2. Nieuwe sleutel — hier maak je er een aan.
3. Sleutels — wat er al bestaat, en wanneer het voor het laatst gebruikt is.

Een sleutel aanmaken

Stap 1. Geef een naam. Niet je eigen naam, maar de naam van wat er aan de andere kant hangt: "onze website", "boekhouding", "nieuwsbrief". Die naam is puur voor jezelf. Ze staat straks in de lijst, en bij "wanneer voor het laatst gebruikt". Zo weet je over een jaar nog welke sleutel waarbij hoort — en welke je gerust mag intrekken.

Stap 2. Vink aan wat de sleutel mag. Onder Wat mag deze sleutel? staan de rechten, of scopes in vaktaal. Lezen staat al aangevinkt:

Recht	Wat het programma mag
Lezen	Je catalogus, prijzen, vrije plaatsen, kortingen, cadeaubonnen en jaarkaarten bekijken — en ook je bestellingen, tickets, scans en kopers, met hun naam en e-mailadres.
Schrijven	Bestellingen aanmaken, laten betalen, annuleren en terugbetalen, een factuur aanvragen, tickets intrekken en opnieuw mailen, inchecken, en cadeaubonnen en jaarkaarten uitgeven, inwisselen of verlengen.
Webhooks	Instellen dat wij een melding sturen naar een eigen adres zodra er iets gebeurt.
Extern betaald	Een bestelling betaald noemen zonder betaalprovider (overschrijving, contant). Werkt alleen samen met Schrijven.

Vink alleen aan wat echt nodig is. Een website die enkel moet tónen welke plaatsen vrij zijn, heeft genoeg aan Lezen. Krijgt die sleutel ook Schrijven, dan kan een fout in die website bestellingen aanmaken of terugbetalen die je niet wil.

Wees extra zuinig met Extern betaald: wie dat mag, kan tickets uitgeven zonder dat er geld binnenkomt. Geef het alleen aan een kassa of boekhouding die je zelf beheert.

Je moet minstens één recht aanvinken. Een sleutel zonder rechten zou niets mogen, en dat is de lastigste soort fout om terug te vinden — daarom weigert het scherm hem.

Stap 3 (optioneel). Zet een vervaldatum. Laat je het veld Vervalt op (optioneel) leeg, dan blijft de sleutel werken tot je ze zelf intrekt. Vul je een datum in, dan werkt ze die dag nog en stopt ze daarna vanzelf. De datum moet in de toekomst liggen. Handig wanneer je iemand tijdelijk laat meekijken: je hoeft er dan later niet meer aan te denken.

Stap 4 (optioneel). Testsleutel. Vink Testsleutel (sandbox) aan voor wie nog aan het bouwen is. Zo'n sleutel leest dezelfde gegevens als een gewone. Heeft ze ook Schrijven, dan maakt ze alleen proefbestellingen: die gaan nooit naar je betaalprovider, tellen niet mee in je omzet en worden na 24 uur vanzelf opgeruimd. Een tikfout kan dan geen echte betaling of terugbetaling veroorzaken. Webhooks instellen kan een testsleutel niet.

Let op: een proefbestelling houdt tot ze opgeruimd is wel een echte plaats vast, en de bevestigingsmail vertrekt echt. Laat testen met een product of tijdslot dat je daarvoor aanmaakt.

Je herkent een testsleutel aan het begin: hij start met pv_test_ in plaats van pv_live_.

Stap 5. Klik op "Sleutel aanmaken".

De sleutel zie je maar één keer

Meteen na het aanmaken verschijnt de sleutel in een kader. Dat is de enige keer dat je hem ziet.

Kopieer hem nu en geef hem meteen door. Ververs je de pagina, dan is hij weg.

Dat is geen ongemak maar bescherming. Wij bewaren je sleutel niet: we bewaren er alleen een soort vingerafdruk van, waarmee we hem kunnen herkennen maar niet kunnen teruglezen. Zou iemand ooit bij onze databank raken, dan heeft hij daarmee nog geen toegang tot jouw gegevens. De keerzijde is dat ook wij hem niet meer kunnen tonen.

Ben je hem kwijt? Geen probleem: maak een nieuwe aan en trek de oude in.

Behandel een sleutel als een sleutel

Wie de sleutel heeft, mag wat er op die sleutel aangevinkt staat — zonder wachtwoord en zonder je account te openen. Dus:

• stuur hem niet in een gewone groepschat waar hij blijft staan;
• zet hem niet in de zichtbare code van je website;
• geef elke koppeling een eigen sleutel. Dan kun je er één intrekken zonder de rest stuk te maken, en zie je in de lijst welke nog gebruikt wordt.

Een sleutel intrekken

Klik in de lijst op Intrekken naast de sleutel, en bevestig.

Vanaf dat moment werkt ze niet meer. De regel blijft wel in de lijst staan, met het merkteken "Ingetrokken": zo kun je later nog altijd opzoeken welke koppeling wanneer bestond.

Trek een sleutel in wanneer:

• je stopt met de tool die hem gebruikte;
• je hem kwijt bent of hij ergens rondslingert;
• iemand vertrekt die hem had.

Het aanmaken en het intrekken van een sleutel komt ook in het activiteitenlog te staan van wie het deed (Instellingen → Medewerkers, die persoon, tabblad Activiteit), met het tijdstip. De sleutel zelf staat daar nooit in.

Wanneer is ze voor het laatst gebruikt?

Onder elke sleutel staat wanneer er voor het laatst mee opgehaald is. Staat er al maanden "nog niet gebruikt", dan hangt er waarschijnlijk niets meer aan. Trek ze dan gerust in — een deur die niemand gebruikt, hoef je niet open te laten staan.

Wat je doorgeeft aan wie de koppeling bouwt

Drie dingen:

1. het API-adres uit het blok De koppeling;
2. de technische beschrijving (de link die op openapi.json eindigt) — daarmee ziet een ontwikkelaar meteen alles wat er kan;
3. de sleutel zelf, en welke rechten je hebt aangevinkt.

Meer heeft hij niet nodig.

En dan?

Je hebt het adres en de sleutel. Wat er daarna gebeurt, is werk voor wie de koppeling bouwt — en die stuur je door naar het developersportaal. Daar staat de volledige referentie, met codevoorbeelden in vier talen en een bestand dat rechtstreeks in Postman of Insomnia te importeren valt.

• Wat is een API, en heb ik dat nodig? — als je eerst nog wil weten waar dit allemaal over gaat.
• Webhooks — laat je website weten dat er iets verkocht is, zonder dat ze het hoeft te blijven vragen.
• Webhooks instellen — het tabblad Webhooks op ditzelfde scherm, stap voor stap.