Calendo

API och integrationer

REST API v1, webhooks samt Zapier och Make.

Allmänt

Calendos öppna REST-API ingår i Pro-paketet. Med det kan du hämta bokningar, mötestyper och lediga tider samt skapa och avboka bokningar från ditt eget system, Zapier eller Make.

Alla svar är JSON och tider anges i ISO 8601-format i UTC (till exempel 2026-10-05T11:00:00.000Z). Maskinläsbar beskrivning: /api/v1/openapi.json (OpenAPI 3.1).

En bokning som görs via API:et följer samma regler som en bokning som läggs till i adminpanelen: tiden kontrolleras mot tillgängligheten och kalendrarna, kapaciteten och värden beaktas, en kalenderhändelse och ett bekräftelsemeddelande skapas och webhooks skickas. Ingen förskottsbetalning tas ut (precis som för bokningar du själv lägger till i adminpanelen).

Autentisering och API-nycklar

  1. Logga in i Calendo och öppna Inställningar → Integrationer → API och Zapier / Make.
  2. Ge nyckeln ett namn (till exempel "Zapier") och välj Skapa API-nyckel.
  3. Kopiera nyckeln direkt. Den visas bara en gång; Calendo sparar endast en hash av den.

Skicka nyckeln i varje anrop i följande header:

Authorization: Bearer cal_live_…

Nyckeln ger endast åtkomst till uppgifterna i det konto där den skapades. Om nyckeln har hamnat i fel händer raderar du den i samma vy: den slutar fungera omedelbart. Om kontot byter till ett mindre paket än Pro fungerar nycklarna inte förrän Pro är aktivt igen.

Anropsgränser

Varje nyckel får göra högst 120 anrop per minut och 3000 per timme. Svarsheadrarna X-RateLimit-Limit och X-RateLimit-Remaining visar hur mycket som återstår. När gränsen överskrids blir svaret 429 och headern Retry-After anger hur många sekunder du ska vänta.

Endpoints

MetodSökvägBeskrivning
GET/api/v1/meNyckelns konto
GET/api/v1/event-typesMötestyper
GET/api/v1/availabilityLediga tider
GET/api/v1/bookingsBokningar
POST/api/v1/bookingsSkapa bokning
GET/api/v1/bookings/{id}Enskild bokning
POST/api/v1/bookings/{id}/cancelAvboka bokning

Exempel

Bokningar inom ett tidsintervall

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

Lediga tider för nästa vecka

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

Skapa en bokning

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

Starttiden måste vara en av de lediga tiderna i svaret från /availability; annars blir svaret 409.

Avboka en bokning

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

Vid avbokning återbetalas en eventuell förskottsbetalning i sin helhet, kalenderhändelsen tas bort och kunden får ett avbokningsmeddelande.

Fel

Felsvar har alltid samma format (texten i message är på finska):

{ "error": { "code": "conflict", "message": "Aika ei ole enää vapaana. Valitse toinen aika." } }
  • 400 invalid_request: ett fält saknas eller är ogiltigt
  • 401 unauthorized: nyckeln saknas, är ogiltig eller har raderats
  • 403 plan_required: kontot har inte Pro-paketet
  • 404 not_found: bokningen eller mötestypen finns inte i det här kontot
  • 409 conflict: tiden är inte ledig eller alla platser är tagna
  • 429 rate_limited: anropsgränsen har överskridits

Webhooks (händelser)

Calendo kan skicka information om nya (booking.created), avbokade (booking.cancelled) och flyttade (booking.rescheduled) bokningar till en adress du anger. Webhooks läggs till under Inställningar → Integrationer → Webhooks och Zapier (Growth och Pro).

Innehållet är JSON: { "event": "booking.created", "createdAt": "…", "data": { …varaus… } }, där bokningen har samma format som API:ets Booking. Varje anrop signeras med headern Calendo-Signature: t=<unix-tid>,v1=<HMAC-SHA256>, där HMAC beräknas med webhookens hemlighet över strängen <t>.<innehåll>. En misslyckad leverans görs om efter 1, 5 och 30 minuter samt efter 2 och 12 timmar.

Zapier

För att ansluta Zapier räcker Zapiers egna "Webhooks by Zapier"-funktioner; ingen separat Calendo-app behövs. Observera att Webhooks by Zapier är en premiumapp i Zapier som kräver ett betalt Zapier-paket.

Trigger: ny, avbokad eller flyttad bokning

  1. Skapa triggern Webhooks by Zapier → Catch Hook i din Zap och kopiera dess adress.
  2. I Calendo: Inställningar → Integrationer → Webhooks och Zapier, klistra in adressen och välj händelser.
  3. Tryck på Skicka test i Calendo för att kontrollera anslutningen. Gör sedan en riktig bokning (testbokningar skickar inga webhooks) och hämta den som exempel i Zapier.
  4. Bokningens uppgifter (kund, tid, tjänst, hanteringslänk) visas i Zapier som fält du kan välja i de följande stegen.

Åtgärd: skapa eller avboka en bokning, hämta bokningar

  1. Lägg till åtgärden Webhooks by Zapier → Custom Request.
  2. Method POST, URL https://calendo.fi/api/v1/bookings, Data till exempel {"eventType":"konsultaatio","startsAt":"…","name":"…","email":"…"}.
  3. Headers: Authorization = Bearer cal_live_… och Content-Type = application/json.
  4. Avbokning: Method POST, URL https://calendo.fi/api/v1/bookings/ID/cancel.

En egen Calendo-app i Zapiers appkatalog (färdiga "Calendo"-triggers och -åtgärder utan Webhooks by Zapier) kräver att appen byggs på Zapiers utvecklarplattform och går igenom Zapiers egen granskning och publicering. Det har inte gjorts ännu. API:et och OpenAPI-beskrivningen räcker som grund för den.

Make (tidigare Integromat)

  1. Trigger: lägg till Webhooks → Custom webhook i ditt scenario, kopiera adressen och lägg till den i Calendo under Inställningar → Integrationer → Webhooks och Zapier. Gör därefter en bokning (till exempel åt dig själv och avboka den sedan) så att Make känner igen bokningens datastruktur. Testbokningar skickar inga webhooks.
  2. Åtgärd: lägg till HTTP → Make a request. URL till exempel https://calendo.fi/api/v1/bookings, Method POST, Headers Authorization: Bearer cal_live_…, Body type Raw, Content type JSON och innehållet som ovan. Välj Parse response.
  3. Hämta bokningar: Method GET, URL https://calendo.fi/api/v1/bookings?from=…&sort=-createdAt.

Du kan också bygga en egen Calendo-app i Make (Custom app). Den blir offentlig i Makes appkatalog först efter att Make har granskat den.