API連携

API リファレンス · 標準コネクタ

Cliptalk が業種ごとに用意する標準コネクタの仕様です。標準コネクタを読み込んで接続したあと、操作・パス・パラメータを自社サービスに合わせて自由にカスタマイズできます。

#標準コネクタとは

業種ごとに、AI ボットがよく使う操作（本人確認、照会、キャンセル・変更）をあらかじめ定義した API 仕様です。ベースアドレスは、プロジェクトに登録した自社ドメインから https://www.mydomain.com/api/shop や https://www.mydomain.com/api/fitness の形で自動的に入ります。

1
自社ドメインを登録
プロジェクトを作るとき、自社ドメイン（例: www.mydomain.com）を入力します。あとからプロジェクトの一般タブで変更できます。
2
標準コネクタを読み込む
プロジェクト → AI ボット → API 仕様を作成 → はじめ方で、業種に合う標準コネクタを選びます。Base URL が自社ドメインを基準に埋まります。
3
API を実装するか、既存の API に合わせる
自社サーバーに、下の仕様と同じパスと応答で API を作れば、そのまま動きます。すでに API がある場合は、次のステップで仕様をその API に合わせます。
4
カスタマイズ
不要な操作はオフにするか削除し、新しい操作を追加し、パス・パラメータ名・説明・認証方式を自社 API に合わせて直します。説明は AI がツールを選ぶ基準なので、自社の言葉に整えるとよいです。
5
シークレット・テスト・接続
シークレットタブで API キーを保存し、API テストタブで呼び出してから、保存して AI ボットに接続を押します。

API を作る前に流れを見たいときは、AI ボット設定のサンプルコネクタに接続してみてください。サンプルコネクタは同じ仕様の Cliptalk デモ API を呼ぶので、先にウィジェットで流れを試せます。

# ショップ
https://www.mydomain.com/api/shop

# 配送代行・購入代行
https://www.mydomain.com/api/forwarding

# 旅行会社
https://www.mydomain.com/api/travel

# 病院・美容室の予約
https://www.mydomain.com/api/clinic

# サブスクリプション（SaaS）
https://www.mydomain.com/api/subscription

# 教育・スクール
https://www.mydomain.com/api/academy

# ホテル・ペンション
https://www.mydomain.com/api/stay

# ジム・ピラティス
https://www.mydomain.com/api/fitness

#共通ルール

項目	説明
`認証`	既定は `Authorization: Bearer` にキーを付けたものです。スタジオの基本設定で、API キーヘッダー・Basic・クエリパラメータに変えられます。
`形式`	リクエストも応答も JSON です。成功応答は ok: true とデータを一緒に返します。
`エラー`	2xx 以外のステータスと `{ "ok": false, "error", "message" }`。message は、AI がお客様へ状況を説明するときの根拠になります。
`本人確認`	`POST /verify` が `customer.id` を返すと、以降のパスの `{customer_id}` は Cliptalk が自動で埋めます。お客様が他人の ID を入れることはできません。
`処理`	キャンセルや変更のようにデータを変える操作は、まず `dry_run: true` で呼んでプレビュー（`summary` の文字列配列）を受け取ります。お客様が同意したら、`dry_run` なしでもう一度呼びます。
`所有権の確認`	顧客情報を扱う API は、サーバー側でもその customer_id のデータかどうか必ず確認してください。

{
  "ok": true,
  "customer": { "id": "cus_1001", "name": "クリップ" }
}

#ショップ標準コネクタ

注文番号で本人確認 → 注文一覧・詳細 → 配送照会 → 発送前の注文キャンセル、商品の在庫・価格検索。ベースアドレスは https://www.mydomain.com/api/shop です。

操作	リクエスト	説明 · 主なパラメータ
`verify_customer`	POST `/verify`	本人確認 `order_no, phone_last4`
`list_orders`	GET `/customers/{customer_id}/orders`	注文一覧 `status`
`get_order`	GET `/customers/{customer_id}/orders/{order_no}`	注文詳細・配送照会 `order_no*`
`cancel_order`	POST `/customers/{customer_id}/orders/{order_no}/cancel`	注文キャンセル（プレビュー → 確定） `order_no*, reason`
`search_products`	GET `/products`	商品検索 `q*`

curl -X POST https://www.mydomain.com/api/shop/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"order_no":"DM-10001","phone_last4":"1234"}'

#ショップ · 本人確認

POST/verify

注文番号と電話番号の下 4 桁でお客様を確認します。応答の customer.id が、以降の操作の {customer_id} になります。

Body	型	説明
`order_no *`	string	注文番号
`phone_last4 *`	string	電話番号の下 4 桁

curl -X POST https://www.mydomain.com/api/shop/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"order_no":"DM-10001","phone_last4":"1234"}'

#ショップ · 注文一覧

GET/customers/{customer_id}/orders

お客様の注文一覧です。

