正文格式與陣列分割

並非每個系統都會傳送 JSON，也並非每個請求都只涉及一項內容。兩項設定即可涵蓋這兩種情況。

正文格式

格式會從請求的 Content-Type 標頭中取得。無論格式為何，您的欄位映射都會使用相同的點路徑。

內容類型	解析結果為	常見的發件人
application/json	JSON	大多數 API、n8n、Make、Zapier
application/x-www-form-urlencoded	表單欄位	Twilio、PayPal IPN、純 HTML 表單
multipart/form-data	表單欄位、檔案片段將成為檔案名稱	表單建立工具、上傳端點
text/xml, application/xml, *+xml	XML	較舊的 ERP 系統與承運商系統

有兩點細節值得了解：

• 只要正文內容符合** JSON** 格式，系統就會將其視為 JSON 來讀取，即使發送方將其標記為其他類型亦然。許多工具會以表單內容類型傳送 JSON，而這種做法能確保它們正常運作。
• 表單和 XML 內容可能包含您尚未進行映射的欄位。這沒問題：由於發送方自行決定其格式，因此這些內容會跳過適用於您所控制的 JSON 的嚴格檢查。

curl -X POST https://your-app-url/webhook/ab12cd34 \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Api-Key: your-token" \
  --data-urlencode "From=+15551234567" \
  --data-urlencode "Body=Where is my order?"

# Map fieldOne to: From
# Map fieldTwo to: Body

XML 屬性

XML 屬性會以其名稱加上 @_ 前綴的形式提供，因此 <order id="7"> 會映射為 order.@_id，而 <order><name>Bob</name></order> 則會映射為 order.name。值以文字形式傳遞，這能確保長識別碼的準確性。

將陣列拆分為區段

當一個請求包含一組清單時 - - 例如來自 ERP 的 20 筆訂單，或是一批庫存更新 - - 您通常希望工作流程針對每個項目執行一次，而非針對整個批次執行一次。

在**「進階設定」→「將陣列拆分為運行」**中，為陣列指定路徑名稱：

路徑	適用於以下情況：
items	該陣列為頂層欄位：{ "items": [ ... ] }
data.orders	這是嵌套的：{ "data": { "orders": [ ... ] } }
$	該內容本身就是一個陣列：[ { ... }, { ... } ]
(空白)	關閉。每項請求執行一次，此為預設設定。

每個元素都會成為一個獨立的執行流程，並以該元素作為有效載荷，因此映射路徑是相對該項目的：應使用 map sku，而非 items.0.sku``。

{
  "items": [
    { "sku": "ABC-1", "qty": 2 },
    { "sku": "ABC-2", "qty": 1 },
    { "sku": "ABC-3", "qty": 7 }
  ]
}

// Split path: items
// Map fieldOne to: sku
// Map fieldTwo to: qty
// Response: { "runs": 3, "blocked": 0 }

規則與限制

• 每次請求最多 100 項。若批次數量超過此限，系統將予以拒絕，以防止惡意發送者淹沒您的工作流程。
• 若任何項目缺少已映射的欄位，或其大小超出 Shopify Flow 的限制，則整個請求將被拒絕且不會傳送任何資料，同時錯誤訊息中會標示出失敗項目的位置。此機制確保批次處理採「全有或全無」的原則，而非僅部分成功。
• 那些是純值而非物件的項目，會以 { "value": ... } 的形式傳入。
• 拆分操作無法與同步回應結合使用：一個呼叫者無法由多個執行程序來回應。請參閱 同步響應。
• 從「歷史紀錄」中重播過去的執行結果時，系統會重新傳送該單一項目，而非整個批次。

在歷史上

每項內容都是獨立的條目，因此您可以分別檢視、重新嘗試及重播每一項。