Contents
Jicoo API キー取得と認証設定
Jicoo の REST API を本番環境で利用するには、まず管理画面から API キー を発行し、リクエストヘッダーに正しく組み込む必要があります。本セクションではキーの取得手順と、一般的な認証方式について解説します。これらを抑えておくことで、後続のエンドポイント呼び出しがスムーズになります。
API キーの作成手順
管理画面左メニューの Settings > Integrations から API キーを生成できます。以下は実際の操作フローです。
- API タブ を選択し、Create API Key ボタンをクリック
- キーに分かりやすい名称（例：
my-service-prod）と利用目的を入力して Generate - 発行されたキーが画面に表示されるので、必ずコピー し安全な場所に保管
重要 : キーは生成時に一度だけ表示されます。紛失した場合は同手順で新規作成し、旧キーを無効化してください。
詳細は Jicoo の公式開発者ポータル（例：https://developer.jicoo.com/articles/api-key) を参照してください。
認証ヘッダーの組み込み方
Jicoo API は Bearer トークン方式 で認証します。リクエストに以下のヘッダーを付与するだけです。
|
1 2 |
Authorization: Bearer <YOUR_API_KEY> |
言語別サンプルコード
| 言語 | サンプル概要 |
|---|---|
| cURL | curl -X GET "https://api.jicoo.com/v1/reservations" -H "Authorization: Bearer YOUR_API_KEY" |
| Python (requests) | python\nimport requests\nheaders = {"Authorization": "Bearer YOUR_API_KEY"}\nresp = requests.get("https://api.jicoo.com/v1/reservations", headers=headers)\nprint(resp.json()) |
| Node.js (axios) | javascript\nconst axios = require('axios');\naxios.get('https://api.jicoo.com/v1/reservations', {headers: {'Authorization': 'Bearer YOUR_API_KEY'}})\n .then(r => console.log(r.data))\n .catch(e => console.error(e)); |
ノーコードツールでの設定例
- Make.com、Power Automate の HTTP モジュールでは「ヘッダー」欄に
AuthorizationとBearer <API_KEY>を入力するだけです。 - Zapier の Webhooks by Zapier でも同様にカスタムヘッダーを設定できます。
主要エンドポイントとサンプルリクエスト
Jicoo が提供する予約操作は「作成」「取得」「更新」「削除」の4種です。ここでは各エンドポイントの概要、必須パラメータ、実装例を示します。公式ドキュメントで最新の URL やパラメータ一覧をご確認ください。
予約作成（POST /v1/reservations）
予約作成は POST メソッドで JSON ボディを送信するだけで完了します。必要最低限の情報さえ揃えていれば、サーバ側で空き枠チェックと確定処理が自動的に行われます。
必要パラメータ
| フィールド | 型 | 説明 |
|---|---|---|
service_id |
string | 予約対象サービスの識別子 |
start_time |
ISO8601 | 予約開始日時（例：2026-07-01T10:00:00+09:00） |
duration_minutes |
integer | 予約時間（分単位） |
customer_name |
string | 顧客氏名 |
customer_email |
string | メールアドレス |
metadata (任意) |
object | 任意の追加情報 |
実装例
- cURL
bash
curl -X POST "https://api.jicoo.com/v1/reservations" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"service_id": "svc_12345",
"start_time": "2026-07-01T10:00:00+09:00",
"duration_minutes": 60,
"customer_name": "山田太郎",
"customer_email": "taro.yamada@example.com"
}'
- Python (requests)
python
import requests, json
url = "https://api.jicoo.com/v1/reservations"
payload = {
"service_id": "svc_12345",
"start_time": "2026-07-01T10:00:00+09:00",
"duration_minutes": 60,
"customer_name": "山田太郎",
"customer_email": "taro.yamada@example.com"
}
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_KEY"
}
resp = requests.post(url, headers=headers, data=json.dumps(payload))
print(resp.status_code, resp.json())
- Node.js (axios)
javascript
const axios = require('axios');
axios.post(
'https://api.jicoo.com/v1/reservations',
{
service_id: 'svc_12345',
start_time: '2026-07-01T10:00:00+09:00',
duration_minutes: 60,
customer_name: '山田太郎',
customer_email: 'taro.yamada@example.com'
},
{
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
}
}
)
.then(r => console.log('Created:', r.status, r.data))
.catch(e => console.error('Error:', e.response?.status, e.message));
成功レスポンス（例）
|
1 2 3 4 5 6 7 |
{ "id": "resv_987654321", "service_id": "svc_12345", "start_time": "2026-07-01T10:00:00+09:00", "status": "confirmed" } |
予約取得・更新・削除（GET / PUT / DELETE）
個別予約は ID を URL に埋め込んで HTTP メソッドを切り替えるだけで管理できます。REST の設計に従っているため、既存フレームワークやノーコードツールと相性が良いです。
| 操作 | メソッド | エンドポイント例 |
|---|---|---|
| 取得 | GET | https://api.jicoo.com/v1/reservations/{reservation_id} |
| 更新 | PUT | https://api.jicoo.com/v1/reservations/{reservation_id} |
| 削除 | DELETE | https://api.jicoo.com/v1/reservations/{reservation_id} |
取得（GET）サンプル（cURL）
|
1 2 3 |
curl -X GET "https://api.jicoo.com/v1/reservations/resv_987654321" \ -H "Authorization: Bearer YOUR_API_KEY" |
更新（PUT）サンプル（Python）
|
1 2 3 4 5 6 7 8 |
payload = {"customer_name": "山田花子", "status": "rescheduled"} resp = requests.put( "https://api.jicoo.com/v1/reservations/resv_987654321", headers={"Authorization": "Bearer YOUR_API_KEY"}, json=payload ) print(resp.status_code, resp.json()) |
削除（DELETE）サンプル（Node.js）
|
1 2 3 4 5 6 |
axios.delete('https://api.jicoo.com/v1/reservations/resv_987654321', { headers: { Authorization: 'Bearer YOUR_API_KEY' } }) .then(r => console.log('Deleted:', r.status)) .catch(e => console.error('Error:', e.response?.status)); |
ノーコードでの呼び出し例
- Make.com の HTTP モジュールに「GET」や「PUT」を選択し、URL に予約 ID を差し込んだうえで
Authorization: Bearer {{api_key}}ヘッダーを設定すれば完了です。 - n8n でも同様のリクエストノードが利用でき、取得した JSON データは後続の「Function」や「Spreadsheet」ノードへ簡単に流せます。
Webhook の登録と受信サーバ実装
予約完了・キャンセルなどリアルタイム通知を外部システムで処理したい場合、Jicoo が提供する Webhook 機能を利用します。本節では管理画面からの設定手順と、代表的な受信エンドポイント実装例（Node.js・Python）をご紹介します。
Webhook 登録手順
管理画面の Settings > Webhooks から数クリックで通知先 URL を登録できます。公式ドキュメントでは「シークレットキー」も自動生成でき、署名検証が可能です（詳細は https://developer.jicoo.com/webhook) をご確認ください）。
- Settings > Webhooks を開く
- 「新規登録」ボタンをクリックし、対象イベント（例：
reservation.created,reservation.canceled）を選択 - 通知先 URL とシークレット（任意だが推奨）を入力して保存
- 保存後に表示される テスト送信 ボタンでペイロード受信の動作確認が可能
署名ヘッダーについて
Jicoo は HMAC‑SHA256 方式でリクエストボディに対する署名を付与します。公式ドキュメントではヘッダー名は X-Jicoo-Signature と記載されていますが、実装前に最新版をご確認ください。
Node.js（Express）による受信ハンドラ例
以下のコードは署名検証と基本的なエラーハンドリングを組み込んだ最小構成です。環境変数 JICOODEV_WEBHOOK_SECRET にシークレットキーを設定して利用します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
const express = require('express'); const crypto = require('crypto'); const app = express(); app.use(express.json()); const WEBHOOK_SECRET = process.env.JICOODEV_WEBHOOK_SECRET; /* 署名検証ロジック */ function verifySignature(req) { const signatureHeader = req.headers['x-jicoo-signature']; if (!signatureHeader) return false; const payload = JSON.stringify(req.body); const expected = crypto .createHmac('sha256', WEBHOOK_SECRET) .update(payload) .digest('hex'); // timingSafeEqual による安全比較 return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected)); } /* Webhook エンドポイント */ app.post('/webhook/jicoo', (req, res) => { if (!verifySignature(req)) { return res.status(401).send('Invalid signature'); } // 必要な処理例：ログ出力、DB 保存、キュー投入など console.log('Received event:', req.body.event_type); res.sendStatus(200); }); app.listen(3000, () => console.log('Webhook server listening on port 3000')); |
Python（Flask）による受信ハンドラ例
Flask 版も同様に HMAC‑SHA256 検証を行います。シークレットは環境変数 JICOODEV_WEBHOOK_SECRET に格納してください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
import os, hmac, hashlib from flask import Flask, request, abort app = Flask(__name__) SECRET = os.getenv('JICOODEV_WEBHOOK_SECRET') def verify_signature(payload: bytes, signature: str) -> bool: mac = hmac.new(SECRET.encode(), payload, hashlib.sha256).hexdigest() return hmac.compare_digest(mac, signature) @app.route('/webhook/jicoo', methods=['POST']) def webhook(): sig = request.headers.get('X-Jicoo-Signature') if not sig or not verify_signature(request.data, sig): abort(401) # 署名不正 data = request.json print('Event:', data.get('event_type')) # 例: ログ出力や DB 登録 return '', 200 if __name__ == '__main__': app.run(port=5000) |
ノーコードツールでの受信設定
- Zapier の Webhooks by Zapier トリガーは、カスタムコードステップで上記と同等の HMAC 検証が可能です。
- n8n でも「Webhook」ノードにシークレット入力項目があり、受信後自動的に署名検証を行うオプションがあります。
埋め込み予約画面と API の併用活用例
Jicoo が提供する埋め込みウィジェットは UI をすぐに構築できる一方、内部ロジックや集計は API 経由で行うことが推奨されています。ここでは iframe 埋め込み手順と、予約データをリアルタイムで社内システムに連携させるフローを示します。
iframe 埋め込みの基本手順
埋め込みはシンプルな <iframe> タグだけで完了し、CSS でレスポンシブ対応が可能です。公式ドキュメント（https://developer.jicoo.com/widget) に記載されたパラメータを活用するとデザインや言語設定も柔軟に変更できます。
|
1 2 3 4 5 6 7 |
<div style="position:relative;width:100%;padding-top:75%;"> <iframe src="https://booking.jicoo.com/widget?service_id=svc_12345&theme=light&locale=ja" style="position:absolute;top:0;left:0;width:100%;height:100%;border:none;" title="Jicoo予約ウィジェット"> </iframe> </div> |
| パラメータ | 説明 |
|---|---|
service_id |
表示したいサービスを限定 |
theme |
light / dark の外観切替 |
locale |
言語設定（例：ja, en） |
hide_header |
ヘッダー非表示でデザイン調整 |
API と組み合わせたリアルタイム集計フロー
Webhook だけではイベントの概要しか取得できません。予約詳細や顧客属性は GET /v1/reservations/{id} で取得し、社内 DB や BI ツールに格納すると情報が完全です。
フローステップ（図示）
reservation.createdWebhook が自社エンドポイントへ届く- エンドポイントは受信データから
reservation_idを抽出し、API で詳細取得 - 必要項目（日時・顧客名・サービス種別）を DB に保存または BI ツールに送信
- ダッシュボードが自動的に更新され、経営判断に即活用できる
Python 実装例（Webhook ハンドラ内）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
import os, requests API_KEY = os.getenv('JICOODEV_API_KEY') BASE_URL = "https://api.jicoo.com/v1" def fetch_reservation(resv_id: str) -> dict: url = f"{BASE_URL}/reservations/{resv_id}" headers = {"Authorization": f"Bearer {API_KEY}"} r = requests.get(url, headers=headers) r.raise_for_status() return r.json() # Webhook ハンドラの一部として呼び出す例 def handle_created(event: dict): resv_id = event['data']['reservation_id'] details = fetch_reservation(resv_id) # ここで DB 保存や BI API 呼び出しを実装 print('予約詳細:', details) |
ノーコードでの自動集計例
- Make.com のシナリオ
Webhook→HTTP GET (Jicoo API)→Google Sheets に行追加といった流れをドラッグ＆ドロップだけで構築可能です。 - Power Automate でも「When a HTTP request is received」→「HTTP（GET）」→「Add a row to Excel」などのテンプレートが用意されています。
ベストプラクティスと実装事例
API を本番環境で安定運用するために、エラーハンドリング・レートリミット対策・セキュリティ管理を徹底しましょう。以下では具体的な指針と、実際の活用事例を交えて解説します。
エラーハンドリングとステータスコード別対処法
| ステータス | 意味 | 推奨対策 |
|---|---|---|
| 200 / 201 | 正常レスポンス（作成は 201） | 正常データをそのまま利用 |
| 400 | リクエストパラメータ不正 | 入力バリデーションを事前に実装 |
| 401 | 認証失敗 | API キーとヘッダー形式を再確認 |
| 404 | リソース未発見 | ID が正しいか、削除済みでないかチェック |
| 429 | レートリミット超過 | Retry-After ヘッダーの秒数待機し指数バックオフで再送 |
| 5xx 系 | サーバ側エラー | 最大 3 回までリトライし、障害通知を行う |
レートリミットに関する注意点
公式情報（2024 年版）では 1 分あたり最大 60 リクエスト が上限とされていますが、プランや利用状況により変動する可能性があります。実装時はレスポンスヘッダー X-RateLimit-Limit・X-RateLimit-Remaining を参照し、キューイングライブラリ（例：Bull、Sidekiq）でスロットリングを行うと安全です。
API キーの安全な管理方法
- 環境変数 に格納し、コードベースに直接記述しない
- CI/CD では GitHub Secrets や GitLab CI のシークレットストアを利用
- 管理画面で IP ホワイトリスト を設定できる場合は必ず有効化（公式ドキュメント参照）
- 定期的にキーをローテーションし、旧キーは速やかに無効化
実装事例：Google カレンダー連携 & CRM 同期
| 目的 | 構成概要 | 成果 |
|---|---|---|
| Google カレンダー自動登録 | Webhook → Jicoo API で予約詳細取得 → Google Calendar API (events.insert) に送信 |
会議室二重予約が約 30% 減少（導入企業 A 社） |
| CRM データベース同期 | Node.js サーバで Webhook を受信 → MySQL の reservations テーブルへ INSERT/UPDATE |
データ不整合率 < 0.1% に抑制、営業チームのリード管理がリアルタイム化 |
これらは Jicoo が公式サイトで紹介している活用例（https://developer.jicoo.com/use-cases) を元に作成したサンプルです。
まとめ
- API キー取得 は Settings > Integrations から簡単に行え、
Authorization: Bearer <key>ヘッダーで認証します。 - 主要エンドポイント（予約の作成・取得・更新・削除）は RESTful に設計されており、cURL／Python／Node.js のサンプルを参考にすぐ実装可能です。
- Webhook は管理画面から数クリックで登録でき、
X-Jicoo-Signatureを用いた HMAC‑SHA256 署名検証が推奨されています。 - 埋め込みウィジェット と API の併用により、ユーザー向け UI はそのままで社内集計・分析を自動化できます。
- ベストプラクティス（エラーハンドリング、レートリミット対策、キー管理）を遵守すれば、安定した運用とセキュアな連携が実現します。
上記手順とサンプルコードを活用し、Jicoo API を自社サービスへシームレスに統合してください。公式ドキュメントの最新情報は常に確認し、必要に応じて設定や実装を見直すことが成功への鍵です。