パラメータ	位置	説明
`customer_id *`	path	本人確認で受け取った顧客 ID
`status`	query	paid \| preparing \| shipped \| delivered \| cancelled

curl https://www.mydomain.com/api/shop/customers/cus_1001/orders \
  -H 'Authorization: Bearer YOUR_API_KEY'

#ショップ · 注文詳細

GET/customers/{customer_id}/orders/{order_no}

注文 1 件の商品・金額・配送情報（配送会社、送り状番号、配送照会リンク）です。

curl https://www.mydomain.com/api/shop/customers/cus_1001/orders/DM-10001 \
  -H 'Authorization: Bearer YOUR_API_KEY'

#ショップ · 注文キャンセル

POST/customers/{customer_id}/orders/{order_no}/cancel

決済完了・商品準備中の注文だけキャンセルできます。dry_run: true の場合は返金予定額のプレビューだけを返します。

Body	型	説明
`dry_run`	boolean	プレビューかどうか
`reason`	string	キャンセル理由

curl -X POST https://www.mydomain.com/api/shop/customers/cus_1001/orders/DM-10002/cancel \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"dry_run":true}'

#ショップ · 商品検索

GET/products

パラメータ	位置	説明
`q *`	query	商品名の検索語または SKU

curl 'https://www.mydomain.com/api/shop/products?q=タンブラー' \
  -H 'Authorization: Bearer YOUR_API_KEY'

#配送代行・購入代行標準コネクタ

私書箱番号で本人確認 → 申請一覧・詳細（トラッキング） → 申請のキャンセル、予想送料と海外倉庫の住所案内。ベースアドレスは https://www.mydomain.com/api/forwarding です。

操作	リクエスト	説明 · 主なパラメータ
`verify_customer`	POST `/verify`	本人確認 `member_code, name`
`list_applications`	GET `/customers/{customer_id}/applications`	申請一覧 `status`
`get_application`	GET `/customers/{customer_id}/applications/{application_no}`	申請詳細・トラッキング `application_no*`
`cancel_application`	POST `/customers/{customer_id}/applications/{application_no}/cancel`	申請キャンセル（プレビュー → 確定） `application_no*, reason`
`estimate_shipping`	GET `/rates`	予想送料 `country, weight_kg`
`list_warehouses`	GET `/warehouses`	海外倉庫の住所

curl -X POST https://www.mydomain.com/api/forwarding/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"member_code":"CT1001","name":"配送"}'

#旅行会社標準コネクタ

予約番号で本人確認 → 予約一覧・詳細 → 予約キャンセル、旅行商品の検索とキャンセル規定の案内。ベースアドレスは https://www.mydomain.com/api/travel です。

操作	リクエスト	説明 · 主なパラメータ
`verify_customer`	POST `/verify`	本人確認 `booking_no, name`
`list_bookings`	GET `/customers/{customer_id}/bookings`	予約一覧
`get_booking`	GET `/customers/{customer_id}/bookings/{booking_no}`	予約詳細 `booking_no*`
`cancel_booking`	POST `/customers/{customer_id}/bookings/{booking_no}/cancel`	予約キャンセル（プレビュー → 確定） `booking_no*, reason`
`search_products`	GET `/products`	旅行商品の検索 `city, q`
`get_cancellation_policy`	GET `/cancellation-policy`	キャンセル規定

curl -X POST https://www.mydomain.com/api/travel/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"booking_no":"TR-260001","name":"旅行"}'

#病院・美容室の予約標準コネクタ

施術・診療の案内と空き時間の照会、新規予約。予約番号で本人確認 → 自分の予約の照会 → 予約の変更・キャンセル。ベースアドレスは https://www.mydomain.com/api/clinic です。

操作	リクエスト	説明 · 主なパラメータ
`verify_customer`	POST `/verify`	本人確認 `reservation_no, name`
`list_services`	GET `/services`	施術・診療の案内
`find_slots`	GET `/slots`	空き時間の照会 `date*`
`create_reservation`	POST `/reservations`	新規予約（プレビュー → 確定） `service_code, datetime, name, phone`
`list_reservations`	GET `/customers/{customer_id}/reservations`	自分の予約
`change_reservation`	POST `/customers/{customer_id}/reservations/{reservation_no}/change`	予約変更（プレビュー → 確定） `reservation_no, new_datetime`
`cancel_reservation`	POST `/customers/{customer_id}/reservations/{reservation_no}/cancel`	予約キャンセル（プレビュー → 確定） `reservation_no*`

curl -X POST https://www.mydomain.com/api/clinic/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"reservation_no":"RV-7001","name":"予約"}'

#サブスクリプション（SaaS）標準コネクタ

料金プランの案内。メールとアカウント番号で本人確認 → 契約状態・請求書 → 領収書の再送、プラン変更、解約予約。ベースアドレスは https://www.mydomain.com/api/subscription です。

