事件格式

所有事件共用相同外層結構：

欄位	型別	說明
`type`	string	事件類型
`api_version`	string	規格版本，目前為 `2026-10-01`
`id`	string	事件 ID，與 `webhook-id` 標頭相同；可依字典序排序
`created_at`	string	事件建立時間（ISO 8601，UTC）
`data`	object	依事件類型而定

scan.created

App 使用者完成一筆掃描。

{
  "type": "scan.created",
  "api_version": "2026-10-01",
  "id": "evt_01JB8Z3K9Q4C7XR2M5N6P8T0VW",
  "created_at": "2026-10-02T00:00:01.123Z",
  "data": {
    "scan_id": "5f0c2c1e-3b0a-4c39-9d0c-2f1d8f6b7a11",
    "scanned_at": "2026-10-02T07:59:58+08:00",
    "issuer": "GS1",
    "format": "gs1_element_string",
    "raw": "]d2010081234567890117270531",
    "di": "00812345678901",
    "lot": "A123",
    "serial": "S0001",
    "expiry": "2027-05-31",
    "production_date": null,
    "gudid": {
      "status": "found",
      "brand_name": "Sample Device",
      "company_name": "Sample Medical Inc.",
      "model_number": "SD-100"
    },
    "batch_id": null,
    "source": {
      "org_id": "org_8x2k4m9q0r1s3t5v7w",
      "member_id": "mem_2b4d6f8h0j2k4m6n8p",
      "member_label": "3F 開刀房 iPhone 2"
    }
  }
}

data 欄位

欄位	型別	說明
`scan_id`	uuid	App 產生的掃描 ID；同一使用者內唯一
`scanned_at`	date-time	裝置上的掃描時間（含時區）
`issuer`	`GS1` / `HIBCC`	發碼機構
`format`	string	`gs1_element_string`、`gs1_digital_link`、`hibcc`
`raw`	string	條碼原始內容；GS1 的 FNC1 以 ASCII 29 表示，主次條碼合併時以 `\n` 分隔
`di`	string	器材識別碼；GS1 為 14 碼 GTIN
`lot`	string 或 null	批號（AI 10）
`serial`	string 或 null	序號（AI 21）
`expiry`	date 或 null	效期（AI 17）；日為 `00` 時已換算為當月最後一天
`production_date`	date 或 null	製造日期（AI 11）
`gudid`	object 或 null	App 在裝置上查詢 FDA AccessGUDID 的結果；`status` 為 `found`、`not_found`、`unknown`
`batch_id`	uuid 或 null	批次掃描的批次 ID
`source`	object	送出者：`org_id`（個人模式為 null）、`member_id`（組織模式 `mem_...`、個人模式 `sub_...`，請視為不透明字串）、`member_label`（組織 Admin 自訂的代稱）

endpoint.verification

建立或變更網址後按「驗證」時送出。請回 200 與：

{ "challenge": "與 data.challenge 相同的字串" }

endpoint.test

按「送出測試事件」時送出。data 為範例掃描，格式與 scan.created 相同。建議你的系統把它當成正式事件處理流程的一部分測試，但不要寫入正式資料。

相容性

同一 api_version 內只會新增欄位或事件類型，請忽略不認得的欄位與 type。
破壞性變更會發布新的 api_version 並提前公告（見版本紀錄）。

完整的 OpenAPI 3.1 規格：openapi.yaml，或看互動式 API 參考。