Tapaamiset #

Appointments API:n avulla voit varata aikoja yhteyshenkilöillesi tapahtumatyypeillesi sekä hakea, listata, päivittää, peruuttaa tai poistaa niitä. Se vastaa myös useimmissa varausprosesseissa ensimmäisenä esiin nousevaan kysymykseen – mitkä ajat ovat todella vapaita – ja kattaa kalenteripuolen: yhdistettyjen Google-kalenterien listaamisen ja niissä jo olevien tapahtumien tuomisen. Kun Google-kalenteriyhteys on aktiivinen, vastaava kalenteritapahtuma luodaan ja pidetään automaattisesti synkronoituna taustalla. Ravintolat, jotka käyttävät Zenchefiä, Formitablea, OpenTablea tai TheForkia omana varausjärjestelmänään, voidaan myös vahvistaa ja yhdistää täällä, jolloin tekoälyagentti varaa oikeita pöytiä sisäisten tapaamisten sijaan – ja tapaamispohjaiset yritykset, jotka hallinnoivat aikataulujaan Trafftissa, voivat yhdistää ne samalla tavalla.

Kaikki tämän sivun polut ovat suhteessa perus-URL-osoitteeseen https://api.youraiconnector.com/v1. Jokainen pyyntö vaatii API-avaimesi – katso todennus nähdäksesi täydellisen listan tavoista lähettää se. Alla olevissa esimerkeissä käytetään X-API-Key-otsikkoa, ja yhdessä cURL-esimerkissä näytetään myös ?apiKey=-kyselylomake.

Tapahtumat vs. tapaamiset: Tapahtumatyyppi on varattavissa olevan ajan määrittely (tapaamisen tyyppi, kesto, huoneet). Tapaaminen on yksi varattu ilmentymä tapahtumatyypistä tietylle yhteyshenkilölle. Varaat tapaamisen viittaamalla yhteyshenkilöön ja tapahtumatyyppiin.

Tapaamisobjekti #

Jokainen päätepiste, joka palauttaa tapaamisen, käyttää samaa rakennetta:

Tietoja kalenterisynkronoinnista: Heti tapaamisen varaamisen tai muuttamisen jälkeen google_calendar_event_id voi yhä olla null ja calendar_synced voi olla false, koska synkronointi suoritetaan taustalla hetkeä myöhemmin. Hae tapaaminen uudelleen hetken kuluttua nähdäksesi täytetyt kalenterikentät.

Etsi vapaita aikoja #

GET /appointments/available-slots

Palauttaa ajat, jotka ovat todellisuudessa vapaita tietylle tapahtumatyypille kahden ajankohdan välillä. Tämä on yleensä ensimmäinen kutsu varausprosessissa: näytä nämä ajat, anna henkilön valita yksi ja lähetä sitten valittu aika osoitteeseen Varaa aika.

Vastaus ottaa jo huomioon tapahtumatyypin omat aukioloajat ja varauksen keston, sen huoneet, jo varaamasi ajat sekä kaiken yhdistetyissä Google-kalentereissa estetyn – joten täältä palautuva aika on sellainen, jonka voit varata.

Tulokset palautetaan päivittäin ryhmiteltyinä – ja kun tapahtumatyyppi käyttää huoneita, yksi ryhmä per huone per päivä:

Jokaisella available_slots-kohdan merkinnällä on:

Ajat ovat tapahtumatyypin paikallista aikaa, eivät UTC-aikaa. date, start_time ja end_time ovat kellonaikoja tapahtumatyypin omassa aikavyöhykkeessä (sen ohitusasetus tai tilisi aikavyöhyke, jos ohitusta ei ole). Varaa aika odottaa ISO 8601 UTC -hetkeä, joten muunna valitsemasi aika ennen sen lähettämistä.

cURL

