AI向け

AI コーディングアシスタントが Crisphive 連携を構築するために必要なものをすべて 1 か所に — そのまま貼り付けられるプロンプト、機械可読リソース、API の要点。

AI でインストールする

連携の土台を作るには、このプロンプトを AI コーディングアシスタントに貼り付けてください。

Read the Crisphive backend integration skill at
https://api.crisphive.com/developers/SKILL.md and the OpenAPI spec at
https://api.crisphive.com/developers/openapi.json.

Then implement a client for my backend that:
1. Authenticates with an API key as a Bearer token (chsk_test_… for sandbox)
2. Creates a customer and a job request
3. Keeps job requests in sync by polling GET /v1/job-requests/changes
   with the next_since cursor

すべてのレスポンスは単一のエンベロープ形式 — { error_code, message, errors, data } — を使用するため、生成されたクライアントは 1 つのレスポンスパーサーを共有できます。

機械可読リソース

どちらのファイルも API 自身が配信するため、常にデプロイ済みバージョンと一致します。ドキュメントページをコンテキストにコピーする代わりに、アシスタントをこれらの URL に直接向けてください。

リソース	内容
`SKILL.md`	エージェント向けに書かれた簡潔な連携ガイド。認証、レスポンスエンベロープ、主要な予約フロー、よくある落とし穴を扱います。
`openapi.json`	完全な OpenAPI 仕様 — すべてのエンドポイント、リクエスト/レスポンスのスキーマ、エラーコード。型付きクライアントの生成に利用できます。

アシスタントに伝えるべき要点

ベース URL は https://api.crisphive.com/v1 です。sandbox と live はパスが共通で、環境はキーのプレフィックス（chsk_test_… と chsk_live_…）で決まります。
すべてのリクエストを Authorization: Bearer <api key> で認証します。キーには有効期限があります — 有効期間は作成時に選択し（デフォルトは 30 日、1 日から 365 日まで）、後から延長することはできません。更新するには、代わりのキーを作成して古いキーを無効化してください（環境ごとに最大 50 個のアクティブなキー）。有効期限切れのキーは 401 と API_KEY_EXPIRED を返し、API_KEY_INVALID とは区別されます。キーはフルアクセスか、特定の権限スコープに制限されたもの（例: 顧客リストへの読み取りアクセスなしでジョブリクエストを作成）のいずれかで、常に 1 つのワークスペースと 1 つの環境（ライブまたはサンドボックス）に固定されます。キーはサーバー側で保管してください。
error_code が 0 なら成功、それ以外はエラーです。バリデーション失敗時は errors にフィールドごとの詳細が入ります。
リソースを再取得する代わりに、返された next_since カーソルで GET /v1/job-requests/changes をポーリングしてデータをミラーします。
イベント（予約、顧客、テクニシャン）が発生した瞬間にプッシュ配信を受け取るには、Webhook を推奨します。エンドポイントを公開できない場合は、プル方式の代替手段として変更フィードを使用してください。

より良い結果を得るためのヒント

まずアシスタントに SKILL.md を読ませてください。コンテキストに収まる小ささで、完全な仕様なしにほとんどの連携の疑問に答えられます。
フィールド名をモデルに推測させず、openapi.json からリクエスト/レスポンスの型を生成してください。
sandbox キー（chsk_test_…）で開発し、フローが端から端まで動いてから live に切り替えてください。
デバッグ時は HTTP ステータスだけでなく error_code を確認してください。