Conectar o Loop Returns: devoluções chegam por webhook, sinalize e processe no armazém

Crie uma API key com o scope returns no Loop admin em Returns Management → Tools & integrations → Developer Tools, preencha essa única chave no Integration, entenda por que o teste fica pendente de verificação e ative.

O conector do Loop Returns conecta seu portal de devoluções da Loop ao sistema de devoluções (RMS). As devoluções não são trazidas pela API: chegam por webhook quando os compradores as criam na Loop. Depois que entram, o armazém trabalha aqui: sinalizar uma devolução e processar uma devolução são as duas ações desta conexão. Ela não cria etiquetas de devolução. A conexão tem um único campo, a Loop API Key.

Pré-requisitos#

• Uma conta da Loop à qual você consiga entrar como administrador, com acesso a Returns Management → Tools & integrations → Developer Tools.
• As devoluções acontecem primeiro na Loop: os compradores iniciam a devolução na Loop e esta conexão a recebe; não é um lugar para criar uma devolução do zero.
• Entenda a via de entrada antes de começar: as devoluções chegam apenas por webhook, não há uma extração por API programada para esperar e esta conexão não fornece etiquetas de devolução.

Obter credenciais#

1. Entre no Loop admin.
2. Vá para Returns Management → Tools & integrations → Developer Tools.
3. Crie ali uma nova API key e certifique-se de incluir o scope returns. O scope returns é um requisito obrigatório: sem ele, as ações de sinalizar e processar devoluções falharão depois.
4. Copie a chave completa. Quando este sistema se comunica com a Loop, a chave é enviada no cabeçalho X-Authorization: você não preenche esse cabeçalho em lugar nenhum, só preenche a chave.

Preencher no Integration#

1. Abra Integration → Marketplace → Loop Returns → Nova conexão.
2. api_key, obrigatório, Loop API Key: cole a chave criada no Loop admin → Returns Management → Tools & integrations → Developer Tools, completa e com o scope returns. É um campo do tipo senha e é guardado como segredo. Esta conexão não tem outros campos: nem endereço da loja, nem endereço de servidor, nada mais para preencher.
3. Salve a conexão e execute o teste, e leia primeiro a próxima seção, porque o resultado do teste deste canal não se parece com o dos outros.

Testar a conexão#

Clique em Testar a conexão e espere este resultado: com uma chave real preenchida, o teste não volta como aprovado, volta como não aprovado, pendente de verificação, e não envia nenhuma solicitação à Loop. Esse é o comportamento esperado para este canal, não um sinal de que sua chave esteja errada. O motivo é simples: a Loop não tem uma verificação somente leitura verificada que possa provar que a chave funciona sem alterar dados. As ações conhecidas da Loop, sinalizar e processar, alteram uma devolução, então não podem ser usadas como teste inofensivo, e o caminho de leitura dos detalhes da devolução não foi confirmado na documentação oficial. Por isso o teste só verifica que há uma chave presente, envia zero solicitações e informa pendente de verificação. Não fique recriando chaves buscando um resultado verde: uma chave correta com o scope returns mostra exatamente este resultado. Se testar com a chave vazia, o resultado é apenas uma verificação simulada e vem rotulado como simulado; não prova nada sobre uma conta real da Loop.

Mapping / escolher modelo#

Escolha o mapping padrão do Loop Returns. Ele pega uma devolução que chega por webhook e a registra como uma devolução no sistema de devoluções, com sua referência de devolução, referência do pedido, itens e quantidades como enviados pela Loop. Antes de ativar, percorra uma devolução real: inicie uma devolução na Loop, deixe ela chegar e compare a devolução aqui com a Loop lado a lado: referência, itens e quantidades. Se algo não bater, ajuste esse campo no mapping em vez de mudar algo na Loop.

Ativar#

Após ativar, as devoluções criadas na Loop chegam por webhook e aparecem como devoluções para trabalhar. O armazém abre aqui uma devolução, sinaliza quando ela precisa de atenção e processa quando a devolução está tratada: essas duas ações são enviadas à Loop para essa devolução. Acompanhe as primeiras devoluções reais em Runs / Logs e compare com a Loop antes de deixar a conexão sem supervisão.