curl "https://api.youraiconnector.com/v1/appointments/available-slots?event_id=event_xyz789&start_time=2026-06-15T00:00:00.000Z&end_time=2026-06-19T00:00:00.000Z" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  event_id: "event_xyz789",
  start_time: "2026-06-15T00:00:00.000Z",
  end_time: "2026-06-19T00:00:00.000Z",
});
const res = await fetch(
  `https://api.youraiconnector.com/v1/appointments/available-slots?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.data);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments/available-slots",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "event_id": "event_xyz789",
        "start_time": "2026-06-15T00:00:00.000Z",
        "end_time": "2026-06-19T00:00:00.000Z",
    },
)
print(res.json()["data"])

Vastaus (200 OK):

{
  "success": true,
  "data": [
    {
      "date": "15/06/2026",
      "day": "monday",
      "room_name": "Room A",
      "available_slots": [
        { "start_time": "10:00", "end_time": "10:30", "available": true },
        { "start_time": "10:30", "end_time": "11:00", "available": true }
      ]
    },
    {
      "date": "16/06/2026",
      "day": "tuesday",
      "room_name": "Room A",
      "available_slots": [
        { "start_time": "09:00", "end_time": "09:30", "available": true, "spots_left": 2 }
      ]
    }
  ]
}

Päivä, jolloin ei ole mitään vapaata, ei yksinkertaisesti näy. Puuttuva event_id, start_time tai end_time palauttaa 400; tapahtumatyyppi, joka ei kuulu tilillesi, palauttaa 404.

Varaa tapaaminen #

POST /appointments

Luo varauksen yhdelle yhteyshenkilöistäsi. Sitä voi käyttää kahdella tavalla:

• Yhdellä tapahtumatyypeistäsi — lähetä event_id, ja varaus toimii täsmälleen kuten aina ennenkin: saatavuutta ja kapasiteettia noudatetaan, päättymisaika lasketaan tapahtumatyypin keston perusteella, ja varaus synkronoidaan Google-kalenteriisi, kun sellainen on yhdistetty.
• Ulkoisena varauksena — jätä event_id pois ja lähetä sen sijaan title. Tämä tallentaa varauksen, joka on tehty muualla (omassa CRM-järjestelmässäsi, kurssiaikataulussa, toisessa varaustyökalussa), jotta se näkyy Varaus-sivulla muiden joukossa.

Huoneita sisältävän tapahtumatyypin varauksen on oltava ajankohta, jonka Etsi vapaita aikoja tarjoaisi: huoneen aukioloaikojen sisällä, varoitusajan ulkopuolella, tapahtumatyypin sallitun varausikkunan puitteissa, aikaväliruudukossa, ei menneisyydessä eikä estettynä yhdistetyssä kalenterissa. Kaikki muut ajat hylätään virheellä 400, eikä mitään luoda. Sama koskee room_name, joka ei vastaa yhtäkään tapahtumatyypin huonetta (viesti luettelee kelvolliset nimet). Tapahtumatyypille määritetyt puskuriajat (Puskuri ennen ja Puskuri jälkeen tapahtumatyypin muokkaimessa, buffer_before ja buffer_after minuutteina) pidetään vapaina jokaisen varauksen ympärillä.

Tapahtumatyypin varaukselle tehdään myös ristiriitatarkistus: jos aika on jo varattu, pyyntö epäonnistuu virheellä 409, eikä mitään luoda. Ulkoisella varauksella ei ole taustalla tapahtumatyyppiä, joten mitään ei tarkisteta saatavuuttasi tai kapasiteettiasi vasten, eikä mitään synkronoida kalenteriin.

Uudelleenyrittäminen on turvallista. Jos samalla yhteyshenkilöllä on jo vahvistettu varaus samalle tapahtumatyypille samana alkamisajankohtana (samassa huoneessa, jos sellainen on määritetty), esimerkiksi siksi, että ensimmäinen pyyntösi aikakatkaistiin sen jälkeen, kun se meni läpi, saat kyseisen varauksen takaisin virheellä 200 ja "replayed": true toisen varauksen tai virheen 409 sijaan.

external_reference toimii idempotenttiavaimena. Se on tilikohtaisesti yksilöllinen: jos tapaamisella on jo lähettämäsi viite, kyseinen tapaaminen palautetaan 200- ja "replayed": true-arvoilla, eikä mitään uutta luoda, vaikka uusintayrityksessä olisi eri aika tai yhteystieto ja riippumatta tapaamisen tilasta. Käytä sitä maksetuissa varauksissa (lähetä maksu- tai tilausnumerosi) ja lähetä uusi viite aidosti uudelle varaukselle.

Lähetä event_id ja title yhdessä, tai ei kumpaakaan, jolloin pyyntö palauttaa 400 — samoin käy, jos lähetät sekä end_time että duration_minutes.

cURL (käyttäen ?apiKey=-kyselylomaketta)

curl -X POST "https://api.youraiconnector.com/v1/appointments?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "start_time": "2026-06-15T10:00:00.000Z",
    "room_name": "Room A"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/appointments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contact_id: "contact_abc123",
    event_id: "event_xyz789",
    start_time: "2026-06-15T10:00:00.000Z",
    room_name: "Room A",
  }),
});
const data = await res.json();
console.log(data.appointment_id);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "contact_id": "contact_abc123",
        "event_id": "event_xyz789",
        "start_time": "2026-06-15T10:00:00.000Z",
        "room_name": "Room A",
    },
)
print(res.json()["appointment_id"])

Vastaus (201 Created):

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678",
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-15T10:00:00.000Z",
    "end_time": "2026-06-15T10:30:00.000Z",
    "created_at": "2026-06-10T09:00:00.000Z",
    "last_modified_at": "2026-06-10T09:00:00.000Z",
    "room_name": "Room A",
    "google_calendar_event_id": null,
    "calendar_synced": false
  }
}

Muualla tehdyn varauksen tallentaminen #

Sama päätepiste, ilman tapahtumatyyppiä: title ja start_time riittävät, ja duration_minutes määrittää keston.

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "contact_abc123",
    "title": "Beginner guitar class",
    "start_time": "2026-06-15T10:00:00.000Z",
    "duration_minutes": 90,
    "external_reference": "class-slot-4812"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/appointments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contact_id: "contact_abc123",
    title: "Beginner guitar class",
    start_time: "2026-06-15T10:00:00.000Z",
    duration_minutes: 90,
  }),
});
const data = await res.json();
console.log(data.appointment_id);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "contact_id": "contact_abc123",
        "title": "Beginner guitar class",
        "start_time": "2026-06-15T10:00:00.000Z",
        "duration_minutes": 90,
    },
)
print(res.json()["appointment_id"])

Vastaus (201 Created):

{
  "success": true,
  "appointment_id": "eFgH5678aBcD1234",
  "appointment": {
    "id": "eFgH5678aBcD1234",
    "contact_id": "contact_abc123",
    "event_id": null,
    "status": "Confirmed",
    "start_time": "2026-06-15T10:00:00.000Z",
    "end_time": "2026-06-15T11:30:00.000Z",
    "created_at": "2026-06-10T09:00:00.000Z",
    "last_modified_at": "2026-06-10T09:00:00.000Z",
    "summary": "Beginner guitar class",
    "google_calendar_event_id": null,
    "calendar_synced": false
  }
}

Ulkoiset varaukset ovat sen jälkeen tavallisia varauksia: ne näkyvät Varaus-sivulla ja Listaa varaukset -kohdassa, niitä voi siirtää, peruuttaa tai poistaa sovelluksessa tai tämän API:n kautta, varauksen vahvistussähköposti lähtee normaalisti, ja Varaus tehty -automaatiotriggeri ja webhook aktivoituvat niille samalla tavalla kuin muillekin API:n kautta tehdyille varauksille. Ainoat erot ovat yllä mainitut — ei saatavuus- tai kapasiteettitarkistusta, ei kalenterisynkronointia, ja event_id pysyy null-tilassa.

Hae tapaaminen #

GET /appointments/{appointmentId}

Palauttaa yksittäisen tapaamisen sen tunnisteen (ID) perusteella, mukaan lukien sen kalenterin synkronointitila.

cURL

curl "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.appointment);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["appointment"])

Vastaus (200 OK):

{
  "success": true,
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-15T10:00:00.000Z",
    "end_time": "2026-06-15T10:30:00.000Z",
    "room_name": "Room A",
    "google_calendar_event_id": "abc123googleevent",
    "calendar_synced": true
  }
}

Listaa tapaamiset #

GET /appointments

Listaa tilisi tapaamiset uusimmasta alkaen käyttäen kursoripohjaista sivutusta.

Muista muutamat säännöt:

• Ilman suodattimia saat kaikki tilin tapaamiset sivu kerrallaan.
• Yhteyshenkilön mukaan — aseta contact_id nähdäksesi yhden yhteyshenkilön vahvistetut tapaamiset. Voit rajata tämän yksittäiseen päivään välittämällä myös date.
• Tilan mukaan — aseta status (ilman contact_id) listataksesi vain Confirmed tai vain Canceled tapaamiset koko tililtä.
• date-suodatin ilman contact_id, tai status=Canceled yhdessä contact_id kanssa, palauttaa 400.

cURL

curl "https://api.youraiconnector.com/v1/appointments?contact_id=contact_abc123&date=2026-06-15" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  contact_id: "contact_abc123",
  date: "2026-06-15",
});
const res = await fetch(
  `https://api.youraiconnector.com/v1/appointments?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.appointments, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"contact_id": "contact_abc123", "date": "2026-06-15"},
)
data = res.json()
print(data["appointments"], data["next_cursor"])

