予約

Appointments APIを使用すると、連絡先の予約をイベントタイプに基づいて行い、取得、一覧表示、更新、キャンセル、削除することができます。また、ほとんどの予約フローで最初に発生する「どの時間が実際に空いているか」という疑問に答え、カレンダー側（接続済みのGoogleカレンダーの一覧表示や、既存のイベントのインポート）もカバーします。Googleカレンダーの接続が有効な場合、対応するカレンダーイベントが自動的にバックグラウンドで作成され、同期が維持されます。Zenchef、Formitable、OpenTable、またはTheForkを独自の予約システムとして使用しているレストランもここで検証および接続できるため、AIエージェントは内部的な予定ではなく実際のテーブルを予約します。Trafftでスケジュールを管理している予約ビジネスも同様の方法で接続可能です。

このページのすべてのパスは、ベースURL https://api.youraiconnector.com/v1 からの相対パスです。すべてのリクエストにはAPIキーが必要です。送信方法の全リストについては認証を参照してください。以下の例では X-API-Key ヘッダーを使用しており、1つのcURL例では ?apiKey= クエリ形式も示しています。

イベントと予約の違い: イベントタイプとは、予約可能なスロットの定義（会議の種類、長さ、部屋など）です。予約とは、特定の連絡先に対してイベントタイプを予約した1つのインスタンスです。連絡先とイベントタイプを参照することで予約を行います。

予約オブジェクト

予約を返す各エンドポイントは、同じ形式を使用します。

フィールド	説明
`id`	アポイントメントの一意のID。
`contact_id`	アポイントメントが予約された連絡先のID。
`event_id`	アポイントメントが予約されたイベントタイプのID。外部予約（イベントタイプなしで記録されたアポイントメント）の場合は `null` となります。
`status`	`Confirmed` または `Canceled`。
`start_time`	アポイントメントの開始日時。ISO 8601形式（UTC）。
`end_time`	アポイントメントの終了日時。ISO 8601形式（UTC）。
`created_at`	アポイントメントが作成された日時。
`last_modified_at`	アポイントメントが最後に変更された日時。
`room_name`	イベントタイプで会議室を使用している場合、アポイントメントが予約されている会議室またはリソース。
`description`	アポイントメントの自由形式の説明。
`summary`	短い概要またはタイトル。外部予約の場合、これは記録時に使用された `title` です。
`external_reference`	この予約に対する独自のID（CRMや予約システムからのもの）。送信したままの値、または `null` となります。
`cancelation_reason`	アポイントメントがキャンセルされた場合、その理由。
`google_calendar_event_id`	リンクされたGoogleカレンダーイベントのID。カレンダー同期が完了すると設定されます。カレンダーが接続されていない場合、または同期が進行中の場合は `null` となります。
`calendar_synced`	アポイントメントがカレンダーイベントにリンクされると `true` になります。
`imported`	アポイントメントが直接予約されたのではなく、外部カレンダーからインポートされた場合は `true` となります。
`is_recurring`	アポイントメントが定期的なシリーズの一部である場合は `true` となります。
`recurrence_frequency`	定期的な場合、アポイントメントが繰り返される頻度。
`recurring_event_id`	このアポイントメントが属する定期的なシリーズのID。
`recurring_interval`	定期的な場合、繰り返し間隔。
`recurring_sequence`	定期的なシリーズ内におけるこのアポイントメントの位置。
`end_after_x_occurrences`	定期的なシリーズが終了するまでの発生回数。
`booking_provider`	接続された予約プロバイダーを通じて予約された場合、予約元のシステム。

カレンダー同期について: 予約の直後や変更直後は、同期がバックグラウンドで少し遅れて実行されるため、google_calendar_event_id が null のまま、calendar_synced が false になっている場合があります。少し時間を置いてから予約を再度取得すると、カレンダーのフィールドが反映されていることが確認できます。

空き枠の検索

GET /appointments/available-slots

2つの時点の間で、特定のイベントタイプにおいて実際に空いている時間を返します。これは通常、予約フローにおける最初の呼び出しとなります。これらの枠を表示し、ユーザーに1つ選択してもらい、その選択された時間を予約の登録にPOSTします。

この回答には、イベントタイプ自体の営業時間と枠の長さ、部屋、すでに予約済みの予定、および接続されたGoogleカレンダーでブロックされているすべての予定がすでに考慮されています。そのため、ここで返される枠は予約可能なものとなります。

