Shopify Flow e GraphQL Admin API

O Flow usa a GraphQL Admin API da Shopify para criar automações e integrações que expandem e aprimoram o admin da Shopify. O Flow usa a versão 2026-01 da API para avaliar condições e variáveis em workflows, bem como para realizar ações na sua loja na Shopify. Como o Flow acessa os dados da loja fazendo chamadas à API, você tem acesso a praticamente todos os campos disponíveis na API pelo Flow.

Como a Shopify lança novas versões da API a cada 3 meses, alguns workflows podem precisar ser atualizados quando os campos são alterados ou descontinuados.

Uso da GraphQL Admin API em workflows

A maioria das ações no Flow usa a GraphQL Admin API para fazer alterações na sua loja na Shopify. Por exemplo, a ação Adicionar tags de pedido usa a mutação tagsAdd. A ação Enviar solicitação da Admin API pode usar a maioria das mutações, incluindo aquelas que ainda não estão disponíveis como ações no Flow.

Ao criar workflows, você encontrará com frequência nomes de campos e descrições com base na sintaxe da GraphQL Admin API. Por exemplo, para determinar a quantidade total vendável de uma variante em um workflow, você usaria a variável variants_item.inventoryQuantity. Outro exemplo: para determinar o local em que um cliente se inscreveu em sua newsletter por e-mail, você usaria a variável emailSubscriptionMethod.

Não é preciso ter experiência com a API para criar workflows com o app Flow, mas entender um pouco sobre os nomes e as definições das variáveis pode ajudar a criar a lógica de workflow específica que você deseja. Por exemplo, saber a diferença entre o displayName e o firstName de um cliente pode ajudar seu workflow a acessar os dados corretos, dependendo do uso. As definições são incluídas com cada variável durante a criação do workflow, e é possível clicar em para saber mais sobre qualquer variável ou definição.

Dados da loja e a GraphQL Admin API

Os workflows usam dados da sua loja em condições e ações. O Flow acessa os dados da loja usando a GraphQL Admin API, o que significa que você tem acesso a quase todos os campos na API. Se uma ação não tiver os dados necessários fornecidos pelo acionador ou por uma ação para coletar dados, o workflow não será executado e uma mensagem de erro será exibida.

Por exemplo, um workflow começa com um acionador Cliente criado e importa os dados do cliente para o workflow. Se esse acionador for seguido por uma ação de Adicionar tags de pedido, que exige dados do pedido e não do cliente, o workflow resultará em um erro de dados ausentes.

Pode ser necessário pré-visualizar os dados ou analisar a documentação da API para entender o que é gerado pela API e usado no Flow e para garantir que seu workflow gere os dados esperados.

Argumentos de campo e GraphQL Admin API

Alguns campos da GraphQL Admin API exigem argumentos, que são parâmetros adicionais para restringir os dados retornados. Por exemplo, o campo product.inCollection precisa do argumento id da coleção para saber qual coleção verificar. Sem isso, o campo não pode retornar um resultado.

No Flow, é possível criar variáveis com base nesses campos ao informar o valor necessário do argumento para usá-las no fluxo de trabalho. Também é possível atribuir um nome personalizado à variável para facilitar a referência nas etapas seguintes. Por exemplo, nomear product.inCollection(id: "gid://shopify/Collection/123456") como product.inSummerBestsellers.

Saiba mais sobre como criar variáveis com base em campos com argumentos.

Para criar variáveis com base em metacampos, são necessárias informações adicionais no Flow. Como é você que define o namespace e a chave de cada metacampo, os argumentos são sempre exclusivos da loja. Saiba mais sobre os metacampos no Flow.

Controle de versão da API

A Shopify lança novas versões da API a cada 3 meses, e o Flow adota as novas versões assim que possível, mas pode estar atrás da versão mais recente. Quando possível, as alterações entre as versões são resolvidas automaticamente, mas algumas alterações podem não ser diretas, incluindo qualquer uma das seguintes situações:

• Quando os campos são removidos, mas nenhuma substituição é fornecida, o que pode afetar a forma como as condições ou o Liquid são avaliados.
• Quando os campos se tornam anuláveis, o que pode afetar a forma como as condições ou o Liquid são avaliados.
• Quando os valores de enumeração mudam ou novos tipos de união ou interface são adicionados, o que pode afetar o Liquid ou o código.
• Quando os argumentos de mutação mudam, o que pode afetar a configuração das ações de Enviar solicitação da Admin API.

Alguns workflows podem precisar de atualização manual. Nesses casos, os workflows podem exibir um erro de Atualização necessária ou API não compatível e direcionar você à documentação da API relevante para fazer as alterações necessárias no editor de workflows. Quando essas atualizações são concluídas e salvas, o workflow é atualizado automaticamente para usar a versão mais recente da API disponível no Flow.

Você pode optar por ignorar os problemas temporariamente para fazer alterações urgentes em um workflow com erros de compatibilidade de versão da API. Se esses problemas não forem resolvidos, o workflow poderá parar de ser executado ou causar erros quando a versão mais antiga da API não for mais compatível com a Shopify.