Vastaus (200 OK):

{
  "success": true,
  "appointments": [
    {
      "id": "aBcD1234eFgH5678",
      "contact_id": "contact_abc123",
      "event_id": "event_xyz789",
      "status": "Confirmed",
      "start_time": "2026-06-15T10:00:00.000Z",
      "end_time": "2026-06-15T10:30:00.000Z",
      "calendar_synced": true
    }
  ],
  "next_cursor": null
}

Voit selata tuloksia välittämällä edellisen vastauksen next_cursor seuraavan pyynnön cursor-parametrina. Jatka, kunnes next_cursor on null. Katso Virheet ja sivutus yleisestä sivutusmallista.

Päivitä tapaaminen #

PUT /appointments/{appointmentId}

Muuta tapaamisen ajankohtaa tai sen tietoja. Lähetä vain ne kentät, joita haluat muuttaa — vähintään yksi on pakollinen. Yhdistettyjen alku- ja loppuajan on pysyttävä kronologisessa järjestyksessä (end_time on oltava start_time jälkeen). Muutokset synkronoidaan automaattisesti linkitettyyn kalenteritapahtumaan.

Vahvistetun tapahtumatyypin varauksen siirtämiseen (uusi start_time tai room_name) tehdään ristiriitatarkistus kuten uuteen varaukseen: jo varattu aika vastaa 409, eikä mitään muuteta, ja room_name, joka ei vastaa yhtäkään tapahtumatyypin huonetta, vastaa 400. Lähetä vain start_time, niin varaus säilyttää pituutensa. Omia aukioloaikojasi ja ilmoitusaikaasi ei sovelleta tässä, joten voit silti siirtää varauksen mihin tahansa vapaaseen ajankohtaan.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "2026-06-16T10:00:00.000Z",
    "end_time": "2026-06-16T10:30:00.000Z"
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      start_time: "2026-06-16T10:00:00.000Z",
      end_time: "2026-06-16T10:30:00.000Z",
    }),
  }
);
const data = await res.json();
console.log(data.appointment);

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "start_time": "2026-06-16T10:00:00.000Z",
        "end_time": "2026-06-16T10:30:00.000Z",
    },
)
print(res.json()["appointment"])

