Skip to Content
API 參考公開回呼

公開回呼

先為指定資料表鑄造回呼憑證，再以只顯示一次的密鑰送出外部新增或更新；整合結束後應撤銷該憑證。

同一份憑證也能讀取目標資料表的可寫欄位，讓公開表單自行產生欄位，而不必寫死一組會隨版主改名而失效的名稱。

POST
路由範本/public/module/custom_tables/callback/{token_id}

以公開回呼寫入資料列

用途

讓外部系統使用綁定單一資料表的回呼憑證新增或更新資料列。

適用時機

ERP、表單或其他無 TeamSync 帳號的系統需要把事件寫入指定資料表時使用。

實際掛載路徑
  • 完整路由/public/module/custom_tables/callback/{token_id}

範圍

範圍是否提供驗證與權限
完整路由可使用callback token (minted)

參數

欄位位置型別必填說明
token_idpathuuid是鑄造回呼憑證時取得的 token_id；它是 URL 憑證的一半。

請求結構

CallbackRequest

OpenAPI 快照中沒有此模型的頂層元件欄位。

回應結構

CallbackResponse
欄位型別必填說明
okboolean否Always true on a 2xx response (the submission was accepted)
op"create" | "update"是The operation the request asked for
process_idstring | null否ReviewProcess now holding the write (held_for_approval / already_pending)
record_idstring | null否Id of the created/updated record; null when status is held_for_approval or already_pending (no row exists until a reviewer approves)
replayedboolean否True when idempotency_key matched a previous accepted request — no new write or staged change happened. Created/updated and held/already-pending outcomes are replayable for 24 hours.
rule_labelstring | null否Human label of the require_approval rule that held the write — safe to show the submitter (held_for_approval only)
staged_change_idstring | null否Staged change holding the write (held_for_approval / already_pending)
status"created" | "updated" | "held_for_approval" | "already_pending"是Outcome discriminator. created/updated: the write landed and record_id is set. held_for_approval: a require_approval rule matched — the write is staged and now awaits review (process_id/staged_change_id set, record_id null); this is a terminal success, do NOT resubmit. already_pending: an identical submission (same approval match column value) or the target record is already held by the returned process — no second change was staged.

範例

以具冪等鍵的回呼新增訂單

請求
{
  "pathParams": {
    "token_id": "11111111-1111-4111-8111-111111111111"
  },
  "body": {
    "op": "create",
    "data": {
      "訂單編號": "ORD-1042",
      "數量": 3
    },
    "idempotency_key": "event-1042"
  }
}
回應200
{
  "ok": true,
  "op": "create",
  "status": "created",
  "record_id": "22222222-2222-4222-8222-222222222222",
  "process_id": null,
  "staged_change_id": null,
  "rule_label": null,
  "replayed": false
}

錯誤

狀態發生條件錯誤本文
400請求格式、允許操作、資料規則或欄位內容不合法。
{
  "detail": "op 'update' requires record_id"
}
404token 不存在、已撤銷、已過期，或所提供的密鑰驗證失敗。
{
  "detail": "Not found"
}
413原始請求本文超過 64 KB。
{
  "detail": "body exceeds 65536 bytes"
}
423資料表正被遷移鎖定。
{
  "detail": "Table is currently locked for a migration"
}
429單一 token 超過每分鐘 60 次，或待覆核暫存變更已達上限。
{
  "detail": "rate limit exceeded (60/min per token)"
}
GET
路由範本/public/module/custom_tables/callback/{token_id}/form-schema

讀取回呼 token 背後的可寫欄位

用途

回傳目標資料表的顯示名稱與可寫欄位（名稱與型別），讓外部表單在送出回呼寫入前先自行產生欄位。

適用時機

當公開表單應該依資料表動態產生欄位，而不是寫死一組會隨版主改名而失效的欄位名稱時使用。

實際掛載路徑
  • 完整路由/public/module/custom_tables/callback/{token_id}/form-schema

範圍

範圍是否提供驗證與權限
完整路由可使用callback token (Bearer secret or HMAC signature — same credential as the write route)

參數

欄位位置型別必填說明
token_idpathuuid是回呼（寫入）token 的 token_id——與你送出寫入請求時使用的網址是同一半憑證。

回應結構

CallbackFormSchemaResponse
欄位型別必填說明
columnsPublicColumnInfo[]是Writable columns (name + type). Computed columns omitted.
table_namestring是Display name of the target table.

範例

依 token 的目標資料表產生表單

請求
{
  "pathParams": {
    "token_id": "11111111-1111-4111-8111-111111111111"
  }
}
回應200
{
  "table_name": "訂單回報",
  "columns": [
    {
      "name": "訂單編號",
      "type": "string"
    },
    {
      "name": "數量",
      "type": "integer"
    },
    {
      "name": "狀態",
      "type": "select"
    },
    {
      "name": "備註",
      "type": "text"
    },
    {
      "name": "回報時間",
      "type": "datetime"
    }
  ]
}

錯誤

狀態發生條件錯誤本文
404token 不存在、已撤銷、已過期，憑證驗證失敗，或目標資料表已不存在——這五種情況都回傳完全相同的 404。
{
  "detail": "Not found"
}
Last updated on
複合指令JSONL IaC