Soms wil iemand iets aan Stippa koppelen. Een websitebouwer die het boekformulier in jouw eigen huisstijl wil nabouwen, een boekhouder met een script dat omzet ophaalt, of een dienst als Zapier die een bericht stuurt zodra er een afspraak binnenkomt. Zo iemand vraagt je dan om een API-sleutel.
Deze pagina is voor jou, niet voor die ontwikkelaar. Je hoeft niet te weten hoe het technisch werkt om de goede beslissing te nemen. Wat de ontwikkelaar nodig heeft, staat in de ontwikkelaarsdocumentatie, die in het Engels is.
Wat is een API-sleutel?
Een lange, geheime tekst die begint met stp_live_. Wie hem heeft, mag namens jouw zaak precies
die dingen doen die jij bij het aanmaken hebt aangevinkt, en niets anders.
Drie dingen zijn belangrijker dan de techniek:
- Een sleutel hoort bij jouw zaak. Hij kan nooit bij de gegevens van een andere zaak, ook niet per ongeluk.
- Een sleutel is geen inlog. Er zit geen wachtwoord aan vast en niemand kan er de app mee binnenlopen. Hij werkt alleen voor de koppeling zelf.
- Een sleutel is een geheim, zoals een sleutel van de zaak. Wie hem heeft, kan hem gebruiken. Dat is precies waarom de rest van deze pagina bestaat.
Wanneer heb ik er een nodig?
Alleen als iemand erom vraagt. Voor het normale gebruik van Stippa heb je nooit een API-sleutel nodig: de boekingswidget, de agenda, de e-mails en het openbare profiel werken allemaal zonder.
Typische gevallen waarin het wel speelt:
- Je websitebouwer wil boeken volledig in je eigen site verwerken, in plaats van de standaard widget te gebruiken.
- Iemand wil je afspraken automatisch in een spreadsheet of boekhoudpakket zetten.
- Je wilt een melding in Slack, Teams of Zapier zodra er geboekt wordt.
Welk abonnement heb ik nodig?
| Wat je wilt | Vanaf | |---|---| | Gegevens uitlezen (afspraken, klanten, diensten, beschikbaarheid) | Groei | | Gegevens laten aanmaken of wijzigen, en webhooks | Pro |
Ga je terug naar een lager abonnement, dan blijft de sleutel gewoon bestaan. De rechten die je abonnement niet meer geeft, werken alleen niet meer. Upgrade je later weer, dan doet de koppeling het meteen weer, zonder dat iemand iets hoeft in te stellen.
Een sleutel aanmaken
Je vindt de sleutels in de Dev-app, die in de app-kiezer linksboven staat zodra je de module Publieke API hebt ingeschakeld.
Zet de module aan
Ga naar Beheer > Modules en zet Publieke API aan. De Dev-app verschijnt daarna in de app-kiezer.
Ga naar Dev > Sleutels
Klik op Nieuwe sleutel.
Geef hem een naam die je over een jaar nog snapt
Niet "test" of "sleutel 2", maar "Website Jansen Webdesign" of "Koppeling boekhouding". Als je ooit iets moet intrekken, is de naam het enige waaraan je ziet welke sleutel van wie is.
Vink alleen aan wat nodig is
Er staan vaste combinaties klaar. Twijfel je, kies dan Alleen lezen: die kan niets veranderen. Rechten toevoegen kan later niet meer, maar een tweede sleutel aanmaken wel, en dat is de veilige volgorde.
Kopieer de sleutel meteen
Je ziet de volledige sleutel één keer, direct na het aanmaken. Daarna bewaart Stippa alleen nog een versleutelde vorm en kan ook wij hem niet meer laten zien. Ben je hem kwijt, dan trek je hem in en maak je een nieuwe.
Een sleutel veilig doorgeven
De sleutel één keer per e-mail sturen en dan vergeten is de manier waarop het meestal misgaat: een mailbox blijft jaren doorzoekbaar, wordt gedeeld en gaat mee naar een volgende werkgever.
- Geef hem door via een kanaal dat wist, of via de wachtwoordkluis die de ontwikkelaar toch al gebruikt.
- Zet hem nooit in een openbaar bericht, een ticket of een gedeeld document.
- Maak per partij een eigen sleutel. Twee bedrijven met dezelfde sleutel betekent dat je de koppeling van allebei stukmaakt als je er één moet intrekken.
- Vraag om een einddatum als de klus tijdelijk is. Je kunt een sleutel laten verlopen, en dan hoeft niemand er later nog aan te denken.
Een sleutel intrekken
Ga naar Dev > Sleutels en kies Intrekken bij de sleutel in kwestie. Dat werkt direct: het eerstvolgende verzoek met die sleutel wordt geweigerd. Intrekken kun je niet terugdraaien, dus de koppeling moet daarna een nieuwe sleutel krijgen.
Trek in ieder geval in:
- als de samenwerking met de bouwer of het bureau stopt;
- als de sleutel ergens terecht is gekomen waar hij niet hoort;
- als je niet meer weet waar een sleutel voor dient. Een sleutel die niemand kan thuisbrengen, hoort niet actief te zijn.
Twijfel je of een sleutel nog gebruikt wordt, kijk dan eerst in Dev > Logboek. Daar zie je per verzoek wanneer er iets binnenkwam en of het lukte. Een sleutel die daar al maanden niet in voorkomt, kun je gerust intrekken.
Webhooks: de andere kant op
Een sleutel laat iemand gegevens bij jou ophalen. Een webhook doet het omgekeerde: Stippa stuurt een bericht naar een webadres zodra er iets gebeurt, bijvoorbeeld als er een afspraak wordt geboekt of geannuleerd. Dat is wat een koppeling met Slack of Zapier nodig heeft. Webhooks zitten op het Pro-abonnement en staan in Dev > Webhooks.
Een webhook-adres verdient dezelfde zorg als een sleutel. Bij elke gebeurtenis stuurt Stippa de bijbehorende gegevens naar dat adres, inclusief namen, e-mailadressen en telefoonnummers van je klanten. Wie het adres mag instellen, kan die stroom dus ergens anders naartoe laten lopen. Neem alleen een adres over van iemand die je vertrouwt, en controleer de lijst als je niet meer weet wie wat heeft ingesteld.
Blijft een adres onbereikbaar, dan probeert Stippa het een aantal keer opnieuw en zet daarna het eindpunt automatisch uit, zodat er niet eindeloos naar een dood adres wordt gestuurd. Je ziet dat terug als een melding boven de lijst, met een knop om het weer aan te zetten zodra de ontvanger het weer doet.
Veelgestelde vragen
Kan iemand met mijn sleutel inloggen in Stippa? Nee. Een sleutel werkt alleen voor de koppeling en geeft geen toegang tot de app, je account of je abonnement.
Kan een sleutel bij de gegevens van een andere zaak? Nee. De sleutel bepaalt zelf om welke zaak het gaat; er is geen instelling waarmee je een andere zaak zou kunnen aanwijzen.
Ik zie de Dev-app niet. De module Publieke API staat uit, je abonnement is Starter, of je bent medewerker. De app is zichtbaar voor eigenaren en beheerders.
Mijn ontwikkelaar vraagt om documentatie. Stuur hem naar de ontwikkelaarsdocumentatie. Die is Engelstalig en bevat alles wat hij nodig heeft, inclusief voorbeelden.