Vastaus (200 OK):

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678",
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-16T10:00:00.000Z",
    "end_time": "2026-06-16T10:30:00.000Z",
    "calendar_synced": true
  }
}

Peruuta ajanvaraus #

POST /appointments/{appointmentId}/cancel

Peruuttaa vahvistetun ajanvarauksen ja tallentaa valinnaisesti syyn. Ajanvaraus säilyy tililläsi tilassa Canceled, ja siihen linkitetty kalenteritapahtuma poistetaan automaattisesti taustalla. Jo peruutetun ajanvarauksen peruuttaminen palauttaa virheen 400.

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/cancel" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cancellation_reason": "Client asked to reschedule next month"
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/cancel",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      cancellation_reason: "Client asked to reschedule next month",
    }),
  }
);
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/cancel",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"cancellation_reason": "Client asked to reschedule next month"},
)
print(res.json()["success"])

Vastaus (200 OK):

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678"
}

Lähetä varausvahvistus uudelleen #

POST /appointments/{appointmentId}/resend-confirmation

Lähettää yhteyshenkilölle varausvahvistuksen uudelleen, esimerkiksi jos hän sanoo, ettei se koskaan saapunut tai se päätyi roskapostiin. Koostuu kahdesta osasta, jotka molemmat lähetetään, ellet poista toista käytöstä: vahvistussähköposti (sama sähköposti, jonka yhteyshenkilö sai varauksen yhteydessä) ja, jos tapaaminen on Google-kalenterissasi, Google-kalenterikutsu. Molemmat lähetetään yhteyshenkilön sähköpostiosoitteeseen.

Jokaisella osalla on oma tuloksensa: sent, not_requested, no_contact_email, turned_off_for_event_type (tapahtumatyypin Lähetä tapaamisvahvistus yhteyshenkilölle -valinta on pois päältä), not_on_google_calendar, imported (kalenteristasi tuodut tapaamiset eivät saa vahvistussähköpostia) tai failed.

• 200, kun vähintään yksi osa lähetettiin. recipient on osoite, johon se lähetettiin.
• 409 peruutetulle tapaamiselle, jo päättyneelle tapaamiselle tai Zenchefin, Formitablen, OpenTablen, TheForkin tai Trafft-järjestelmän kautta tehdylle varaukselle (kyseinen järjestelmä lähettää oman vahvistuksensa). code on appointment_canceled, appointment_in_past tai managed_by_provider.
• 422, kun mitään ei voitu lähettää, syy on kohdassa error.

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/resend-confirmation" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/resend-confirmation",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ calendar_invite: false }),
  }
);
const data = await res.json();
console.log(data.email, data.recipient);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/resend-confirmation",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={},
)
print(res.json())

Vastaus (200 OK):

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678",
  "email": "sent",
  "calendar_invite": "sent",
  "recipient": "jane@example.com"
}

Poista ajanvaraus #

DELETE /appointments/{appointmentId}

Poistaa ajanvarauksen ja sen viitteet pysyvästi. Jos haluat vain perua varauksen säilyttäen tietueen, käytä sen sijaan peruutusta.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])

Vastaus (200 OK):

{
  "success": true
}

Listaa yhdistetyt Google-kalenterisi #

GET /appointments/google-calendars

Palauttaa tälle tilille saatavilla olevat Google-kalenterit suoraan Googlesta – hyödyllinen tilin haltijalle näytettävässä valitsimessa, josta valitaan, mistä kalenterista tuodaan tietoja, tai vain yhteyden toimivuuden vahvistamiseen.

Tämä toimii vasta, kun tili on yhdistänyt Google-kalenterin (Asetukset → Integraatiot) vähintään lukuoikeudella. Jos näin ei ole, tai myönnetty käyttöoikeus ei enää sisällä kalenterin lukuoikeutta, saat 400-vastauksen, joka kehottaa yhdistämään sen (uudelleen).

cURL

curl "https://api.youraiconnector.com/v1/appointments/google-calendars" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/appointments/google-calendars", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.data);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments/google-calendars",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["data"])

