Uw tools koppelen met de API
Met de API kan een externe toepassing programmatisch toegang krijgen tot de gegevens van uw Organisatie: ledenbestand, agenda's, boekingen en facturatie. U activeert de API met twee klikken en beveiligt hem met een sleutel, een lijst met toegestane adressen en een verbruiksoverzicht.
Nagaan of de API iets voor u is
De API is bedoeld voor een ontwikkelaar, niet voor een verantwoordelijke van een Organisatie. Ze laat uw account communiceren met software die u laat schrijven of instellen: een website op maat, een boekhoudprogramma, een zelfgebouwd informatiescherm, een koppeling naar een ander systeem.
Voor de gangbare behoeften — de ledenlijst ophalen, Abonnementen in bulk bijwerken, cijfers doorgeven aan het bestuur — volstaan de modules voor import, export en rapporten, zonder ook maar één regel code.
De API wordt aangeboden in bètaversie: de werking kan nog wijzigen.
De API activeren en uw sleutel ophalen
- Ga naar Administratie›Instellingen›API BETA.
- Schakel API-module activeren in en klik daarna op Opslaan.
- Uw API-sleutel verschijnt: kopieer hem met de knop Kopiëren en geef hem uitsluitend door aan de tool die u koppelt.
De sleutel wordt bij elke aanvraag meegestuurd in de HTTP-header X-API-Key. De aanroepen verlopen verplicht via HTTPS; onversleutelde aanvragen worden niet aanvaard.
De sleutel beschermen
Enkele goede gewoonten die u de tool of de dienstverlener die hem gebruikt best in herinnering brengt:
- plaats de sleutel nooit in een coderepository; bewaar hem in een configuratiebestand buiten de repository of in een secretbeheerder;
- beperk de toegestane adressen zodra de tool vanaf een vaste server aanroept;
- genereer de sleutel opnieuw bij de minste twijfel — onbedoelde publicatie, gelekte logbestanden, einde van de opdracht van een dienstverlener.
De knop Regenereren vraagt om bevestiging en maakt de oude sleutel meteen ongeldig. Alle toepassingen die hem gebruikten, werken niet meer zolang ze de nieuwe sleutel niet hebben ontvangen: verwittig ze voordat u klikt.
De toegang beperken op IP-adres
Schakel de Beperking op IP-adres in: alleen aanvragen vanaf de adressen die u opsomt, worden aanvaard, met een maximum van 10 IPv4-adressen. Voer elk adres in en bevestig met Toevoegen; uw huidige adres wordt op het scherm getoond om u te helpen.
Dit is de doeltreffendste bescherming, en meteen ook de meest verwaarloosde: zelfs als een sleutel uitlekt, blijft hij onbruikbaar elders wanneer hij beperkt is tot het adres van uw dienstverlener.
Het verbruik opvolgen
Het scherm toont doorlopend wat uw sleutel verbruikt:
- Gebruik deze minuut en Gebruik vandaag, telkens afgezet tegen de limiet wanneer er een limiet is ingesteld;
- Gebruiksstatistieken: Deze week, Deze maand, Totaal en Laatste verzoek.
Boven de aangegeven limieten worden bijkomende aanvragen tijdelijk geweigerd. Een teller die voortdurend tegen zijn plafond aanschurkt, wijst meestal op een slecht afgestelde tool die dezelfde gegevens in een lus blijft opvragen in plaats van ze in cache te bewaren.
De datum van de laatste aanvraag is nuttig in de andere richting: een sleutel die geactiveerd is maar al maanden niet meer werd aangeroepen, is een sleutel die u beter uitschakelt.
Ontdekken wat de API mogelijk maakt
De volledige documentatie, met de parameters en voorbeelden van aanroepen, staat onderaan het scherm van de module. In grote lijnen:
- Gebruikers: dit is de enige aanpasbare bron. U kunt accounts opsommen, raadplegen, aanmaken, wijzigen en verwijderen.
- Configuratie: Abonnementen, profielen, groepen en leeftijdscategorieën kunt u raadplegen, maar alleen vanuit de toepassing instellen.
- Boeking: agenda's, beschikbare Tijdsloten, Boekingen en labels kunt u raadplegen.
- Facturatie: factuuraccounts, bestellingen en betalingen kunt u raadplegen.
