API-documentatie Finly: integreren met de Finly API
Uitleg over de Finly API-documentatie, toegang, authenticatie met API key en bearer token, rate limits en webhooks.
Wat is de Finly API-documentatie?
Met de Finly API kun je gegevens uit Finly ophalen en gebruiken in andere applicaties. Denk aan het ophalen van volledige klantdossiers, formulierinstanties, subaccounts en meer, zodat je jouw eigen applicatie kunt verrijken met actuele Finly-data.
De volledige API-documentatie vind je op:
Productie: www.finly.nl/developers
Staging (testomgeving): staging.finlydev.nl/developers
Hoe is de documentatie opgebouwd?
De API-documentatie bestaat uit standaardvelden én eventuele eigen toegevoegde velden die per omgeving kunnen verschillen. De documentatie wordt daarom dynamisch opgebouwd op basis van de eigen inrichting. Dit betekent dat de documentatie die jij ziet, aansluit op jouw specifieke omgeving.
Per endpoint zie je:
Parameters: de velden die je meegeeft in het verzoek
Response: de velden die je terugkrijgt, inclusief type (string, integer, dateTime, array, etc.)
De documentatie is zo opgezet dat een developer in principe zonder aanvullende ondersteuning van Blinqx aan de slag kan.
Toegang tot de documentatie
De API-documentatie staat achter een inlog en is niet openbaar toegankelijk. Dit komt doordat de documentatie ook eigen (klantspecifieke) velden bevat. Voor inzage is daarom een Finly-account nodig.
Wil een developer toegang tot de documentatie? Dan zijn er twee opties:
Wij maken een account op de staging-omgeving aan, zodat de developer de documentatie daar kan inzien
De documentatiepagina als PDF exporteren en aanleveren
Authenticatie
De API werkt met account-credentials: een domein en een API key die aan het account gekoppeld zijn.
Met het domein en de API key vraag je eenmalig een bearer token op.
Dit bearer token is 24 uur geldig. Je gebruikt het bij elk verzoek naar de API.
Is het token verlopen? Dan ververs je het met het bijbehorende refresh-token, zonder opnieuw de API key te gebruiken.
Optioneel: verzoeken scopen naar één eindklant
Moet je integratie per eindklant filteren? Dan is er een lichtere variant met een eigen clienttoken. Daarmee beperk je verzoeken tot de gegevens van één specifieke eindklant.
API key aanvragen en beheren
De API key is een account-specifieke sleutel die eenmalig wordt aangemaakt.
Belangrijk:
De API key geeft toegang tot de volledige omgeving. Bewaar hem daarom goed en veilig, en deel hem niet met onbevoegden.
Het aanvragen van een API key gaat via een opdracht bij je consultant.
Moet een API key worden vervangen (bijvoorbeeld bij verlies of security-risico)? Dit is een opdracht. Let op: na vervanging moeten alle bestaande koppelingen die de oude key gebruiken ook worden bijgewerkt.
Rate limits en realtime synchronisatie
Rate limit
De API verwerkt maximaal 500 requests per minuut. Bundel requests waar mogelijk en bouw bij overschrijding een wachttijd in voordat je het opnieuw probeert.
Webhooks (agenda-module)
Voor de agenda-module bieden we webhooks die je realtime informeren bij:
het aanmaken van een afspraak
het wijzigen van een afspraak
het annuleren van een afspraak
Overige gegevens
Voor andere onderdelen zijn momenteel geen webhooks beschikbaar. Wil je die gegevens actueel houden, dan haal je wijzigingen periodiek op via de API. Houd daarbij rekening met de rate limit hierboven.
Ondersteuning nodig?
Een developer kan met de documentatie zelfstandig integreren. Lukt het toch niet zonder hulp, of wil je dat Blinqx meedenkt of meekijkt? Dan is het mogelijk om dit als opdracht neer te leggen. Neem contact op met je vaste contactpersoon bij Blinqx.
Bron: helpcenter Finly