API
冇私人 endpoint。連介面自己都冇。
大部分產品有兩個 API：一個係攞出嚟俾你用、有文件嗰個，另一個係佢自己畫面用緊嗰個好玩嘅。第二個永遠好啲，但你永遠掂唔到。呢度只有一個，介面同其他嘢一樣都係佢嘅 client——呢個係對我哋嘅限制，亦係你想建嘅嘢全部都建到嘅原因。
呢條規則實際上嘅代價
即係話，有時一個畫面要等 API 修正先至得，而唔係繞過佢攞一個方便嘅欄位。邊日一個畫面需要一樣公開 API 俾唔到嘅嘢，嗰日就係 API 錯咗，而修正方法係改 API。
回報係，三個好唔同嘅 client 幾乎唔使額外成本。MCP server 係一個 client。dash-b 嘅一塊 tile 係一個 client。你自己嘅 script 係一個 client。冇一個係二等公民，要喺一個為其他人設計嘅介面上繞路，因為根本冇第二個介面俾你做二等。
有文件，仲有測試
OpenAPI 會喺 /docs 生成，而每一條 route 都有一個測試，內容就係文件入面嗰個例子。同程式碼分開寫嘅文件，一個月內就會走樣；錯嘅時候會令 build 失敗嘅文件就唔會。
登入
你嘅 castomo 帳戶，行 authorization code flow 加 PKCE——同你用 dash-b 同成個家族其他嘢嗰個帳戶一樣。一個冇自己 server 嘅頁面完全行到呢個 flow，呢個 flow 本來就係為咗咁而設計。機器對機器嘅工作，就用 project 範圍嘅 API key。
- 1人
/v1/contacts·/lists·/segments·/tags·/imports - 2內容
/v1/creatives，每個 target 都有驗證、預覽同渲染 - 3自動化
/v1/funnels·/funnels/:id/versions·/runs·/simulate - 4廣播
/v1/campaigns，受眾、materialise、排程同發送係各自獨立嘅步驟 - 5事件輸入
/v1/events——你自己應用程式嘅事件，作為觸發條件 - 6派遞
/sender-identities·/domains·/apps·/webhooks - 7數字
/v1/reports/*，同追蹤 host 上嘅/track/*
OpenAPI 喺 /docs/mcp 喺同一個 process
慣例
同其他 castomo 服務一樣嘅形狀
呢樣嘢比聽落重要。如果你已經 call 過其中一個，你已經知道呢個點回應、點失敗、點分頁。
一個錯誤格式
每一次失敗都係同一個形狀：一個穩定嘅 code，同一句寫俾人睇嘅訊息。冇任何 route 自創一套發脾氣嘅方式。
Cursor 分頁
唔係 offset。一個你行緊嗰陣會變嘅列表，唔會靜靜雞跳行或者重複行——offset 分頁就係咁樣靜靜咁、不斷咁做。
Idempotency key
每一條會改嘢嘅 route 都有。你唔肯定有冇送到嘅 request 可以重試，會攞返同一個答案，而唔係多一個聯絡人、多一個 campaign 或者多一次發送。
以 project 為範圍
一個 token 指向一個 tenant 同一個 project，兩樣都係。Row-level security 喺資料庫本身強制執行，唔係靠記得加一個 clause。
Webhook 輸出
有簽名、會用 backoff 重試、至少派一次——所以你嘅 endpoint 都應該係 idempotent。事件嘅詞彙同報告用嘅係同一套。
刪除同匯出
一個聯絡人可以經 API 匯出或者刪除,而刪除會經家族內部嘅專用通道,傳到去每一個有副本嘅姊妹服務度。
介面做到嘅嘢,一個 POST 都做到。
事件先係有趣嘅部分
呢一頁其他嘅嘢都係你預期得到嘅基建。POST /v1/events 先係改變產品用途嘅嗰條路線。
你嘅應用程式已經知道啲市場推廣工具觀察唔到嘅嘢:邊個完成咗 onboarding、邊個邀請咗同事、邊個撞到上限、邊個喺星期日下午匯出咗自己嘅資料。用你自己嘅 token 將呢啲以事件形式 POST 上嚟,每一個都會變成一個觸發器、一個條件同一個分眾。
其餘嘅嘢都係由聯絡人模型推導出嚟。事件只會附加,永遠唔會編輯;佢哋係成個產品掛住嘅日誌。一個由你自己定義嘅事件觸發嘅漏斗,唔係一個整合——佢同 message_opened 用嘅係同一套機制,只係入面個名唔同。
- 1你 POST 佢
POST /v1/events— 一個名、一個聯絡人、一個 payload、一個冪等鍵。 - 2佢到咗附加到聯絡人嘅日誌度。冇其他嘢需要知道佢存在。
- 3一個漏斗開始任何入口指明嗰個事件嘅漏斗,對任何符合佢入口條件嘅聯絡人都會啟動。
- 4其他漏斗喺佢度分岔「呢個事件喺過去 14 日有冇發生過」係一個普通嘅分眾謂詞。
- i而且佢會終止行程一個指明同一個事件嘅目標節點,會喺個人做嗰件事嘅一刻停止一個 sequence。
你嘅詞彙你嘅 token
起樓之前值得知道嘅界線
ClickSomo 只會儲存三個關於你嘅識別碼——一個 tenant、一個 project 同一個 user,全部係不透明嘅 id——其他乜都冇。冇密碼、冇個人檔案、冇卡、冇發票。計劃限制以數字形式到達:幾多個聯絡人、幾多次發送、幾多次生成。付款相關嘅詞彙唔會喺任何一個方向越過嗰條線。
你嘅聯絡人係你嘅。你係資料控制者;我哋係處理者。冇任何路線可以令家族入面另一個產品讀取或者寫入你嘅聯絡人名單,亦都冇一條畀佢哋用嘅匯入通道。
如果你係認真咁評估緊呢樣嘢:喺再讀呢個網站任何嘢之前,先讀 /docs。API 先係誠實描述呢個產品做啲乜嘅地方,而呢幾頁嘅每一個宣稱都對應到一條路線或者一種節點類型,你可以喺嗰度搵到。當 schema 改變,呢幾頁都會改變。