クエリパラメータ	必須	説明
`event_id`	はい	確認するイベントタイプ。アカウントに属している必要があります。アプリの「Appointments」ページ（「Event Types」タブ）でイベントタイプを開くと確認できます。編集ウィンドウに「Event type ID」とコピーボタンが表示されます。
`start_time`	はい	スロットを取得する期間の開始日時（ISO 8601形式）。
`end_time`	はい	期間の終了日時（ISO 8601形式）。終了日全体が含まれます。

結果は日ごとにグループ化されて返されます。イベントタイプで部屋を使用している場合は、日ごと、かつ部屋ごとにグループ化されます。

フィールド	説明
`date`	グループが対象とする日付（`DD/MM/YYYY`形式）。
`day`	曜日の小文字表記（例: `monday`）。
`room_name`	イベントタイプで部屋を使用している場合、このグループが属する部屋またはリソース。
`available_slots`	その日の予約可能なブロック（早い順）。

available_slotsの各エントリには以下が含まれます。

フィールド	説明
`start_time`	ブロックの開始時刻（`HH:mm`形式）。
`end_time`	ブロックの終了時刻（`HH:mm`形式）。
`available`	`true` — 空き時間のみが返されます。
`spots_left`	このブロックにあと何件の予約が可能か。1つの枠で複数の予約を受け付けるイベントタイプの場合のみ表示されます。

時間はUTCではなく、イベントタイプのローカル時間です。 date、start_time、およびend_timeは、イベントタイプ自身のタイムゾーン（オーバーライド設定、または設定がない場合はアカウントのタイムゾーン）における時計の時刻です。予約の登録ではISO 8601形式のUTC時刻が期待されるため、選択した枠をPOSTする前に変換してください。

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"])

レスポンス (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 }
      ]
    }
  ]
}

空きがない日は単純に表示されません。event_id、start_time、またはend_timeが欠落している場合は400が返されます。アカウントに存在しないイベントタイプを指定した場合は404が返されます。

予約の登録

POST /appointments

連絡先のアポイントメントを作成します。使用方法は2通りあります。

イベントタイプで予約する場合 — event_id を送信します。予約はこれまで通り機能します。空き状況と定員が考慮され、終了時間はイベントタイプのスロット時間から計算され、Googleカレンダーが接続されていればアポイントメントが同期されます。
外部予約として予約する場合 — event_id を省略し、代わりに title を送信します。これにより、他の場所（独自のCRM、クラススケジュール、別の予約ツールなど）で行われた予約を記録し、他の予約と一緒に「アポイントメント」ページに表示させることができます。

会議室を使用するイベントタイプの予約は、空きスロットを検索で提示される時間枠内である必要があります。具体的には、会議室の営業時間内、通知期間外、イベントタイプで予約可能な期間内、スロットグリッド上であり、過去の日時ではなく、接続されたカレンダーでブロックされていない必要があります。これ以外の時間は 400 で拒否され、何も作成されません。イベントタイプのどの会議室にも一致しない room_name も同様です（メッセージには有効な名前が一覧表示されます）。イベントタイプで設定されたバッファ時間（イベントタイプエディターの Buffer before および Buffer after、単位は buffer_before と buffer_after 分）は、すべての予約の前後で確保されます。

イベントタイプの予約には競合チェックも行われます。スロットがすでに埋まっている場合、リクエストは 409 で失敗し、何も作成されません。外部予約には背後にイベントタイプが存在しないため、可用性やキャパシティに対するチェックは行われず、カレンダーへの同期も行われません。

再試行は安全です。同じ連絡先が同じイベントタイプで同じ開始時間に（名前を指定した場合は同じ会議室で）すでに確定した予約を持っている場合（例えば、最初のリクエストが処理された後にタイムアウトした場合など）、2つ目の予約や 409 が作成される代わりに、その予約が 200 および "replayed": true とともに返されます。

external_reference は冪等性キーとして機能します。これはアカウント内で一意です。送信した参照IDを持つ予約が既に存在する場合、その予約が 200 と "replayed": true とともに返され、新しい予約は作成されません。これは、再試行時に異なる時間や連絡先を指定した場合や、その予約のステータスがどのような状態であっても同様です。有料予約にはこれを使用し（支払いIDや注文IDを送信）、純粋に新しい予約の場合は新しい参照IDを送信してください。