操作	リクエスト	説明 · 主なパラメータ
`verify_customer`	POST `/verify`	本人確認 `email, account_no`
`list_plans`	GET `/plans`	料金プラン
`get_subscription`	GET `/customers/{customer_id}/subscription`	契約状態
`list_invoices`	GET `/customers/{customer_id}/invoices`	請求書一覧
`resend_invoice`	POST `/customers/{customer_id}/invoices/{invoice_no}/resend`	領収書の再送（プレビュー → 確定） `invoice_no*`
`change_plan`	POST `/customers/{customer_id}/subscription/change-plan`	プラン変更（プレビュー → 確定） `plan*`
`cancel_subscription`	POST `/customers/{customer_id}/subscription/cancel`	解約予約（プレビュー → 確定） `reason`

curl -X POST https://www.mydomain.com/api/subscription/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"email":"sub.kim@example.com","account_no":"AC-5001"}'

#教育・スクール標準コネクタ

コース案内。受講生番号で本人確認 → 受講履歴・詳細（返金見込額） → 返金申請、受講の延期。ベースアドレスは https://www.mydomain.com/api/academy です。

操作	リクエスト	説明 · 主なパラメータ
`verify_customer`	POST `/verify`	本人確認 `student_no, name`
`search_courses`	GET `/courses`	コース案内 `q`
`list_enrollments`	GET `/customers/{customer_id}/enrollments`	受講履歴
`get_enrollment`	GET `/customers/{customer_id}/enrollments/{enrollment_no}`	受講詳細・返金見込額 `enrollment_no*`
`request_refund`	POST `/customers/{customer_id}/enrollments/{enrollment_no}/refund`	返金申請（プレビュー → 確定） `enrollment_no*, reason`
`postpone_enrollment`	POST `/customers/{customer_id}/enrollments/{enrollment_no}/postpone`	受講の延期（プレビュー → 確定） `enrollment_no, weeks`

curl -X POST https://www.mydomain.com/api/academy/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"student_no":"ST-8001","name":"受講"}'

#ホテル・ペンション標準コネクタ

空室・料金と施設案内。予約番号で本人確認 → 予約一覧・詳細 → 追加サービスの依頼、予約キャンセル。ベースアドレスは https://www.mydomain.com/api/stay です。

操作	リクエスト	説明 · 主なパラメータ
`verify_customer`	POST `/verify`	本人確認 `reservation_no, name`
`find_rooms`	GET `/rooms`	空室・料金 `check_in*, nights, guests`
`get_info`	GET `/info`	施設案内
`list_reservations`	GET `/customers/{customer_id}/reservations`	自分の予約一覧
`get_reservation`	GET `/customers/{customer_id}/reservations/{reservation_no}`	予約詳細 `reservation_no*`
`add_request`	POST `/customers/{customer_id}/reservations/{reservation_no}/requests`	追加サービスの依頼（プレビュー → 確定） `reservation_no, type`
`cancel_reservation`	POST `/customers/{customer_id}/reservations/{reservation_no}/cancel`	予約キャンセル（プレビュー → 確定） `reservation_no*`

curl -X POST https://www.mydomain.com/api/stay/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"reservation_no":"HT-9001","name":"宿泊"}'

#ジム・ピラティス標準コネクタ

レッスンスケジュールと残席。会員番号で本人確認 → 利用券・残り回数 → レッスンの予約・キャンセル、会員権の停止。ベースアドレスは https://www.mydomain.com/api/fitness です。

操作	リクエスト	説明 · 主なパラメータ
`verify_customer`	POST `/verify`	本人確認 `member_no, phone_last4`
`list_classes`	GET `/classes`	レッスンスケジュール `date, type`
`get_membership`	GET `/customers/{customer_id}/membership`	利用券の照会
`list_bookings`	GET `/customers/{customer_id}/bookings`	自分のレッスン予約
`book_class`	POST `/customers/{customer_id}/bookings`	レッスン予約（プレビュー → 確定） `class_id*`
`cancel_booking`	POST `/customers/{customer_id}/bookings/{booking_id}/cancel`	レッスン予約のキャンセル（プレビュー → 確定） `booking_id*`
`hold_membership`	POST `/customers/{customer_id}/membership/hold`	会員権の停止（プレビュー → 確定） `start_date, days`

curl -X POST https://www.mydomain.com/api/fitness/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"member_no":"FT-1001","phone_last4":"1234"}'

#標準コネクタとは

#共通ルール

#ショップ 標準コネクタ

#ショップ · 本人確認

#ショップ · 注文一覧

#ショップ · 注文詳細

#ショップ · 注文キャンセル

#ショップ · 商品検索

#配送代行・購入代行 標準コネクタ

#旅行会社 標準コネクタ

#病院・美容室の予約 標準コネクタ

#サブスクリプション（SaaS） 標準コネクタ

#教育・スクール 標準コネクタ

#ホテル・ペンション 標準コネクタ

#ジム・ピラティス 標準コネクタ