Use este artigo para configurar os quatro modelos pré-construídos de conector de dados Shopify do Fin — para que o Fin possa cotar reembolsos, emitir crédito na loja e verificar ou revogar cartões-presente durante uma conversa de suporte, sem a intervenção de um colega.
Conectores de dados permitem que o Fin chame APIs externas (application programming interfaces) durante a conversa para buscar ou atualizar dados ao vivo. Os modelos Shopify são conectores pré-configurados que chamam a Shopify Admin REST API em seu nome. Escopos de API são as permissões específicas que sua loja Shopify deve conceder antes que um conector possa ler ou gravar esses dados.
O que cada modelo de compensação Shopify faz
Os quatro modelos de conector de dados Shopify para Fin estão listados abaixo — cada um cobre uma parte diferente do fluxo de trabalho de compensação.
Calcular Reembolso Shopify
Cota um reembolso — incluindo frete reembolsável, imposto e o máximo reembolsável por transação de pagamento — sem movimentar dinheiro. Esta é uma ação de simulação: calcula quanto seria o reembolso antes de qualquer emissão. Combine com a ação Criar Reembolso Shopify quando quiser que o Fin confirme o valor com o cliente antes de processar. Não grava no Shopify.
Emitir Cartão-Presente Shopify
Emite crédito na loja como um cartão-presente Shopify. O Shopify envia o código diretamente por e-mail ao cliente — o código resgatável nunca é retornado ao Fin nem visível na conversa. O Fin vê apenas o ID do cartão, saldo, moeda, validade e os últimos 4 caracteres. Este modelo grava no Shopify.
Obter Saldo do Cartão-Presente Shopify
Verifica o saldo restante, valor inicial e data de validade do cartão-presente Shopify de um cliente. Use quando um cliente perguntar quanto crédito ainda tem ou se um cartão foi usado. Não grava no Shopify.
Desativar Cartão-Presente Shopify
Revoga um cartão-presente que foi emitido incorretamente — por exemplo, enviado com valor errado, para o cliente errado ou emitido por engano. O cartão para de funcionar imediatamente.
Importante: Esta ação não pode ser desfeita — o Shopify não tem como reativar um cartão-presente desativado. Se um cartão for revogado por engano, emita um substituto usando o modelo Emitir Cartão-Presente Shopify.
Como adicionar um modelo
Encontre o modelo que deseja adicionar na seção Shopify.
Conecte (ou reutilize) sua conexão da loja Shopify — a URL da ação direciona automaticamente para a loja conectada ao seu workspace. Não é necessária configuração de domain por ação.
Revise os parâmetros preenchidos, descrição e orientações de uso do Fin. Clique em Ativar para ativar o modelo. Você verá o conector listado como ativo em Configurações > Integrações > Conectores de dados.
Nota: Cada modelo é ativado por workspace. Uma vez ativo, teste o conector em uma conversa real — o modo de visualização do Fin não faz chamadas reais ao conector de dados.
Permissões Shopify necessárias
Antes de adicionar os modelos de cartão-presente, sua loja Shopify deve ter os escopos read_gift_cards e write_gift_cards. O Shopify não concede esses por padrão — um administrador do comerciante deve solicitá-los ao Suporte Shopify.
Importante: Todos os três modelos de cartão-presente (Emitir Cartão-Presente Shopify, Obter Saldo do Cartão-Presente Shopify, Desativar Cartão-Presente Shopify) retornarão erro de autorização até que esses escopos sejam concedidos. Esta é a causa mais provável de falha na primeira execução. Após o Suporte Shopify conceder os escopos, volte para Configurações > Integrações > Conectores de dados para adicionar ou re-testar seus modelos de cartão-presente — não é necessária reinstalação do app Shopify.
O modelo Calcular Reembolso Shopify tem um requisito separado: precisa do escopo orders ou marketplace_orders, que o Shopify concede por padrão.
Limitações conhecidas
As seguintes limitações se aplicam aos quatro modelos de conector de dados Shopify para Fin. Cada limitação nomeia o modelo ou modelos afetados.
Calcular Reembolso Shopify — cotações apenas por pedido e frete. A cotação por item não é suportada por este modelo. O parâmetro de moeda também deve corresponder exatamente à moeda do pedido, ou o Shopify rejeita a solicitação.
Desativar Cartão-Presente Shopify — esta ação é irreversível. O Shopify não possui endpoint de API para reativar (habilitar) um cartão desativado. Se um cartão for revogado por engano, emita um substituto usando o modelo Emitir Cartão-Presente Shopify.
Emitir Cartão-Presente Shopify — o código do cartão-presente nunca é visível na conversa. Quando o Fin usa este modelo, o Shopify envia o código diretamente por e-mail ao cliente. Se um cliente disser que não recebeu, verifique o endereço de e-mail do cliente no Shopify Admin e o próprio log de notificações do Shopify.
Todos os quatro modelos — os campos de resposta são limitados ao que está listado na configuração de cada modelo. Apenas os atributos de resposta explicitamente listados em um modelo são legíveis pelo Fin — quaisquer outros campos do Shopify são ocultados e indisponíveis.
Perguntas frequentes
O Fin mostrará o código do cartão-presente ao cliente na conversa?
O Fin mostrará o código do cartão-presente ao cliente na conversa?
Não — o Fin não mostrará o código do cartão-presente ao cliente na conversa. Quando o Fin emite um cartão-presente usando o modelo Emitir Cartão-Presente Shopify, o Shopify envia o código diretamente por e-mail ao cliente. O código resgatável nunca é retornado ao Fin nem visível na conversa. O Fin vê apenas o ID do cartão, saldo, moeda, data de validade e os últimos 4 caracteres.
O Fin pode cotar um reembolso antes de realmente emiti-lo?
O Fin pode cotar um reembolso antes de realmente emiti-lo?
Sim — o Fin pode cotar um reembolso antes de realmente emiti-lo. O modelo Calcular Reembolso Shopify retorna uma cotação de reembolso — frete reembolsável, imposto e o valor máximo reembolsável — sem movimentar dinheiro. Use-o junto com a ação Criar Reembolso Shopify existente quando quiser que o Fin faça a cotação primeiro e depois confirme antes de emitir.
O que acontece se um cartão-presente for revogado?
O que acontece se um cartão-presente for revogado?
Se um cartão-presente for revogado usando o modelo Desativar Cartão-Presente Shopify, o cartão para de funcionar imediatamente e não pode ser restaurado. O Shopify não possui endpoint para reativar (habilitar) um cartão desativado. Se um cartão foi revogado por engano, emita um substituto usando o modelo Emitir Cartão-Presente Shopify.
Qual versão da API Shopify esses modelos usam?
Qual versão da API Shopify esses modelos usam?
Os quatro modelos de conector de dados de compensação Shopify usam a Shopify Admin REST API (application programming interface) versão 2025-04.