API en webhooks
Uw andere tools aansluiten op de gegevens van het makelaarskantoor met een API-sleutel, en de gebeurtenissen ervan ontvangen op uw eigen adres.
De sleutels beheert u in Organisatie › API, de ontvangstadressen in Organisatie › Webhooks.
Voor u begint
- De rubrieken API en Webhooks verschijnen alleen in het menu met het recht „Integraties“ (standaard alleen de beheerder).
- De twee pagina's openen alleen voor de beheerder. Een manager of makelaar die het recht „Integraties“ heeft gekregen, ziet de rubrieken, maar wordt teruggestuurd naar de startpagina.
- Elke functie moet in uw formule zitten: „API“ voor de sleutels, „Webhooks“ voor de adressen (zie Abonnement en facturatie). Anders zegt de pagina het en stelt ze Formules bekijken voor.
De API
De API geeft toegang tot de gegevens van uw kantoor, en alleen van uw kantoor.
| Wat de API toelaat | Vereiste sleutel |
|---|---|
| De contacten, de twee pipelines en hun stappen, de opportuniteiten, de opdrachten, de advertenties en de bezoeken lezen | lezen |
| Een lead aanmaken (contact teruggevonden via zijn e-mail of aangemaakt; bij een advertentie, een kopersopportuniteit) | lezen en schrijven |
| Een opportuniteit naar een andere stap van haar pipeline verplaatsen | lezen en schrijven |
- De opdrachten worden geleverd zonder onderhandelingsmarge, zonder commissie en zonder logboek.
- Elke sleutel heeft recht op 120 verzoeken per minuut en 20 000 per dag.
De technische documentatie
De pagina API toont het Adres van de API en een link Documentatie. Die link opent de openbare technische documentatie van de API, bestemd voor uw ontwikkelaar: elke toegang, de parameters, de antwoorden, hoe u zich met de sleutel aanmeldt en hoe u de resultaten pagina per pagina doorloopt. In productie staat ze op het adres https://api.immobooking.be/api/v1/externe/docs.
Een sleutel aanmaken
- Open Organisatie › API.
- Vul op de kaart Nieuwe sleutel de Naam van de sleutel in (2 tot 60 tekens), bijvoorbeeld „Website van het kantoor“ of „Dashboard“.
- Vink Mag ook schrijven (leads aanmaken, opportuniteiten verplaatsen) aan als de tool moet schrijven. Anders kan de sleutel alleen lezen.
- Klik op Sleutel aanmaken.
- Klik op de kaart Uw nieuwe sleutel op Kopiëren en bewaar de sleutel op een veilige plaats.
- Klik op Ik heb de sleutel gekopieerd.
De sleutels opvolgen en intrekken
De lijst Uw sleutels toont voor elke sleutel de naam, het begin, het label „Lezen“ of „Lezen en schrijven“, de aanmaakdatum en het laatste gebruik (of „Nooit gebruikt“).
- Klik op Intrekken naast de sleutel.
- Bevestig. Het bericht „Sleutel ingetrokken.“ verschijnt.
De tools die deze sleutel gebruiken, verliezen meteen de toegang; de andere sleutels blijven werken. Verliest uw formule de functie „API“, dan worden alle sleutels geweigerd.
De webhooks
Een webhook stuurt bij elke gebeurtenis van het kantoor een bericht naar het adres van uw tool.
| Gebeurtenis | Wanneer hij vertrekt |
|---|---|
| „Lead aangemaakt (nieuwe opportuniteit)“ | er wordt een nieuwe opportuniteit aangemaakt |
| „Opdracht ondertekend“ | er wordt een opdracht ondertekend |
| „Zoekertje gepubliceerd“ | er wordt een advertentie gepubliceerd |
| „Bezoek geboekt“ | een online geboekt bezoek wordt bevestigd |
Een adres toevoegen
- Open Organisatie › Webhooks.
- Vul op de kaart Nieuw adres het Adres (https) van uw tool in.
- Vink minstens één van de Gebeurtenissen aan.
- Klik op Adres opslaan.
- Klik op de kaart Ondertekeningsgeheim op Kopiëren en bezorg het geheim aan uw ontwikkelaar.
- Klik op Ik heb het geheim gekopieerd.
- Het geheim wordt maar één keer getoond. Uw tool gebruikt het om te controleren dat de berichten wel degelijk van ImmoBooking komen; de kaart Een bericht controleren legt uit hoe.
- Hoogstens tien adressen.
- Mogelijke weigeringen: „Dit adres is ongeldig.“, „Het adres moet met https:// beginnen.“, „Dit adres verwijst naar een intern netwerk: het wordt geweigerd.“.
Een adres beheren
In Uw adressen draagt elk adres het label „Actief“ of „Gepauzeerd“.
- Test versturen: binnen de minuut vertrekt een testbericht.
- Pauzeren en Hervatten.
- Verwijderen: er wordt geen enkel bericht meer naartoe gestuurd, en de historiek van de verzendingen wordt gewist.
De verzendingen opvolgen
Onder Laatste verzendingen draagt elk bericht de status „In afwachting“, „Bezorgd“ of „Mislukt“, het aantal pogingen en, in voorkomend geval, het uur van de volgende poging.
- Uw tool moet binnen 10 seconden met een succesantwoord reageren. Een doorverwijzing wordt niet gevolgd en telt als mislukt.
- Bij een mislukking wordt het bericht opnieuw verstuurd na 1, 5 en 30 minuten, daarna na 2, 6, 12 en 24 uur, dus gedurende bijna twee dagen.
- Na de laatste poging is de mislukking definitief. Opnieuw versturen zet het bericht opnieuw in de wachtrij („Verzending opnieuw in de wachtrij.“).