O que esta conexão não faz: não traz devoluções da Loop pela API segundo uma programação, então não há um botão de sincronização para esperar; e não cria etiquetas de devolução, então os compradores continuam recebendo suas etiquetas como a própria Loop as fornece. As devoluções começam na Loop, chegam por webhook e aqui são sinalizadas e processadas.

Perguntas frequentes#

Preenchi uma chave real, mas o teste diz não aprovado, pendente de verificação

Este é o resultado esperado para o Loop Returns, mesmo com uma chave perfeita. A Loop não tem uma verificação somente leitura verificada que possa provar que uma chave funciona sem alterar dados, então o teste não envia nenhuma solicitação e informa pendente de verificação. O resultado diz que há uma chave presente; não diz que a chave esteja errada.

Pare de recriar chaves. Confirme que a chave salva é a criada no Loop admin → Returns Management → Tools & integrations → Developer Tools com o scope returns, continue para o mapping e a ativação, e julgue a conexão pela primeira devolução real que chegar por webhook.

O teste parecia bem sem chave, mas nada real acontece

Com a chave vazia, o teste só executa uma verificação simulada e rotula o resultado como simulado. Esse resultado nunca se comunica com sua conta da Loop, então não pode trazer devoluções nem enviar ações de sinalizar e processar.

Crie uma API key real com o scope returns no Loop admin → Returns Management → Tools & integrations → Developer Tools, cole no campo api_key e salve. Depois, o teste mostrará pendente de verificação: para este canal, é assim que uma chave real se parece.

Sinalizar ou processar uma devolução falha

A causa mais provável é a própria API key: sinalizar e processar são as ações que se comunicam com a Loop e precisam de uma chave criada com o scope returns. Uma chave criada sem esse scope pode estar na conexão parecendo completa, enquanto a Loop recusa cada ação real sobre uma devolução.

Crie uma chave nova no Loop admin → Returns Management → Tools & integrations → Developer Tools, desta vez incluindo o scope returns, substitua a api_key salva por ela e tente novamente a ação de sinalizar ou processar na mesma devolução.

A conexão está ativa, mas nenhuma devolução chega

Nesta conexão, as devoluções só chegam de um jeito: por webhook, no momento em que um comprador cria uma devolução na Loop. Não há extração por API por trás, então uma conexão ativa sem devoluções novas na Loop mostrará corretamente nada de novo, e devoluções criadas antes da ativação não são trazidas depois.

Inicie uma devolução real na Loop e espere por ela aqui e em Runs / Logs. Se ela chegar, a conexão está funcionando e o período calmo anterior simplesmente não tinha devoluções novas. Se nunca chegar, confirme que a conexão está ativada com a chave correta salva e verifique Runs / Logs daquele período.

Os compradores perguntam onde está a etiqueta de devolução

Esta conexão não fornece etiquetas de devolução de jeito nenhum. Ela recebe devoluções e envia as ações de sinalizar e processar; a etiqueta que um comprador imprime vem da própria Loop, pelo arranjo de etiquetas que você já tem na Loop.

Mantenha o fluxo de etiquetas do comprador dentro da Loop e verifique ali suas configurações de etiquetas da Loop. Use esta conexão para o que ela faz: receber a devolução aqui para que o armazém possa sinalizá-la e processá-la.

Qual chave devo usar se eu tiver várias API keys da Loop?

Só uma chave serve para esta conexão: uma chave criada em Returns Management → Tools & integrations → Developer Tools com o scope returns. Chaves criadas para outros fins, ou sem esse scope, preencherão o campo, mas as ações de sinalizar e processar devoluções não funcionarão com elas.

Escolha a chave com o scope returns, ou crie uma nova seguindo os passos de credenciais acima, cole completa em api_key e salve. Há um único campo, então não há um segundo lugar onde uma chave errada possa se esconder.