Calendo

Rajapinta ja integraatiot

REST API v1, webhookit sekä Zapier ja Make.

Yleistä

Calendon julkinen REST-rajapinta on Pro-paketin ominaisuus. Sillä voit hakea varauksia, tapaamistyyppejä ja vapaita aikoja sekä luoda ja perua varauksia omasta järjestelmästäsi, Zapierista tai Makesta.

Kaikki vastaukset ovat JSONia ja ajat ISO 8601 -muodossa UTC-aikana (esim. 2026-10-05T11:00:00.000Z). Koneluettava kuvaus: /api/v1/openapi.json (OpenAPI 3.1).

Rajapinnan kautta tehty varaus noudattaa samoja sääntöjä kuin hallintapaneelista lisätty varaus: aika tarkistetaan saatavuudesta ja kalentereista, kapasiteetti ja pitäjä huomioidaan, kalenterimerkintä ja vahvistusviesti luodaan, ja webhookit lähtevät. Ennakkomaksua ei peritä (kuten hallintapaneelin omissa varauksissa).

Tunnistus ja API-avaimet

  1. Kirjaudu Calendoon ja avaa Asetukset → Integraatiot → Rajapinta (API) ja Zapier / Make.
  2. Anna avaimelle nimi (esim. "Zapier") ja valitse Luo API-avain.
  3. Kopioi avain heti. Se näytetään vain kerran; Calendo tallentaa siitä vain tiivisteen.

Lähetä avain jokaisessa pyynnössä otsakkeessa:

Authorization: Bearer cal_live_…

Avain antaa pääsyn vain sen tilin tietoihin, jossa se luotiin. Poista avain samasta näkymästä, jos se on päätynyt vääriin käsiin: se lakkaa toimimasta heti. Jos tilin paketti vaihtuu pienempään kuin Pro, avaimet eivät toimi ennen kuin Pro on taas voimassa.

Pyyntörajat

Avainta kohden enintään 120 pyyntöä minuutissa ja 3000 tunnissa. Vastauksen otsakkeet X-RateLimit-Limit ja X-RateLimit-Remaining kertovat tilanteen. Rajan ylittyessä vastaus on 429 ja otsake Retry-After kertoo, montako sekuntia odottaa.

Päätepisteet

MetodiPolkuKuvaus
GET/api/v1/meAvaimen tili
GET/api/v1/event-typesTapaamistyypit
GET/api/v1/availabilityVapaat ajat
GET/api/v1/bookingsVaraukset
POST/api/v1/bookingsLuo varaus
GET/api/v1/bookings/{id}Yksittäinen varaus
POST/api/v1/bookings/{id}/cancelPeru varaus

Esimerkit

Varaukset aikaväliltä

curl -H "Authorization: Bearer $CALENDO_KEY" \ "https://calendo.fi/api/v1/bookings?from=2026-10-01&to=2026-11-01&status=confirmed"

Vapaat ajat seuraavalle viikolle

curl -H "Authorization: Bearer $CALENDO_KEY" \ "https://calendo.fi/api/v1/availability?eventType=konsultaatio&from=2026-10-05&days=7"

Varauksen luonti

curl -X POST -H "Authorization: Bearer $CALENDO_KEY" -H "Content-Type: application/json" \ -d '{"eventType":"konsultaatio","startsAt":"2026-10-05T11:00:00Z","name":"Maija Meikäläinen","email":"maija@example.com","phone":"+358401234567","notes":"Tuli verkkokaupasta"}' \ https://calendo.fi/api/v1/bookings

Aloitusaika on oltava jokin /availability-vastauksen vapaista ajoista; muuten vastaus on 409.

Varauksen peruutus

curl -X POST -H "Authorization: Bearer $CALENDO_KEY" https://calendo.fi/api/v1/bookings/123/cancel

Peruutus palauttaa mahdollisen ennakkomaksun kokonaan, poistaa kalenterimerkinnän ja lähettää asiakkaalle peruutusviestin.

Virheet

Virhevastauksen muoto on aina sama:

