正文格式和数组拆分

并非每个系统都会发送 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。值以文本形式传递，从而确保长 ID 的精确性。

将数组划分为片段

当一个请求包含一个列表时 - - 例如来自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": ... }的形式出现。
• 拆分不能与同步响应结合使用：一个调用者不能由多个运行实例来响应。参见 同步响应。
• 从“历史记录”中重播过去的运行会重新发送该单个项目，而非整个批次。

在“历史”栏目中

每个项目都是一个独立的条目，因此您可以分别查看、重试和回放每个项目。