Tapaamiset #

Appointments API:n avulla voit varata aikoja yhteyshenkilöillesi tapahtumatyypeillesi sekä hakea, listata, päivittää, perua tai poistaa niitä. Se vastaa myös useimpien varausprosessien ensimmäiseen kysymykseen – mitkä ajat ovat todellisuudessa vapaita – ja kattaa kalenteripuolen: yhdistettyjen Google-kalentereiden 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ä tai Formitablea omana varausjärjestelmänään, voidaan myös vahvistaa ja yhdistää täällä, jolloin tekoälyagentti varaa oikeita pöytiä sisäisten tapaamisten sijaan.

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

Varaa uuden tapaamisen yhteyshenkilölle jollekin tapahtumatyypillesi. Päättymisaika lasketaan automaattisesti tapahtumatyypin keston perusteella.

Varaukselle tehdään ristiriitatarkistus: jos pyydetty aika menee päällekkäin olemassa olevan vahvistetun tapaamisen kanssa samalla tapahtumatyypillä, pyyntö epäonnistuu virheellä 409 eikä mitään luoda.

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
  }
}

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.

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"
}

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.

Ravintolavarausintegraatiot (Zenchef / Formitable) #

Zenchef ja Formitable ovat ravintolavarausjärjestelmiä, joiden kautta tekoälyagenttisi voi tehdä oikeita pöytävarauksia. Molemmilla on julkinen, tunnistautumaton varauswidget (https://api.youraiconnector.com/v1/zenchef-widget/... ja https://api.youraiconnector.com/v1/formitable-widget/...), joka näkyy ruokailijalle chatin sisällä — kyseiset widget-reitit ovat tavallisia HTML-sivuja, jotka on tarkoitettu avattavaksi selaimessa, eivät JSON-rajapintapäätepisteitä, joten niitä ei ole dokumentoitu tässä. Seuraavassa on tilinhallinnan päätepisteet: ravintolatunnuksen omistajuuden varmentaminen sekä ravintolan 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ä.

Virheen muoto kaikissa Zenchef/Formitable-päätepisteissä: toisin kuin muualla tällä sivulla, virheet tässä sisältävät 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, lue error viestin saamiseksi.

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.