フィールド	必須	説明
`contact_id`	はい	予約対象の連絡先のID。アカウントに属している必要があります。
`start_time`	はい	希望する開始日時（ISO 8601形式）。タイムゾーンオフセットなしで送信された時間は、アカウントのタイムゾーンで読み取られます。
`event_id`	いいえ	予約するイベントタイプのID。アカウントに属している必要があります。外部予約を記録する場合は省略してください。
`title`	`event_id` なしの場合のみ	予約ページに表示される予約名（例：クラス名）。最大200文字。戻り値は `summary` となります。
`end_time`	いいえ	外部予約の終了日時（ISO 8601形式）。`start_time` より後の時間である必要があります。`event_id` を使用する場合は不要です（終了時間はイベントタイプのスロット期間から算出されます）。
`duration_minutes`	いいえ	外部予約の所要時間（1〜1440の整数）。または `end_time` のいずれかを使用してください（両方は不可）。どちらも指定しない場合、外部予約は60分間となります。
`description`	いいえ	予約に保持する自由形式のメモ。
`room_name`	いいえ	イベントタイプで部屋を使用する場合の部屋またはリソース名。いずれかの部屋と一致する必要があります。省略した場合は、最初の空き部屋が予約されます。
`external_reference`	いいえ	CRMや予約システムの記録と照合するための独自の予約ID。最大255文字。すべての読み取り時、および予約完了・キャンセル・再スケジュール時のWebhookで返されます。アカウント内で一意です。既に使用されている参照IDを指定すると、再予約は行われず、その予約が返されます（上記参照）。

event_id と title を両方送信するか、両方送信しない場合、リクエストは 400 を返します。end_time と duration_minutes を両方送信した場合も同様です。

cURL (?apiKey= クエリ形式を使用)

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"])

レスポンス (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
  }
}

他の場所で行われた予約の記録

イベントタイプなしで同じエンドポイントを使用します。title と start_time だけで十分であり、duration_minutes で所要時間を設定します。

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"])

レスポンス (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
  }
}

外部予約は、それ以降は通常のアポイントメントとして扱われます。「アポイントメント」ページやアポイントメントの一覧取得に表示され、アプリ内やこのAPIを通じて再スケジュール、キャンセル、削除が可能です。予約通知メールも通常通り送信され、アポイントメント予約の自動化トリガーやWebhookも、API経由で行われた他の予約と同様に実行されます。唯一の違いは前述の通り、空き状況や定員のチェックが行われないこと、カレンダー同期が行われないこと、そして event_id が null のままになることです。

予約の取得

GET /appointments/{appointmentId}

IDを指定して単一の予約を取得します。これにはカレンダーの同期状態も含まれます。

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"])

レスポンス (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
  }
}

予約の一覧表示

GET /appointments

アカウントの予約を新しい順に一覧表示します。カーソルベースのページネーションを使用します。

クエリパラメータ	必須	説明
`contact_id`	いいえ	指定した連絡先の予約のみを返します。連絡先でフィルタリングされた一覧には確定済みの予約のみが含まれます。
`date`	いいえ	指定したカレンダーの日付（`YYYY-MM-DD`）の予約のみを返します。`contact_id`が必要です。
`status`	いいえ	`Confirmed`または`Canceled`でフィルタリングします。`contact_id`を指定していない場合のみ利用可能です。
`limit`	いいえ	1から100までの整数でページサイズを指定します。デフォルトは`50`です。
`cursor`	いいえ	前回のレスポンスから取得した`next_cursor`の値です。

留意すべきいくつかのルール:

フィルタなしの場合、アカウント上のすべての予約をページごとに取得します。
連絡先別 — contact_idを設定すると、特定の連絡先の確定済み予約を表示できます。dateも併せて渡すことで、特定の日付に絞り込むことも可能です。
ステータス別 — statusを設定（contact_idは指定しない）すると、アカウント全体でConfirmedまたはCanceledの予約のみを一覧表示できます。
contact_idなしでのdateフィルタ、またはstatus=Canceledとcontact_idを組み合わせた場合は、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"])

レスポンス (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
}

結果をページ送りするには、あるレスポンスのnext_cursorを次のリクエストのcursorとして渡します。next_cursorがnullになるまで繰り返します。共通のページネーションパターンについてはエラーとページネーションを参照してください。