Vastaus (200 OK):

{
  "success": true,
  "data": [
    {
      "id": "primary",
      "summary": "jane@example.com",
      "timeZone": "America/New_York",
      "accessRole": "owner",
      "primary": true
    },
    {
      "id": "abcdefg1234567890@group.calendar.google.com",
      "summary": "Bookings",
      "timeZone": "America/New_York",
      "accessRole": "writer"
    }
  ]
}

Jokainen merkintä on Googlen oma CalendarListEntry-muoto, joten kenttien nimet noudattavat Googlen camelCase-määrityksiä, eivät tämän rajapinnan tavallisia snake_case-nimiä — kyseessä on Googlen data sellaisenaan, ei meidän. Puuttuva tai peruutettu yhteys palauttaa 400-vastauksen, jossa selitetään, että Google-kalenteri on yhdistettävä (uudelleen).

Tapahtumien tuominen Google-kalenterista #

POST /appointments/import-calendar-events

Hakee kampanjan tai tekoälyagentin yhdistetyssä Google-kalenterissa olevat tapahtumat ja muuttaa ne tapaamisiksi — hyödyllinen, kun yhdistät ensimmäistä kertaa kalenterin, jossa on jo varauksia. Tämä voi viedä aikaa (jokainen tapahtuma käy läpi erotteluprosessin sen selvittämiseksi, kenelle se kuuluu), joten se ei koskaan toimi suoraan pyynnön yhteydessä: pyyntö asettaa taustatyön jonoon ja palauttaa job_id-tunnisteen, jota voit kysellä.

Lähetä täsmälleen joko campaign_id tai agent_id, ei koskaan molempia eikä kumpaakaan — mikä tahansa muu yhdistelmä palauttaa 400-vastauksen. Lähettämäsi kohteen on kuuluttava tiliisi, muuten saat 404-vastauksen.

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments/import-calendar-events?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "identifier": "EMAIL"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/appointments/import-calendar-events", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_id: "agent_abc123",
    identifier: "EMAIL",
  }),
});
const data = await res.json();
console.log(data.job_id);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments/import-calendar-events",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"agent_id": "agent_abc123", "identifier": "EMAIL"},
)
print(res.json()["job_id"])

Vastaus (202 Accepted):

{
  "success": true,
  "job_id": "jK9mQ2xR7pL4wN1t",
  "status": "queued",
  "campaign_id": null,
  "agent_id": "agent_abc123"
}

campaign_id ja agent_id palauttavat sen, minkä lähetit; toinen on aina null.

Tuontityön kysely #

GET /appointments/import-calendar-events/{jobId}

curl "https://api.youraiconnector.com/v1/appointments/import-calendar-events/jK9mQ2xR7pL4wN1t" \
  -H "X-API-Key: YOUR_API_KEY"

Vastaus (200 OK):

{
  "success": true,
  "job_id": "jK9mQ2xR7pL4wN1t",
  "status": "completed",
  "message": "Imported 12 events as appointments.",
  "error": null
}

GET-pyyntö jobId-tunnisteelle, jota ei ole olemassa (tai joka kuuluu eri tilille), palauttaa 404-vastauksen.

Ulkoiset varausintegraatiot (Zenchef / Formitable / OpenTable / TheFork / Trafft) #

Zenchef ja Formitable ovat ravintoloiden varausjärjestelmiä, joiden kautta tekoälyagenttisi voi varata oikeita pöytiä; Trafft on tapaamispohjaisten yritysten aikataulutusalusta, joka yhdistetään kerran tiliä kohden, ei ravintolaa kohden. Molemmilla ravintola-alustoilla on julkinen, todennusta vaatimaton varauswidget (https://api.youraiconnector.com/v1/zenchef-widget/... ja https://api.youraiconnector.com/v1/formitable-widget/...), joka näkyy ruokailijalle chatissa – kyseiset widget-reitit ovat tavallisia HTML-sivuja, jotka on tarkoitettu avattavaksi selaimessa, eivät JSON API -päätepisteitä, joten niitä ei ole dokumentoitu tässä. Seuraavassa esitellään tilinhallinnan päätepisteet: ravintolatunnuksen vahvistaminen tilinhaltijalle kuuluvaksi sekä sen lisääminen, päivittäminen tai poistaminen.

Zenchef #

Zenchef-ravintolan yhdistäminen on kaksivaiheinen vahvistusprosessi, jolla tilinhaltija todistaa hallinnoivansa ravintolaa ennen kuin se yhdistetään bottiin: tarkista ensin, että tunnus on olemassa (paljastamatta nimeä), ja pyydä sitten käyttäjää kirjoittamaan ravintolan nimi itse ja varmista, että se täsmää.

Vaihe 1 — Tarkista, että ravintolan tunnus on olemassa

POST /appointments/zenchef-restaurants/check

curl -X POST "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/check?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345" }'

Vastaus (200 OK):

