Formatos de corpo e divisão de matrizes

Nem todos os sistemas enviam JSON, e nem todos os pedidos dizem respeito a um único elemento. Duas definições abrangem ambos os casos.

Formatos de corpo

O formato é obtido a partir do cabeçalho Content-Type do pedido. Independentemente do formato, o 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 HTML simples
multipart/form-data	Os campos do formulário e as partes do ficheiro passam a constituir o nome do ficheiro	Criadores de formulários, pontos de fim de carregamento
text/xml, application/xml, *+xml	XML	Sistemas ERP e de transportadoras mais antigos

Dois pormenores que vale a pena conhecer:

• Um corpo que seja 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, o que permite que continuem a funcionar.
• Os corpos em formato Form e XML podem conter campos que ainda não tenha mapeado. Não há problema: o remetente decide a sua própria estrutura, pelo que esses corpos não são sujeitos à 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 o 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 apresentados como texto, o que permite manter a exatidão dos identificadores longos.

Divisão de matrizes em sequências

Quando um pedido inclui uma lista - 20 pedidos provenientes de um ERP, um lote de atualizações de stock - , normalmente pretende que o seu fluxo de trabalho seja executado uma vez por item, e não uma única vez para todo o lote.

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

Caminho	Utilizar 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 pedido, o valor predefinido.

Cada elemento passa a constituir a sua própria execução, tendo esse elemento como payload; por isso, 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 pedido. Um lote maior é rejeitado, para que um remetente descontrolado não possa sobrecarregar o seu fluxo de trabalho.
• Se algum item não tiver um campo mapeado ou for demasiado grande para o Shopify Flow, todo o pedido é rejeitado e nada é enviado, sendo a posição do item com falha indicada no erro. Isso garante que um lote seja processado na íntegra ou não seja processado de todo, em vez de ser processado parcialmente.
• Os elementos 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, é reenviado apenas esse elemento específico, e não todo o lote.

Na História

Cada item constitui uma entrada própria, pelo que pode visualizar, repetir a tentativa e rever cada um deles separadamente.