予約の更新

PUT /appointments/{appointmentId}

予約の日時変更や詳細の変更を行います。変更したいフィールドのみを送信してください（少なくとも1つは必須です）。開始時刻と終了時刻を組み合わせた場合、時系列順である必要があります（end_timeはstart_timeより後である必要があります）。変更内容はリンクされたカレンダーイベントに自動的に同期されます。

イベントタイプの確定済み予約（新規の start_time または room_name）の移動は、新規予約と同様に競合チェックが行われます。すでに埋まっているスロットへの移動は 409 となり何も変更されません。また、イベントタイプの会議室のいずれにも一致しない room_name を指定すると 400 となります。start_time のみを送信すれば、予約の長さは維持されます。ここでは独自の営業時間や通知期間は適用されないため、空いている時間であればいつでも予約を移動できます。

フィールド	説明
`start_time`	新しい開始日時（ISO 8601形式）。予約時と同様に、タイムゾーンオフセットなしで送信された時間はイベントタイプ（またはアカウント）のタイムゾーンで読み取られます。
`end_time`	新しい終了日時（ISO 8601形式）。同様に読み取られます。開始時間より後である必要があります。
`room_name`	新しい部屋またはリソース名。
`description`	新しい説明。クリアする場合は `null` を指定。
`summary`	新しい概要。クリアする場合は `null` を指定。
`external_reference`	新しい参照ID（最大255文字）。クリアする場合は `null` を指定。他の予約で既に使用されている参照IDは、`409` と `"code": "external_reference_taken"` により拒否されます。

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"])

レスポンス (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
  }
}

予約のキャンセル

POST /appointments/{appointmentId}/cancel

確定済みの予約をキャンセルします（オプションで理由を記録可能）。予約はステータス Canceled としてアカウント内に保持され、リンクされているカレンダーイベントはバックグラウンドで自動的に削除されます。すでにキャンセル済みの予約をキャンセルしようとすると、400 が返されます。

フィールド	必須	説明
`cancellation_reason`	いいえ	キャンセルの理由。予約情報に保存されます。

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"])

レスポンス (200 OK):

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

予約確認メールの再送

POST /appointments/{appointmentId}/resend-confirmation

連絡先に予約確認メールを再送します。確認メールが届かない、または迷惑メールフォルダに入ってしまったといった場合に利用します。確認メール（予約時に連絡先へ送信されたものと同じメール）と、予定がGoogleカレンダーにある場合はGoogleカレンダーの招待状の2つが送信されます（どちらかをオフにしない限り両方送信されます）。いずれも連絡先のメールアドレス宛に送信されます。

フィールド	必須	説明
`email`	いいえ	`false`は確認メールをスキップします。デフォルトは`true`です。
`calendar_invite`	いいえ	`false`はGoogleカレンダーの招待状をスキップします。デフォルトは`true`です。

各パートにはそれぞれ結果が返されます：sent、not_requested、no_contact_email、turned_off_for_event_type（イベントタイプの**「連絡先に予約メールを送信」**スイッチがオフの場合）、not_on_google_calendar、imported（カレンダーからインポートされた予約には確認メールは送信されません）、またはfailed。

200：少なくとも1つのパートが送信された場合。recipientは送信先のアドレスです。
409：予約がキャンセルされている、すでに終了している、またはZenchef、Formitable、OpenTable、TheFork、Trafft経由で予約された場合（これらのシステムは独自の確認メールを送信します）。codeはappointment_canceled、appointment_in_past、またはmanaged_by_providerです。
422：何も送信できなかった場合。理由は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())

レスポンス (200 OK):

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

予約の削除

DELETE /appointments/{appointmentId}

予約とその参照情報を完全に削除します。記録を残したまま予約を取り消したい場合は、代わりにキャンセルを使用してください。

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"])

レスポンス (200 OK):

{
  "success": true
}

接続済みGoogleカレンダーの一覧表示

GET /appointments/google-calendars

このアカウントで利用可能なGoogleカレンダーをGoogleから直接返します。これは、アカウント所有者にインポート元のカレンダーを選択させるピッカーを表示する場合や、接続が有効であることを確認する場合に便利です。

