Formatos de corpo e divisão de matrizes

Nem todo sistema envia JSON, e nem toda solicitação se refere a um único item. Duas configurações abrangem ambos os casos.

Formatos de corpo

O formato é obtido a partir do cabeçalho Content-Type da solicitação. Seja qual for o formato, seu mapeamento de campos utiliza os mesmos caminhos com pontos.

Tipo de conteúdo	Analisado como	Remetentes típicos
application/json	JSON	A maioria das APIs, n8n, Make, Zapier
application/x-www-form-urlencoded	Campos do formulário	Twilio, PayPal IPN, formulários em HTML simples
multipart/form-data	Os campos do formulário e as partes do arquivo passam a constituir o nome do arquivo	Criadores de formulários, pontos de destino de upload
text/xml, application/xml, *+xml	XML	Sistemas ERP e de transportadoras mais antigos

Dois detalhes que vale a pena saber:

• Um corpo de mensagem que seja um JSON válido é sempre interpretado como JSON, mesmo quando o remetente o identifica como outra coisa. Muitas ferramentas enviam JSON com um tipo de conteúdo de formulário, e isso faz com que continuem funcionando.
• Os corpos de formulários e XML podem conter campos que o senhor não mapeou. Isso não representa problema: o remetente define sua própria estrutura; portanto, esses corpos não passam pela verificação rigorosa que se aplica ao JSON que o senhor controla.

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

Atributos XML

Um atributo XML está disponível com seu nome precedido pelo prefixo @_; assim, <order id="7"> é mapeado como order.@_id, e <order><name>Bob</name></order> é mapeado como order.name. Os valores são fornecidos como texto, o que mantém a exatidão dos IDs longos.

Divisão de matrizes em sequências

Quando uma solicitação contém uma lista - 20 pedidos de um ERP, um lote de atualizações de estoque - , normalmente é desejável que seu fluxo de trabalho seja executado uma vez por item, e não uma única vez para todo o lote.

Em Configurações avançadas -> Dividir matrizes em séries, indique o caminho para a matriz:

Caminho	Utilize quando
items	A matriz é um campo de nível superior: { "items": [ ... ] }
data.orders	Está aninhado: { "data": { "orders": [ ... ] } }
$	O próprio corpo do texto é a matriz: [ { ... }, { ... } ]
(vazio)	Desativado. Uma execução por solicitação, que é a configuração padrão.

Cada elemento passa a constituir sua própria execução, tendo esse elemento como payload; portanto, os caminhos de mapeamento são relativos ao item: mapeie sku, e não 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 }

Regras e limites

• No máximo 100 itens por solicitação. Um lote maior será rejeitado para que um remetente descontrolado não sobrecarregue seu fluxo de trabalho.
• Se algum item não tiver um campo mapeado ou for grande demais para o Shopify Flow, a solicitação inteira será rejeitada e nada será enviado, com a posição do item com falha indicada na mensagem de erro. Isso garante que um lote seja processado na íntegra ou não seja processado de forma parcial.
• Os itens que são valores simples, em vez de objetos, são recebidos como { "value": ... }.
• A divisão não pode ser combinada com uma resposta síncrona: uma chamada não pode ser atendida por várias execuções. Consulte Resposta síncrona.
• Ao reproduzir uma execução anterior a partir do Histórico, esse único item é reenviado, e não todo o lote.

Em História

Cada item constitui uma entrada separada, de modo que o(a) senhor(a) pode visualizar, tentar novamente e reproduzir cada um deles separadamente.