{
  "success": true,
  "data": { "exists": true, "requiresNameVerification": true }
}

exists: false tarkoittaa, ettei kyseisellä tunnuksella ole Zenchef-ravintolaa — muuta ei tarvitse tehdä. Nopeusrajoitus on 10 tarkistusta 5 minuutissa tiliä kohden; rajan ylittäminen palauttaa 429.

Vaihe 2 — Vahvista ravintolan nimi

POST /appointments/zenchef-restaurants/verify-name

curl -X POST "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/verify-name?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345", "user_input_name": "The Blue Door Bistro" }'

Vastaus (200 OK):

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "id": "12345",
      "name": "The Blue Door Bistro",
      "address": "1 Rue de Rivoli, Paris",
      "status": "active"
    }
  }
}

verified: false tarkoittaa, että nimi ei täsmännyt — restaurantDetails jätetään pois, pyydä tilinhaltijaa yrittämään uudelleen. Nopeusrajoitus on 3 yritystä 5 minuutissa (tiukempi kuin olemassaolon tarkistus, koska tämä on varsinainen todistusvaihe). restaurant_id, joka ei enää vastaa Zenchefissä, palauttaa 404.

Vaihe 3 — Tallenna ravintola

POST /appointments/zenchef-restaurants

curl -X POST "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345", "restaurant_name": "The Blue Door Bistro" }'

Vastaus (201 Created):

{ "success": true, "data": { "restaurantId": "12345" } }

Päivitä tallennettu Zenchef-ravintola

PUT /appointments/zenchef-restaurants/{restaurantId}

curl -X PUT "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/12345" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Vastaus (200 OK): sama muoto kuin yllä olevassa tallennusvastauksessa.

Zenchef-ravintolan poistaminen

DELETE /appointments/zenchef-restaurants/{restaurantId}

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/12345" \
  -H "X-API-Key: YOUR_API_KEY"

Vastaus (200 OK): { "success": true, "data": { "restaurantId": "12345" } }

restaurantId, jota ei ole tällä hetkellä tilillä, palauttaa 404 päivityksen tai poiston yhteydessä.

Formitable #

Formitable ei tarvitse Zenchefin kaksivaiheista nimen vahvistusta — sen ravintolatunnukset on jo rajattu yrityskohtaisesti, joten yksi vahvistuskutsu riittää. Siinä on myös tietojen haku, jota käytetään ravintolan verkkosivuston URL-osoitteen välimuistiin tallentamiseen määrityksen aikana.

Ravintolatunnuksen vahvistaminen

POST /appointments/formitable-restaurants/verify

curl -X POST "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/verify?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "the-blue-door", "language": "en" }'

Vastaus (200 OK):

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "the-blue-door",
      "productCount": 4,
      "sampleProductTitle": "Dinner for two",
      "language": "en"
    }
  }
}

Jos Formitable ei tunnista restaurant_id, se palauttaa 404. Nopeusrajoitus on 10 yritystä 5 minuutin aikana tiliä kohden.

Ravintolan tietojen hakeminen

GET /appointments/formitable-restaurants/{restaurantId}/details?language=en

Hakee ravintolan julkisen profiilin Formitablesta, mukaan lukien sen verkkosivuston — käytetään verkkosivuston URL-osoitteen välimuistiin tallentamiseen ravintolaa määritettäessä. language on valinnainen kyselyparametri, jonka oletusarvo on "en".

curl "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/the-blue-door/details?language=en" \
  -H "X-API-Key: YOUR_API_KEY"

Vastaus (200 OK):

{
  "success": true,
  "data": {
    "uid": "the-blue-door",
    "name": "The Blue Door Bistro",
    "website": "https://thebluedoorbistro.com",
    "email": "info@thebluedoorbistro.com",
    "telephone": "+31201234567",
    "streetAddress": "Prinsengracht 1",
    "zipcode": "1015 AB",
    "city": "Amsterdam",
    "country": "Netherlands",
    "countryCode": "NL",
    "currency": "EUR"
  }
}

Tallenna ravintola

POST /appointments/formitable-restaurants

curl -X POST "https://api.youraiconnector.com/v1/appointments/formitable-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "restaurant_id": "the-blue-door",
    "restaurant_name": "The Blue Door Bistro",
    "language": "en",
    "website_url": "https://thebluedoorbistro.com"
  }'

Vastaus (201 Created): { "success": true, "data": { "restaurantId": "the-blue-door" } }

Päivitä tallennettu Formitable-ravintola

PUT /appointments/formitable-restaurants/{restaurantId}

curl -X PUT "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/the-blue-door" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Vastaus (200 OK): sama muoto kuin yllä olevassa tallennusvastauksessa.

Poista Formitable-ravintola

DELETE /appointments/formitable-restaurants/{restaurantId}

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/the-blue-door" \
  -H "X-API-Key: YOUR_API_KEY"

Vastaus (200 OK): { "success": true, "data": { "restaurantId": "the-blue-door" } }