これは、アカウントが（設定 → 連携）からGoogleカレンダーに接続し、少なくとも読み取り権限が付与されている場合にのみ機能します。接続されていない場合、または付与された権限にカレンダーの読み取りスコープが含まれなくなった場合は、接続（または再接続）を促す400が返されます。

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"])

レスポンス (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"
    }
  ]
}

各エントリはGoogle独自のCalendarListEntry形式であるため、フィールド名は本APIの一般的なsnake_caseではなく、GoogleのcamelCaseに従います。これはGoogleのデータをそのまま渡しているものであり、当社のデータではありません。接続が欠落しているか取り消されている場合は、Googleカレンダーの接続（または再接続）が必要であることを説明するエラーとともに400が返されます。

Googleカレンダーからイベントをインポートする

POST /appointments/import-calendar-events

キャンペーンまたはAIエージェントの接続済みGoogleカレンダーに既に存在するイベントを取得し、アポイントメントに変換します。これは、既に予約が入っているカレンダーを初めて接続する場合に便利です。各イベントの抽出処理（誰のための予約かを判断するため）に時間がかかる可能性があるため、インラインでは実行されません。リクエストはバックグラウンドジョブとしてキューに入れられ、ポーリング用のjob_idが返されます。

フィールド	必須	説明
`campaign_id`	どちらか一方	インポート元の接続済みカレンダーを持つキャンペーン。
`agent_id`	どちらか一方	インポート元の接続済みカレンダーを持つAIエージェント。
`identifier`	はい	`"EMAIL"`または`"PHONE_NUMBER"` — 各カレンダーイベントから抽出して、所属する連絡先を照合または作成するために使用する連絡先情報。

campaign_idまたはagent_idのいずれか一方のみを送信してください。両方送信したり、どちらも送信しなかったりすると、400が返されます。送信するIDは、ご自身のアカウントに属している必要があります。そうでない場合は404が返されます。

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"])

レスポンス (202 Accepted):

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

campaign_idとagent_idは送信した値をそのまま返します。もう一方は常にnullとなります。

インポートジョブをポーリングする

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

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

レスポンス (200 OK):

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

`status`	意味
`queued`	まだ処理されていません。ポーリングを続けてください。
`processing`	インポートを実行中です。ポーリングを続けてください。
`completed`	完了しました。`message`に人間が読める形式の短い要約が含まれています。
`failed`	何らかのエラーが発生しました。`error`に理由が記載されています。

存在しない（または別のアカウントに属する）jobIdに対してGETを実行すると、404が返されます。

外部予約連携 (Zenchef / Formitable / OpenTable / TheFork / Trafft)

ZenchefとFormitableは、AIエージェントが実際のテーブルを予約できるレストラン予約システムです。Trafftは予約ビジネス向けのスケジューリングプラットフォームであり、レストランごとではなくアカウントごとに1回接続します。2つのレストランプラットフォームにはそれぞれ、ダイナー（食事客）のためにチャット内でレンダリングされる公開された認証不要の予約ウィジェット（https://api.youraiconnector.com/v1/zenchef-widget/...およびhttps://api.youraiconnector.com/v1/formitable-widget/...）があります。これらのウィジェットルートはブラウザで開くことを目的としたプレーンなHTMLページであり、JSON APIエンドポイントではないため、ここではドキュメント化されていません。以下はアカウント管理エンドポイントであり、レストランIDがアカウント所有者に属していることを確認し、追加、更新、または削除を行うためのものです。

Zenchef

Zenchefレストランの接続は2段階の認証プロセスとなっており、ボットに接続する前に、アカウント所有者が実際にそのレストランを運営していることを証明する必要があります。まずIDが存在するかを確認し（名前は表示されません）、次にレストラン名を本人に入力してもらい、それが一致するかを検証します。

ステップ 1 — レストランIDの存在確認

POST /appointments/zenchef-restaurants/check

フィールド	必須	説明
`restaurant_id`	はい	確認するZenchefレストランID。

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

レスポンス (200 OK):

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

exists: falseは、そのIDを持つZenchefレストランが存在しないことを意味します。これ以上の操作は不要です。レート制限はアカウントごとに5分間で10回までです。これを超えると429が返されます。

ステップ 2 — レストラン名の検証

POST /appointments/zenchef-restaurants/verify-name