{ "error": { "code": "conflict", "message": "Aika ei ole enää vapaana. Valitse toinen aika." } }
  • 400 invalid_request – puuttuva tai virheellinen kenttä
  • 401 unauthorized – avain puuttuu, on virheellinen tai poistettu
  • 403 plan_required – tili ei ole Pro-paketissa
  • 404 not_found – varausta tai tapaamistyyppiä ei ole tällä tilillä
  • 409 conflict – aika ei ole vapaana tai paikat ovat täynnä
  • 429 rate_limited – pyyntöraja ylittyi

Webhookit (tapahtumat)

Calendo voi lähettää tiedon uusista (booking.created), perutuista (booking.cancelled) ja siirretyistä (booking.rescheduled) varauksista antamaasi osoitteeseen. Webhookit lisätään kohdassa Asetukset → Integraatiot → Webhookit ja Zapier (Kasvu ja Pro).

Runko on JSON: { "event": "booking.created", "createdAt": "…", "data": { …varaus… } }, jossa varaus on samassa muodossa kuin rajapinnan Booking. Jokainen pyyntö on allekirjoitettu otsakkeella Calendo-Signature: t=<unix-aika>,v1=<HMAC-SHA256>, jossa HMAC lasketaan webhookin salaisuudella merkkijonosta <t>.<runko>. Epäonnistunut toimitus yritetään uudelleen 1, 5 ja 30 minuutin sekä 2 ja 12 tunnin kuluttua.

Zapier

Zapierin yhdistämiseen riittävät Zapierin omat "Webhooks by Zapier" -toiminnot; erillistä Calendo-sovellusta ei tarvita. Huom. Webhooks by Zapier on Zapierin premium-sovellus, joka vaatii maksullisen Zapier-paketin.

Käynnistin: uusi, peruttu tai siirretty varaus

  1. Luo Zapissa käynnistin Webhooks by Zapier → Catch Hook ja kopioi sen osoite.
  2. Calendossa: Asetukset → Integraatiot → Webhookit ja Zapier, liitä osoite ja valitse tapahtumat.
  3. Paina Calendossa Lähetä testi yhteyden tarkistamiseksi. Tee sitten yksi oikea varaus (testivaraukset eivät lähetä webhookeja) ja hae se näytteeksi Zapierissa.
  4. Varauksen tiedot (asiakas, aika, palvelu, hallintalinkki) näkyvät Zapierissa valittavina kenttinä seuraavissa vaiheissa.

Toiminto: luo tai peru varaus, hae varauksia

  1. Lisää toiminto Webhooks by Zapier → Custom Request.
  2. Method POST, URL https://calendo.fi/api/v1/bookings, Data esim. {"eventType":"konsultaatio","startsAt":"…","name":"…","email":"…"}.
  3. Headers: Authorization = Bearer cal_live_… ja Content-Type = application/json.
  4. Peruutus: Method POST, URL https://calendo.fi/api/v1/bookings/ID/cancel.

Oma Calendo-sovellus Zapierin sovellushakemistoon (valmiit "Calendo"-käynnistimet ja -toiminnot ilman Webhooks by Zapieria) vaatii sovelluksen rakentamisen Zapierin kehittäjäalustalla ja Zapierin oman tarkastus- ja julkaisuprosessin. Sitä ei ole vielä tehty. Rajapinta ja OpenAPI-kuvaus riittävät sen pohjaksi.

Make (entinen Integromat)

  1. Käynnistin: lisää skenaarioon Webhooks → Custom webhook, kopioi osoite ja lisää se Calendoon kohdassa Asetukset → Integraatiot → Webhookit ja Zapier. Tee sen jälkeen yksi varaus (esim. itsellesi ja peru se), jotta Make tunnistaa varauksen tietorakenteen. Testivaraukset eivät lähetä webhookeja.
  2. Toiminto: lisää HTTP → Make a request. URL esim. https://calendo.fi/api/v1/bookings, Method POST, Headers Authorization: Bearer cal_live_…, Body type Raw, Content type JSON, ja runko kuten yllä. Valitse Parse response.
  3. Varausten haku: Method GET, URL https://calendo.fi/api/v1/bookings?from=…&sort=-createdAt.

Makeen voi rakentaa myös oman Calendo-sovelluksen (Custom app). Julkiseksi Maken sovellushakemistoon se tulisi vasta Maken tarkastuksen jälkeen.