restaurantId, jota ei ole tällä hetkellä tilillä, palauttaa 404 päivityksen tai poiston yhteydessä.

OpenTable #

OpenTable-ravintoloihin otetaan yhteys alustan OpenTable-kumppanitunnuksilla, ja OpenTable sallii näiden tunnusten nähdä vain ne ravintolat, jotka ovat yhdistäneet alustan listauksen OpenTablen integraatiomarkkinapaikassa. Kuten Formitablen kohdalla, yksi vahvistuskutsu riittää: tavoitettavissa oleva ravintolatunnus (numeerinen “RID”) todistaa sekä ravintolan olemassaolon että sen, että se on yhdistänyt integraation. Ennen kuin OpenTable-kumppanilistaus on otettu käyttöön alustalla, vahvistuskutsu vastaa 503.

Vahvista OpenTable-ravintola

POST /appointments/opentable-restaurants/verify

curl -X POST "https://api.youraiconnector.com/v1/appointments/opentable-restaurants/verify?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "1038007" }'

Vastaus (200 OK):

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "1038007",
      "diningAreaCount": 2,
      "diningAreaNames": ["Main Room", "Garden"],
      "tableTypes": ["default", "outdoor", "bar"]
    }
  }
}

verified: false tarkoittaa, ettei millään OpenTable-ravintolalla ole kyseistä tunnusta. 403 tarkoittaa, että ravintola on olemassa, mutta se ei ole vielä yhdistänyt alustan integraatiota OpenTablessa. Nopeusrajoitus on 10 yritystä 5 minuutissa tiliä kohden.

Lisää OpenTable-ravintola

POST /appointments/opentable-restaurants

curl -X POST "https://api.youraiconnector.com/v1/appointments/opentable-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "1038007", "restaurant_name": "The Blue Door", "website_url": "https://thebluedoor.example" }'

Vastaus (201 Created): { "success": true, "data": { "restaurantId": "1038007" } }

Päivitä tallennettu OpenTable-ravintola

PUT /appointments/opentable-restaurants/{restaurantId}

Lähetä mikä tahansa kentistä restaurant_name, is_active (tauko false:lla) tai website_url (tyhjä merkkijono tyhjentää sen); pois jätettyjä kenttiä ei muuteta.

curl -X PUT "https://api.youraiconnector.com/v1/appointments/opentable-restaurants/1038007" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Vastaus (200 OK): { "success": true, "data": { "restaurantId": "1038007" } }

Poista OpenTable-ravintola

DELETE /appointments/opentable-restaurants/{restaurantId}

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/opentable-restaurants/1038007" \
  -H "X-API-Key: YOUR_API_KEY"

Vastaus (200 OK): { "success": true, "data": { "restaurantId": "1038007" } }

Jos restaurantId ei ole tällä hetkellä tilillä, päivitys palauttaa 404.

TheFork #

TheFork-ravintoloihin otetaan yhteys alustan TheFork-kumppanitunnuksilla, ja TheFork sallii näiden tunnusten nähdä vain ne ravintolat, joilla kyseisen alustan kumppanuus on otettu käyttöön niiden TheFork-tilillä. Kuten Formitablen ja OpenTablen kohdalla, yksi vahvistuskutsu riittää: tavoitettavissa oleva ravintolatunnus (Restaurant ID) todistaa sekä ravintolan olemassaolon että sen, että kumppanuus on käytössä. Tunnus on UUID, jonka TheFork antaa ravintolalle TheFork Managerissa, ja se lähetetään merkkijonona. Ennen kuin TheFork on hyväksynyt alustan kumppaniksi ja myöntänyt tunnukset, vahvistuskutsu vastaa 503 – katso TheFork nähdäksesi, mitä se tarkoittaa nykyään.

Vahvista TheFork-ravintola

POST /appointments/thefork-restaurants/verify

curl -X POST "https://api.youraiconnector.com/v1/appointments/thefork-restaurants/verify?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" }'

Vastaus (200 OK):

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60",
      "partySizes": [1, 2, 3, 4, 5, 6, 7, 8]
    }
  }
}

partySizes ovat seuruekoot, joita ravintola ottaa vastaan verkossa seuraavan 30 päivän aikana. 404 tai 403 tarkoittaa, ettei TheFork antanut meille ravintolaa kyseisellä tunnuksella – joko tunnus on väärä tai alustan kumppanuus ei ole vielä käytössä kyseisessä ravintolassa; 400 tarkoittaa, ettei tunnus ole UUID. Nopeusrajoitus on 10 yritystä 5 minuutissa tiliä kohden.

Lisää TheFork-ravintola

POST /appointments/thefork-restaurants

curl -X POST "https://api.youraiconnector.com/v1/appointments/thefork-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60", "restaurant_name": "The Blue Door", "website_url": "https://thebluedoor.example" }'