フィールド	必須	説明
`restaurant_id`	はい	ステップ1で取得したZenchefレストランID。
`user_input_name`	はい	アカウント所有者が入力した名前。Zenchef上の実際のレストラン名と照合されます（大文字小文字や空白は区別されません）。

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

レスポンス (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は名前が一致しなかったことを意味します。restaurantDetailsは省略されるため、アカウント所有者に再試行を依頼してください。レート制限は5分間で3回までです（これが実際の証明ステップであるため、存在確認よりも厳しくなっています）。Zenchef上で解決できなくなったrestaurant_idは、404を返します。

ステップ 3 — レストランの保存

POST /appointments/zenchef-restaurants

フィールド	必須	説明
`restaurant_id`	はい	1〜64文字。英数字、アンダースコア、ハイフンが使用可能です。
`restaurant_name`	はい	ステップ2で検証済みのレストラン名。

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

レスポンス (201 Created):

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

保存されたZenchefレストランの更新

PUT /appointments/zenchef-restaurants/{restaurantId}

フィールド	必須	説明
`restaurant_name`	いいえ	新しい表示名。
`is_active`	いいえ	レストランを削除せずにボットによる予約を停止するには、`false` を設定します。

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

レスポンス (200 OK): 上記の保存レスポンスと同じ形式。

Zenchefレストランの削除

DELETE /appointments/zenchef-restaurants/{restaurantId}

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

レスポンス (200 OK): { "success": true, "data": { "restaurantId": "12345" } }

アカウントに現在存在しない restaurantId を更新または削除しようとすると、404 が返されます。

Formitable

FormitableはZenchefのような2段階の名前確認を必要としません。レストランIDはすでにビジネスごとにスコープ設定されているため、1回の検証呼び出しで十分です。また、セットアップ中にレストランのウェブサイトURLをキャッシュするために使用される詳細ルックアップ機能もあります。

レストランIDの検証

POST /appointments/formitable-restaurants/verify

フィールド	必須	説明
`restaurant_id`	はい	FormitableのレストランID。
`language`	いいえ	プローブ要求の言語タグ。デフォルトは `"nl"` です。

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

レスポンス (200 OK):

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

Formitableが認識できない restaurant_id は、404 を返します。レート制限は、アカウントごとに5分間で10回までです。

レストラン詳細の取得

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

Formitableからレストランの公開プロフィール（ウェブサイトを含む）を取得します。これは、レストランのセットアップ中にウェブサイトURLをキャッシュするために使用されます。language はオプションのクエリパラメータで、デフォルトは "en" です。

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

レスポンス (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"
  }
}

レストランを保存する

POST /appointments/formitable-restaurants

フィールド	必須	説明
`restaurant_id`	はい	1〜64文字。英数字、アンダースコア、ハイフンが使用可能です。
`restaurant_name`	はい	表示名。
`language`	はい	ISO言語タグ（例: `"en"` や `"en-GB"`）。
`website_url`	いいえ	上記の詳細検索で取得したレストランのウェブサイト。 `http(s)://` である必要があります。

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

レスポンス (201 Created): { "success": true, "data": { "restaurantId": "the-blue-door" } }

保存済みのFormitableレストランを更新する

PUT /appointments/formitable-restaurants/{restaurantId}

フィールド	必須	説明
`restaurant_name`	いいえ	新しい表示名。
`language`	いいえ	新しいISO言語タグ。
`is_active`	いいえ	`false` を設定すると、レストランを削除せずにボットによる予約を停止できます。
`website_url`	いいえ	新しいウェブサイトURL。

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

レスポンス (200 OK): 上記の保存レスポンスと同じ形式。

Formitableレストランを削除する

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"

レスポンス (200 OK): { "success": true, "data": { "restaurantId": "the-blue-door" } }

アカウントに現在存在しない restaurantId を更新または削除しようとすると、404 が返されます。

OpenTable

OpenTableのレストランには、プラットフォームのOpenTableパートナー資格情報を通じてアクセスします。OpenTableでは、OpenTableの「Integrations Marketplace」内でプラットフォームのリスティングを接続したレストランのみが、これらの資格情報から参照可能になります。そのため、Formitableと同様に、1回の検証呼び出しで十分です。到達可能なレストランID（数値の「RID」）は、レストランが存在することと、統合が接続されていることの両方を証明します。OpenTableのパートナーリスティングがプラットフォーム上で有効になるまで、検証呼び出しは 503 を返します。

