API
プライベートなエンドポイントはありません。インターフェース用にさえも。
多くの製品には2つのAPIがあります。公開されているドキュメント付きのAPIと、自社の画面が実際に使うもう一方のAPIです。後者は常に優れていますが、あなたは決して近づくことを許されません。ここには1つしかなく、インターフェースも他と同じようにそのクライアントです。それは私たちへの制約であり、同時にあなたが作りたいものすべてが可能である理由でもあります。
このルールの実際のコスト
つまり、画面は便利なフィールドをAPIを迂回して取得するのではなく、APIが正しくなるのを時々待つ必要があるということです。画面に公開APIが提供できないものが必要になった日は、APIが間違っている日であり、修正対象はAPIです。
その見返りは、まったく異なる3つのクライアントがほぼ追加コストなしで実現できることです。MCPサーバーはクライアントです。dash-bのタイルはクライアントです。あなた自身のスクリプトもクライアントです。どれも、他人向けに設計された表面を迂回する二流の存在ではありません。二流の対象となる別の表面が存在しないからです。
ドキュメント化され、テストもされている
OpenAPIは/docsで生成され、すべてのルートにはドキュメントの例そのものであるテストが付いています。コードとは別に書かれたドキュメントは1か月以内に陳腐化しますが、間違っていればビルドが失敗するドキュメントはそうなりません。
サインイン
あなたのcastomoアカウントを、PKCE付きの認可コードフローで使用します。dash-bやファミリーの他の製品で使うのと同じアカウントです。独自のサーバーを持たないページでもこのフローは問題なく実行できます。それこそがこのフローの設計目的です。マシン間の処理には、プロジェクトスコープのAPIキーを使用します。
- 1ユーザー
/v1/contacts·/lists·/segments·/tags·/imports - 2本文
/v1/creatives— ターゲットごとのバリデーション、プレビュー、レンダリング付き - 3オートメーション
/v1/funnels·/funnels/:id/versions·/runs·/simulate - 4ブロードキャスト
/v1/campaigns— オーディエンス、実体化、スケジュール、送信が個別のステップとして - 5イベントの受信
/v1/events— あなたのアプリケーションのイベントをトリガーとして - 6配信
/sender-identities·/domains·/apps·/webhooks - 7数値
/v1/reports/*、およびトラッキングホスト上の/track/*
/docsのOpenAPI同一プロセス上の/mcp
規約
他のcastomoサービスと同じ形状
これは思った以上に重要です。これらのいずれかをすでに呼び出しているなら、このAPIがどう応答し、どう失敗し、どうページネーションするかをすでに知っています。
1つのエラー形式
すべての失敗は同じ形状を持ち、安定したコードと人間向けのメッセージを含みます。ルートごとに独自の失敗の表現方法を考案することはありません。
カーソルページネーション
オフセットではありません。参照中に変化するリストでも、行が静かにスキップされたり重複したりしません。オフセットページネーションはそれを静かに、そして絶えず起こします。
べき等性キー
すべての変更系ルートにあります。届いたか確信できないリクエストを再試行しても、2つ目の連絡先、2つ目のキャンペーン、2つ目の送信ではなく、同じ答えが返ります。
プロジェクトスコープ
トークンは1つのテナントと1つのプロジェクトの両方を指定します。行レベルセキュリティは、節を追加し忘れないことによってではなく、データベース自体で強制されます。
Webhookの送信
署名付き、バックオフ付きの再試行、少なくとも1回の配信です。そのため、あなたのエンドポイントもべき等であるべきです。イベントはレポートと同じ語彙を使用します。
消去とエクスポート
連絡先はAPIを通じてエクスポートまたは消去でき、消去はファミリー独自の内部経路を通じて、コピーを保持していたすべての姉妹サービスにまで届きます。
インターフェースでできることは、すべてPOSTでもできます。
イベントこそが本質です
このページのその他の部分は、予想どおりの配管にすぎません。POST /v1/eventsこそ、この製品の目的を変えるルートです。
アプリケーションは、マーケティングツールには観測できないことをすでに知っています。オンボーディングを完了した人、同僚を招待した人、上限に達した人、日曜の午後にデータをエクスポートした人。それらを独自のトークンでイベントとして投稿すれば、それぞれがトリガー、条件、セグメントになります。
残りはすべて連絡先モデルから導かれます。イベントは追加されるだけで、決して編集されません。それこそが、製品全体が依拠するログです。あなたが定義したイベントで発火するファネルは、統合ではありません。message_openedが使うのと同じ仕組みで、名前が違うだけです。
- 1投稿する
POST /v1/events— 名前、連絡先、ペイロード、冪等キー。 - 2届く連絡先のログに追加されます。他の何も、その存在を知る必要はありません。
- 3ファネルが開始するそのイベントを入口に指定しているファネルは、入口の条件を満たすすべての連絡先に対して開始します。
- 4他のファネルが分岐する「このイベントが過去14日以内に発生したか」は、通常のセグメント述語です。
- iそして実行を終了させる同じイベントを指定するゴールノードは、その人がその行動をした瞬間にシーケンスを停止させます。
あなたの語彙あなたのトークン
構築前に知っておくべき境界
ClickSomoはあなたについて3つの識別子(テナント、プロジェクト、ユーザー)を不透明なIDとして保存するだけで、それ以外は何も保存しません。パスワードも、プロフィールも、カードも、請求書もありません。プランの上限は数値として届きます。連絡先の数、送信数、生成数。支払いに関する語彙は、どちらの方向にもこの線を越えません。
あなたの連絡先はあなたのものです。あなたがデータ管理者であり、当社は処理者です。ファミリー内の他の製品があなたの連絡先リストを読み書きできる経路は存在せず、それが使える取り込み経路もありません。
本格的に評価される場合:このサイトの続きを読む前に、まず/docsをお読みください。APIこそ、この製品が何をするかの正直な記述であり、これらのページの主張はすべて、そこで見つけられるルートまたはノード種別に対応しています。スキーマが変われば、これらのページも変わります。