Wat is een API, en heb ik dat nodig?

Je komt de drie letters tegen in een offerte van je webbouwer, of in de functielijst van je boekhoudpakket: API. Dit artikel legt uit wat het is, zonder dat je hoeft te kunnen programmeren.

Het korte antwoord

Een API is een deur aan de achterkant van je account.

Waar jij in je beheerscherm klikt om te zien hoeveel plaatsen er nog vrij zijn, kan een ander programma langs die deur precies hetzelfde opvragen — zonder dat er iemand aan een scherm zit. Achter allebei die deuren staan dezelfde gegevens: je producten, je prijzen, je vrije plaatsen, je verkoop.

Het verschil zit in wie er binnenkomt. Door de voordeur komt een mens met een muis. Door de achterdeur komt een programma met een sleutel.

Wanneer heb je er een nodig?

Alleen wanneer je iets wil dat het beheerscherm niet doet. Bijvoorbeeld:

• op je eigen website tonen welke rondleidingen deze week nog plaats hebben, in je eigen vormgeving, met cijfers die op dat moment kloppen;
• je boekhouder laten meelezen, zodat hij de omzet van vorige maand zelf ophaalt in plaats van elke maand een export van jou te krijgen;
• een scherm in de inkomhal dat toont welk tijdslot er zo begint;
• verkopen vanuit een programma dat je al gebruikt, zonder eerst in het beheerscherm te moeten inloggen.

En wanneer heb je er géén nodig? Wanneer je het kan klikken. Een koppeling bouwen kost tijd en onderhoud; twee keer per maand een lijst exporteren kost twee minuten. Kies het eerste pas wanneer het tweede in de weg begint te zitten.

Let op: je hoeft dit zelf niet te bouwen. Wie het wél bouwt — je webbouwer, de leverancier van je boekhoudpakket, iemand in je bestuur die kan programmeren — heeft maar twee dingen van je nodig: het adres en een sleutel. Allebei vind je in je beheerscherm.

Wat je precies doorgeeft

Open Instellingen → API-toegang (dat scherm is er voor de eigenaar van de organisatie). Op het tabblad Sleutels staan drie dingen die je kan doorgeven:

1. Het adres. Eén regel tekst. Dat is waar het andere programma naartoe praat.
2. De technische beschrijving, de link die op openapi.json eindigt. Daarmee ziet een ontwikkelaar in één oogopslag alles wat er kan: welke gegevens er zijn, hoe je ze opvraagt, wat er terugkomt.
3. Een sleutel, die je zelf aanmaakt. Zie Een API-sleutel aanmaken.

Meer heeft hij niet nodig, en meer hoor je ook niet te geven — je wachtwoord zeker niet.

Wat een sleutel wel en niet mag

Bij het aanmaken vink je aan wat de sleutel mag. Dat is geen formaliteit:

• Lezen — alles opvragen, niets veranderen. Dit is wat de meeste koppelingen nodig hebben. Let op: "alles" is ook je bestellingen en je 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 — laten weten waar er berichten naartoe mogen. Zie Webhooks.
• Extern betaald — een bestelling betaald noemen zonder dat er een betaalprovider aan te pas kwam (overschrijving, contant). Geef dat alleen aan een kassa of boekhouding die je zelf beheert: wie dit mag, kan tickets uitgeven zonder dat er geld binnenkomt.

Geef elke koppeling een eigen sleutel met alleen wat ze nodig heeft. Dan kan je er één intrekken zonder de rest stuk te maken, en zie je in de lijst welke nog gebruikt wordt.

Een sleutel is trouwens geen wachtwoord dat toegang geeft tot je account: hij geeft alleen wat erop aangevinkt staat, en hij hoort bij één organisatie. Ook als hij ergens rondslingert, kan niemand er de gegevens van iemand anders mee opvragen.

Eerst veilig proberen

Naast een gewone sleutel kan je een testsleutel aanmaken. Die leest exact dezelfde gegevens. Mag 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. Webhooks instellen kan een testsleutel niet.

Dat is er precies voor dit moment — iemand die aan het uitproberen is en nog niet zeker weet wat hij doet. Laat je webbouwer met een testsleutel beginnen en pas op het einde overstappen.

Eén ding om te weten: ook een proefbestelling houdt een echte plaats vast (tot ze opgeruimd wordt), en de bevestigingsmail vertrekt echt. Laat je webbouwer daarom testen met een product of tijdslot dat je daarvoor aanmaakt.

En als het misgaat?

Trek de sleutel in. Klik in de lijst op Intrekken, en vanaf dat moment werkt ze niet meer. De koppeling stopt, je gegevens blijven. Er is geen enkele situatie waarin een sleutel iets kan aanrichten dat je niet met één klik kan stoppen.

Wat het kost

De API hoort bij een grotere formule. Zit je op een kleinere, dan staat API-toegang niet in je menu. Kom je toch op dat scherm terecht, dan zie je uitleg, op welke formule de API zit, en een knop Naar Abonnement — geen sleutels. Wat er in welke formule zit, staat op de prijzenpagina van Passavo.

Verder lezen

• Een API-sleutel aanmaken — het scherm zelf, stap voor stap.
• Webhooks — laat je website weten dat er iets verkocht is, zonder dat ze het hoeft te blijven vragen.
• Webhooks instellen — het scherm zelf, stap voor stap.
• Het developersportaal — voor wie de koppeling bouwt.