ConnectWiz + API & Webhooks

稼働中の連携

販売している API と、当社が使っている API は同じ

プラットフォーム全体が1つの OpenAPI の契約で仕様化されており、当社のパネルもモバイルアプリもそこから生成されています。隠しエンドポイントも、ドキュメントのずれもありません。その上に、スコープ付きの Commerce API キー、保護された Webhook トリガー、そして自社のシステムを呼び出すフローが載ります。

無料ではじめる すべての連携
OpenAPI の契約は1つ スコープ付きの API キー HMAC で検証する Webhook
API & Webhooks × ConnectWiz
ペイロードはデータであって、命令ではない
スコープ付きキー：カタログ読み取り · 注文書き込み
Webhook → HMAC 検証 → フロー開始
フローの REST 手順が自社の API を呼ぶ
1
正本となる OpenAPI 契約の数 — 当社のパネルとモバイルアプリが生成元にしているのと同じファイルです
3
Commerce のスコープ数 — カタログ読み取り、注文読み取り、注文書き込み。キーごとに発行します
100
1回の読み取りで返る最大行数。サーバー側で制限します — limit パラメーターは検証するもので、信用するものではありません
50
API 経由の注文1件あたりの明細行数 — 明記された上限で、あとから発見するものではありません

開発者向け

できること、正確に

正本となる契約は1つ

1つの OpenAPI 3 ドキュメントがプラットフォームを仕様化し、当社の TypeScript クライアントはそこから生成されます。ドキュメントが現実からずれることはありません。現実のほうがドキュメントから作られているからです。

Commerce の API キー

テナントが発行する、明示的なスコープ付きのキーです。カタログ読み取り、注文読み取り、注文書き込み。自社のストアフロントやアプリを、同じ注文エンジンの上で動かせます。価格は常にサーバー側で解決されます。

受信 Webhook を保護

フローの Webhook トリガーには、それぞれ固有の URL とシークレット、生の本文に対する HMAC 検証、リプレイ防止が備わります。ペイロードは人を名指しできますが、フローの内部を操ることはできません。

送信はフロー経由で

REST の手順は、キャンバス上で描いたとおりの瞬間に自社のシステムを呼び出します。注文が入ったとき、同意が取得されたとき、予約が成立したとき。

技術的な仕組み

API の設計方針を明記する

価格をクライアントから受け取らない

注文のリクエストが伝えるのは、何をいくつか、だけです。名称と価格はその時点のカタログからサーバー側で読み、明細にスナップショットとして書き込みます。改ざんされたリクエストが割引をでっち上げることはできません。

呼び出す前に、できることを確認

連携の面はそれぞれ、機能の契約を公開します。電話番号で照合できるか、ゲストの注文を一覧できるか、注文を作成できるか。「いいえ」と宣言されたものを呼び出せば、奥深くで失敗するのではなく即座に例外になります。

意味のあるエラー

通信層は「認証されていない」と「サービスが落ちている」を区別します。だから「ストアに到達できない」が「この顧客は何も買っていない」として描画されることはありません。名前の付いたエラーがあるかどうかが、API と当てものの違いです。

リプレイに強い Webhook

受信したイベントは、処理の前に idempotency の台帳で一意のキーを確保します。再送も再生も、自動化の中ではなくデータベース層で止まります。

キーはハッシュ化、シークレットは範囲限定

API キーはハッシュとして保存され、入口で解決できるのはハッシュとスコープだけです。データベースの行が漏れても、ワークスペース名はわからず、スコープの外は何も開きません。

下書きと確定を明示する

注文の作成には、明示的な confirm パラメーターがあります。公開 API の既定は確定で、パネル側のフローでは下書きとして置けます。だから「これは本物か」は慣習ではなく、1つの項目で決まります。

セットアップ

接続のしくみ

01

キーの発行

パネルでスコープ付きの Commerce API キーを作成します。失効も同じ手軽さです。

02

Webhook の配線

Webhook トリガーを持つフローを作り、そのシークレットでリクエストに署名します。

03

外へ呼び返す

自社のシステムに知らせたい場所に、REST の手順を足します。

組み合わせると強い

組み合わせられる機能

Flows

Webhook のトリガーが起動するのは フロー。REST の手順は、キャンバス上で描いた瞬間に自社のシステムを呼び返します。受信と送信の自動化が、1枚のキャンバスを共有します。

Commerce

ConnectWiz の カタログと注文のエンジンは API の後ろでも、チャットショップや AI が使うものとまったく同じです。注文の真実は1つ、入口は4つ。

自社のストアフロント

いまも複数のチームが Commerce API の上でヘッドレスのストアフロントを運用しています。詳しくは Shopify のページ — ネイティブのコネクターができるまでは、当社もそこで包み隠さずこの道を勧めています。

セキュリティと保証

退屈な保証

生の本文に対する HMAC

Webhook の検証では、リクエストの生の本文をトリガーごとのシークレットで署名し、一定時間で比較します。解析に進むのは、証明が済んだあとだけです。

ペイロードはデータであって、命令ではない

Webhook のペイロードは人を参照できますが、フローの内部を操ることも、プロンプトを書き換えることも、ツールを呼び出すこともできません。データと命令のあいだの境界は、振る舞いではなくアーキテクチャで引かれています。

どの入口にもレート制限

公開エンドポイントには標準の制限がかかり、読み取りの上限はサーバー側で抑えられます。行儀の悪いクライアントが劣化させるのは自分自身であって、プラットフォームではありません。

包み隠さない但し書き

線引きを明示

全件配信はまだなし

すべてを購読する汎用の Webhook フィードは実装していません。送信イベントは現時点ではフローの手順を通ります。ここに書いておくので、営業の場でそれ以上をほのめかす必要はありません。

読み取りに上限があるのは設計

読み取りはカーソル方式で、1回あたり最大100行を返します。この API は運用のための連携に向けて作られており、一括エクスポート用ではありません。大量データが必要な場合は、抜け道ではなく相談の対象です。

API と Webhook の FAQ

率直な回答

詳しくは FAQ をご覧いただくか、 直接お問い合わせください。

プラットフォームは1つの OpenAPI 3 の契約で仕様化されています。当社の Web パネルとモバイルアプリが型を生成しているのと同じファイルです。連携先として見ているものが、そのまま当社が動かしているものです。

トリガーごとのシークレット、生の本文に対する HMAC 検証、そして idempotency の台帳によるリプレイ防止です。さらにルールとして、ペイロードはデータです。人を参照することはできても、自動化に命令することはできません。

フローの REST 手順を通じて送れます。発火するのは、キャンバス上で選んだ瞬間です。汎用の送信 Webhook フィードはロードマップ上にあり、実装するまで意図的に約束はしません。

はい。カタログの読み取りと注文の書き込みが、想定されている道です。価格はサーバー側で解決され、キーは面ごとに失効できるスコープ付きです。明細50行、読み取り100行という上限は、つまずく前に設計に織り込めるよう明記しています。

配信は当社側で冪等です。台帳が再生を認識して捨てるので、自社のシステムは安心して再送できます。フローからの送信 REST 手順には独自の再試行ポリシーがあり、失敗はそのフローの実行結果に表示されます。

派手な連携より、正直な連携を。

ここに並ぶ連携はすべて、実際の挙動で説明しています。データの向き、所有権、制約まで含めてです。

無料ではじめる すべての連携