OpenTableレストランの検証

POST /appointments/opentable-restaurants/verify

フィールド	必須	説明
`restaurant_id`	はい	OpenTableレストランID（RID）。`1038007`のような数値です。

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

レスポンス (200 OK):

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

verified: false は、そのIDを持つOpenTableレストランが存在しないことを意味します。403 は、レストランは存在するものの、まだOpenTable内でプラットフォームの統合を接続していないことを意味します。アカウントごとに5分あたり10回までの試行にレート制限されています。

OpenTableレストランの追加

POST /appointments/opentable-restaurants

フィールド	必須	説明
`restaurant_id`	はい	検証済みのレストランID。
`restaurant_name`	はい	表示名（ラベル。AIがそのレストランを呼ぶ際の名前でもあります）。
`website_url`	いいえ	AIがゲストをレストランに引き継ぐ際に表示されるhttp(s) URL。

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

レスポンス (201 Created): { "success": true, "data": { "restaurantId": "1038007" } }

保存済みOpenTableレストランの更新

PUT /appointments/opentable-restaurants/{restaurantId}

restaurant_name、is_active（falseで一時停止）、またはwebsite_url（空文字でクリア）のいずれかを送信します。省略されたフィールドは変更されません。

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

レスポンス (200 OK): { "success": true, "data": { "restaurantId": "1038007" } }

OpenTableレストランを削除する

DELETE /appointments/opentable-restaurants/{restaurantId}

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

レスポンス (200 OK): { "success": true, "data": { "restaurantId": "1038007" } }

現在アカウントに存在しない restaurantId を更新しようとすると、404 が返されます。

TheFork

TheForkのレストランには、プラットフォームのTheForkパートナー資格情報を通じてアクセスします。TheForkでは、その資格情報を持つユーザーは、TheForkアカウントでプラットフォームのパートナー機能が有効になっているレストランのみを参照できます。そのため、FormitableやOpenTableと同様に、1回の検証呼び出しで十分です。到達可能なレストランIDは、レストランが存在することと、そのレストランでパートナー機能が有効になっていることの両方を証明します。IDは、TheForkがTheFork Managerでレストランに割り当てるUUIDであり、文字列として送信されます。TheForkがプラットフォームをパートナーとして承認し、資格情報を発行するまで、検証呼び出しは 503 を返します。現在の状況については TheFork を参照してください。

TheForkレストランの検証

POST /appointments/thefork-restaurants/verify

フィールド	必須	説明
`restaurant_id`	はい	TheForkレストランID（`9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60`のようなUUID）。

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

レスポンス (200 OK):

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

partySizes は、そのレストランが今後30日間にオンラインで受け付ける人数です。404 または 403 は、TheForkがそのIDを持つレストランを提供しなかったことを意味します（IDが間違っているか、そのレストランでプラットフォームのパートナー機能がまだ有効になっていないかのいずれかです）。400 は、IDがUUIDではないことを意味します。レート制限は、アカウントごとに5分間あたり10回までです。

TheForkレストランの追加

POST /appointments/thefork-restaurants

フィールド	必須	説明
`restaurant_id`	はい	検証済みのレストランID（UUID）。
`restaurant_name`	はい	表示名（ラベル。AIがレストランを呼ぶ際の名前でもあります）。
`website_url`	いいえ	AIがゲストをレストランに引き継ぐ際に表示されるhttp(s) URL。

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

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

保存されたTheForkレストランの更新

PUT /appointments/thefork-restaurants/{restaurantId}

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

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

TheForkのレストランを削除する

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"

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

アカウントに現在存在しない restaurantId を更新または削除しようとすると、404 が返されます。

Trafft

Trafftは場所ごとではなく、アカウント全体に対して1回接続します。会社のアドレスと、Trafft管理パネル（Features & Integrations → API & Connectors、Trafftのビジネスプランの一部）から取得したAPI認証情報が必要です。接続呼び出しは、何かを保存する前にTrafftに対してそれらの認証情報をチェックするため、アドレスや認証情報が間違っている場合、あるいはAPIアクセス権のないプランである場合は、顧客との会話中ではなくこの時点で失敗します。クライアントシークレットは暗号化されて保存され、どのエンドポイントからも返されることはありません。

3つの書き込み呼び出し（POST、PUT、DELETE）はすべて、Integrationsの編集権限を必要とします。ステータスGETにはIntegrationsの表示権限が必要です。

