Overzicht · Schedulinq Docs

De Schedulinq API koppelt je eigen systeem — meestal je CRM — aan Schedulinq. Jouw systeem maakt het werk aan; Schedulinq plant het, verstuurt de uitnodigingen en houdt de agenda bij. Dit hoofdstuk is geschreven voor de ontwikkelaar die de koppeling bouwt én voor de beheerder die hem in Schedulinq instelt: sommige stappen gebeuren in jouw code, andere in het dashboard.

Wat je kunt bouwen

Drie knoppen in je CRM, elk één HTTP-aanroep van jouw server naar de onze:

Plannen opent de planner van Schedulinq voor een lead en een teamlid, met alles al ingevuld. De beller kiest een tijd en slaat op. Zie Planningslinks.
Uitnodigen stuurt de klant in één aanroep een uitnodiging om een tijd te boeken bij het teamlid dat je kiest. Zie Uitnodigingen.
Koper aanmaken nodigt iemand uit als teamlid van je organisatie. Zie Teamleden.

Webhooks melden elke wijziging terug aan je systeem: een afspraak geboekt, verzet of geannuleerd, een uitnodiging gebruikt, een teamlid dat heeft geaccepteerd. Zie Webhooks.

Hoe jouw wereld in Schedulinq past

Een lead wordt een klant, één per lead. Klanten worden op e-mailadres gevonden, zodat dezelfde persoon niet twee keer wordt aangemaakt.
Een koper of monteur wordt een teamlid, met eigen werktijden, werkgebieden en agenda.
Een beller is een teamlid dat mag plannen: degene in je CRM die op Plannen drukt.
Je deal- en campagne-id's worden kenmerken — je eigen verwijzingen, die meereizen op uitnodigingen, afspraken en uitnodigingen voor teamleden. Zie Kenmerken.

Wie wat instelt

Beheerders beheren de API-sleutels, de webhooks en de toegestane terugkeeradressen onder Integraties → API. Niemand anders ziet die pagina.
Bellers hebben een rol nodig die afspraken mag maken en alle afspraken en klanten mag zien.
Kopers krijgen meestal een rol die alleen hun eigen afspraken ziet en geen klanten. Zie Teamleden.
Sleutels en webhooks zijn van de organisatie. Ze zien elke afspraak, elke uitnodiging en elk teamlid, wat de rol van een teamlid ook is — rollen zijn een regel van het dashboard, niet van de API. Een CRM dat meerdere concurrerende kopers bedient, houdt ze zelf uit elkaar.

Wat de API bewust niet doet

Hij maakt geen afspraken rechtstreeks. De planner is de weg: een mens kiest de tijd, met de agenda, de rijtijd en het werkgebied in beeld.
Hij annuleert geen uitnodiging.
Hij stelt geen diensten, werkgebieden of werktijden in. Dat doet een beheerder in Schedulinq.
Hij laat een teamlid niet bij meerdere organisaties horen.
Er is geen testmodus. Test met een aparte testorganisatie, nooit met je echte; neem contact op met support@schedulinq.com om er een op te zetten.

Basisadres en formaat

Elk endpoint staat onder https://api.schedulinq.com/api/v1. Verzoeken en antwoorden zijn JSON, alleen over HTTPS. Namen zijn camelCase, id's zijn UUID's en tijden zijn ISO 8601 met hun offset. De referentie noemt alle conventies.

Wat je ontvangt

Antwoorden en webhook-berichten bevatten:

id's, tijden en status;
de dienst, en de teamleden met id en naam;
de plek — bij een bezoek aan huis is dat het adres van de klant;
de kenmerken — je eigen verwijzingen, meegekopieerd naar elke afspraak die uit een uitnodiging of planningslink volgt (zie Kenmerken);
bij een teamlid: naam, e-mailadres en eigen velden.

Ze bevatten geen naam, e-mailadres of telefoonnummer van de klant: de klant staat erin als customerId. Behandel wat je ontvangt toch als persoonsgegevens. Dat geldt ook voor het bezorglogboek van de webhooks in het dashboard, dat de berichten 30 dagen bewaart en aan beheerders laat zien.

Beveiliging

De afnemer van de API is het eigen systeem van je organisatie: je CRM en je webhook-ontvanger, op jouw servers.

Een sleutel hoort bij één organisatie. Een id van een andere organisatie geeft 404, alsof hij niet bestaat.
De sleutel is geheim. Hij handelt voor de hele organisatie. Houd hem op je server, nooit in een browser, een URL, een repository of een logregel. Zie Authenticatie en API-sleutels.
Behandel id's van afspraken en uitnodigingen als vertrouwelijk. Bewaar ze in je eigen systeem en laat ze niet aan klanten zien of in links die je verstuurt.
De url van een planningslink is ook geheim: hij opent één keer, binnen 15 minuten.
Uitnodigingen die je systeem verstuurt, zeggen dat in het dashboard: "Via API" met de naam van de sleutel, op de uitnodigingspagina en, voor teamleden, op de Team-pagina.

Veelgestelde vragen

Is er een SDK?

Nee. De API is beschreven in OpenAPI, waar de meeste talen een client van kunnen maken. De referentie linkt naar de beschrijving.

Kan ik de API vanuit een browser aanroepen?

Nee. De API stuurt geen CORS-headers, en een sleutel in browsercode is een sleutel die iedereen kan kopiëren. Roep hem aan vanaf je server, en laat je server de browser doorsturen waar dat nodig is — naar een planningslink bijvoorbeeld.