Vastaus (201 Created): { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

Päivitä tallennettu TheFork-ravintola

PUT /appointments/thefork-restaurants/{restaurantId}

Lähetä mikä tahansa kentistä restaurant_name, is_active (tauko false:lla) tai website_url (tyhjä merkkijono tyhjentää sen); pois jätettyjä kenttiä ei muuteta.

curl -X PUT "https://api.youraiconnector.com/v1/appointments/thefork-restaurants/9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Vastaus (200 OK): { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

Poista TheFork-ravintola

DELETE /appointments/thefork-restaurants/{restaurantId}

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/thefork-restaurants/9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" \
  -H "X-API-Key: YOUR_API_KEY"

Vastaus (200 OK): { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

restaurantId, jota ei ole tällä hetkellä tilillä, palauttaa 404 päivityksen tai poiston yhteydessä.

Trafft #

Trafft yhdistetään kerran koko tilille, ei toimipistettä kohden: yksi yrityksen osoite sekä API-tunnistetiedot Trafft-hallintapaneelista (Features & Integrations → API & Connectors, osa Trafftin Business-pakettia). Yhteyskutsu tarkistaa nämä tunnistetiedot Trafftia vasten ennen tallennusta, joten väärä osoite, väärät tunnistetiedot tai paketti ilman API-käyttöoikeutta aiheuttavat virheen tässä vaiheessa eikä vasta asiakaskeskustelun aikana. Asiakassalaisuus (client secret) tallennetaan salattuna, eikä sitä palauteta koskaan minkään päätepisteen kautta.

Kaikki kolme kirjoituskutsua (POST, PUT, DELETE) vaativat Integraatioiden muokkausoikeuden; tila GET vaatii Integraatioiden katseluoikeuden.

Yhdistä Trafft

POST /appointments/trafft/connect

curl -X POST "https://api.youraiconnector.com/v1/appointments/trafft/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain": "acme",
    "client_id": "YOUR_TRAFFT_CLIENT_ID",
    "client_secret": "YOUR_TRAFFT_CLIENT_SECRET",
    "company_name": "Acme Salon"
  }'

Vastaus (200 OK):

{
  "success": true,
  "data": {
    "subdomain": "acme",
    "service_count": 12,
    "employee_count": 4,
    "location_count": 2
  }
}

Määrät palautuvat Trafftista tarkistuksen aikana – ne ovat nopein tapa varmistaa, että tunnistetiedot osoittavat haluamaasi tiliin.

Hae yhteyden tila

GET /appointments/trafft

curl "https://api.youraiconnector.com/v1/appointments/trafft" \
  -H "X-API-Key: YOUR_API_KEY"

Vastaus (200 OK):

{
  "success": true,
  "data": {
    "connected": true,
    "subdomain": "acme",
    "hostname": "acme.admin.trafft.com",
    "client_id": "YOUR_TRAFFT_CLIENT_ID",
    "company_name": "Acme Salon",
    "is_active": true,
    "service_count": 12,
    "employee_count": 4,
    "location_count": 2
  }
}

connected: false tarkoittaa, ettei mitään ole vielä määritetty. Asiakassalaisuutta ei koskaan sisällytetä tähän vastaukseen.

Päivitä yhteys

PUT /appointments/trafft

curl -X PUT "https://api.youraiconnector.com/v1/appointments/trafft" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Vastaus (200 OK): sama yhteysolio kuin yllä olevassa GET-kohdassa.

Katkaise Trafft-yhteys

DELETE /appointments/trafft

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/trafft" \
  -H "X-API-Key: YOUR_API_KEY"

Vastaus (200 OK): { "success": true }

Yhteyden katkaiseminen poistaa vain tallennetut tunnistetiedot. Trafft-palvelussa jo oleviin varauksiin ei kosketa.

Virheen muoto kaikissa Zenchef/Formitable/OpenTable/TheFork-päätepisteissä: toisin kuin muualla tällä sivulla, virheet sisältävät tässä tilan kahdesti – kerran HTTP-tilana ja kerran error_code-kenttänä rungossa – esimerkiksi { "success": false, "error": "Restaurant not found", "error_code": 404 }. Käsittele se samalla tavalla kuin mikä tahansa muu virhe: tarkista success ja lue viesti kohdasta error.

Appointments-rajapinnan virheet #

Ajanvarauksen päätepisteet palauttavat vakioidun virhekuoren:

{
  "success": false,
  "error": "Appointment not found"
}

Jaetut koodit, joita jokainen päätepiste voi palauttaa — 401, 403 (tilauksesi ei sisällä API-käyttöoikeutta), 429 (nopeusrajoitus) ja 500 — on lueteltu uudelleenyritysohjeiden kera kohdassa Virheet ja sivutus.

Seuraavat vaiheet #

• Yhteystiedot — luo ja etsi yhteystietoja, joille teet varauksia.
• Viestit ja keskustelut — lähetä yhteystiedolle vahvistus tai muistutus.
• Webhooks — saat ilmoituksen, kun varaukset muuttuvat.