Trafftを接続する

POST /appointments/trafft/connect

フィールド	必須	説明
`subdomain`	はい	会社のアドレス。サインイン時のURLの`.admin.trafft.com`より前の部分（例: `acme`）。完全なアドレスも受け付けられ、同じ値に短縮されます。
`client_id`	はい	TrafftのAPI & Connectorsページから取得したクライアントID。
`client_secret`	はい	同じページから取得したクライアントシークレット。暗号化して保存され、返されることはありません。
`company_name`	いいえ	自身のリスト用のラベル。

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

レスポンス (200 OK):

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

カウント数はチェック中にTrafftから返されます。これは、認証情報が意図したアカウントを指していることを確認する最も迅速な方法です。

接続ステータスを取得する

GET /appointments/trafft

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

レスポンス (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は、まだ何も設定されていないことを意味します。クライアントシークレットはこのレスポンスに含まれることはありません。

接続を更新する

PUT /appointments/trafft

フィールド	必須	説明
`is_active`	いいえ	`false` を設定して一時停止します。AIはTrafftへの予約を停止しますが、接続は維持されます。`true` で再開します。
`company_name`	いいえ	新しいラベル。

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

レスポンス (200 OK): 上記の GET と同じ接続オブジェクトです。

Trafftの接続解除

DELETE /appointments/trafft

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

レスポンス (200 OK): { "success": true }

接続を解除すると、保存された認証情報のみが削除されます。Trafftにすでにある予約には影響しません。

Zenchef/Formitable/OpenTable/TheForkの全エンドポイントにおけるエラー形式: このページの他の箇所とは異なり、ここでのエラーはステータスを2回（HTTPステータスとして1回、ボディ内の error_code として1回）伝えます。例: { "success": false, "error": "Restaurant not found", "error_code": 404 }。他のエラーと同様に処理してください。success を確認し、error を読み取ってメッセージを取得します。

Appointments API エラー

Appointment エンドポイントは、標準的なエラーエンベロープを返します。

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

ステータス	予約エンドポイントで発生する場合
`400`	必須フィールドの欠落または無効（例：不正な `start_time`、`start_time` より後ではない `end_time`、無効なフィルターの組み合わせ、更新するフィールドがない、既にキャンセル済みの予約など）。予約時：`event_id` と `title` の両方が未送信、両方が同時に送信された、`end_time` と `duration_minutes` の両方が送信された、200文字を超える `title`、または1〜1440の範囲外の `duration_minutes` が指定された場合。
`404`	予約、連絡先、またはイベントタイプが見つかりませんでした。
`409`	要求された時間枠が既に埋まっている（予約の競合）、または更新時に `external_reference` が他の予約で既に使用されている場合。

すべてのエンドポイントが返す共通コード（401、403（プランにAPIアクセスが含まれていない）、429（レート制限）、500）については、再試行のガイダンスと共にエラーとページネーションに記載されています。

次のステップ

連絡先 — 予約対象の連絡先を作成および検索します。
メッセージと会話 — 連絡先に確認やリマインダーを送信します。
Webhook — 予約が変更されたときに通知を受け取ります。

予約 #

予約オブジェクト #

空き枠の検索 #

予約の登録 #

他の場所で行われた予約の記録 #

予約の取得 #

予約の一覧表示 #

予約の更新 #

予約のキャンセル #

予約確認メールの再送 #

予約の削除 #

接続済みGoogleカレンダーの一覧表示 #

Googleカレンダーからイベントをインポートする #

インポートジョブをポーリングする #

外部予約連携 (Zenchef / Formitable / OpenTable / TheFork / Trafft) #

Zenchef #

Formitable #

OpenTable #

TheFork #

Trafft #

Appointments API エラー #

次のステップ #

予約

予約オブジェクト

空き枠の検索

予約の登録

他の場所で行われた予約の記録

予約の取得

予約の一覧表示

予約の更新

予約のキャンセル

予約確認メールの再送

予約の削除

接続済みGoogleカレンダーの一覧表示

Googleカレンダーからイベントをインポートする

インポートジョブをポーリングする

外部予約連携 (Zenchef / Formitable / OpenTable / TheFork / Trafft)

Zenchef

Formitable

OpenTable

TheFork

Trafft

Appointments API エラー

次のステップ