Conectar o ReturnGO: trazer RMAs por API, com etiquetas de devolução

Gere uma API key no dashboard do ReturnGO em Settings → API, copie a URL do servidor de API da seção Servers da documentação oficial da API, preencha a chave, o domínio da loja e a URL do servidor no Integration, passe num teste real somente leitura e ative.

O conector do ReturnGO traz devoluções (RMAs) do ReturnGO para o sistema de devoluções (RMS) pela API do ReturnGO: ele lê a lista de RMAs e os detalhes de cada RMA, e esta conexão admite etiquetas de devolução. Funciona por extração por API segundo uma programação: não há webhook nesta conexão, então uma devolução nova no ReturnGO aparece aqui na próxima extração, não no instante em que é criada. A conexão tem quatro campos: uma API key, o domínio da sua loja, a URL do servidor de API que você copia da documentação oficial da API e um nome de cabeçalho opcional.

Pré-requisitos#

• Uma conta do ReturnGO à qual você consiga entrar, com acesso à página Settings → API do dashboard.
• Você conhece o domínio da loja registrado no ReturnGO para a loja que está conectando: um domínio como demo-store.myshopify.com, não o nome de exibição da loja que os compradores veem.
• Você consegue abrir a documentação oficial da API do ReturnGO e encontrar a seção Servers: a URL do servidor de API desta conexão é copiada por você dali; não há um padrão integrado para recorrer.
• Uma API key do ReturnGO pode gerenciar várias lojas, então controle qual loja corresponde a cada conexão: o campo de domínio da loja é o que diz a esta conexão de qual loja ela está extraindo.

Obter credenciais#

1. Entre no dashboard do ReturnGO e abra Settings → API.
2. Gere ali uma API key e copie completa. Uma chave pode gerenciar várias lojas, então a mesma chave pode ser usada para mais de uma conexão de loja.
3. Anote o domínio da loja exatamente como registrado no ReturnGO, por exemplo demo-store.myshopify.com. Durante as solicitações, este valor é enviado no cabeçalho x-shop-name, então copie o domínio em si, não um nome de exibição.
4. Abra a documentação oficial da API do ReturnGO, encontre a seção Servers e copie o endereço do servidor de API exibido ali. Este endereço é obrigatório e tem que vir dessa seção: não adivinhe um nem reutilize um endereço de outro documento.
5. Somente se o ReturnGO tiver dado a você um nome de cabeçalho de API key diferente durante a integração, anote esse nome também. Na maioria dos casos, o nome do cabeçalho é x-api-key e não há mais nada para coletar.

Preencher no Integration#

1. Abra Integration → Marketplace → ReturnGO → Nova conexão.
2. api_key, obrigatório, ReturnGO API Key: cole a chave gerada no ReturnGO dashboard → Settings → API, completa. É um campo do tipo senha e é guardado como segredo.
3. shop_name, obrigatório, domínio da loja: preencha o domínio da loja registrado no ReturnGO, por exemplo demo-store.myshopify.com. Preencha o domínio em si, não o nome de exibição da loja: as solicitações levam este valor no cabeçalho x-shop-name.
4. base_url, obrigatório, URL do servidor de API: cole o endereço do servidor de API copiado da seção Servers da documentação oficial da API do ReturnGO, na forma https://… exatamente como exibido ali. Este campo não tem padrão: se ficar vazio, o teste para antes de enviar qualquer coisa.
5. api_key_header, opcional, nome do cabeçalho da API key: deixe como x-api-key no caso normal. Preencha apenas quando o ReturnGO tiver dado a você um nome de cabeçalho diferente durante a integração, e então preencha esse nome exatamente.

Testar a conexão#

Clique em Testar a conexão. Com as credenciais preenchidas, o teste executa uma sondagem real somente leitura: envia GET {base_url}/rmas?pagesize=1 para o endereço do servidor de API que você preencheu, levando sua API key no cabeçalho (x-api-key por padrão, ou o nome de cabeçalho que você preencheu) e seu domínio de loja no cabeçalho x-shop-name, e permite 12 segundos para a resposta. Uma resposta bem-sucedida, a mensagem de sondagem bem-sucedida para GET /rmas, conta como aprovado, porque a sondagem prova que o endereço do servidor responde, que a chave é aceita e que o domínio da loja é reconhecido, sem alterar nada. Se base_url estiver ausente, o teste para com MISSING_BASE_URL e não envia nenhuma solicitação; se a chave ou o domínio da loja estiver ausente, ele falha abertamente pela credencial que falta em vez de informar uma aprovação falsa. Se testar sem preencher nenhuma credencial, o resultado é apenas uma verificação simulada e vem rotulado como simulado: preencha os três campos obrigatórios e teste novamente para a sondagem real.

Mapping / escolher modelo#

Escolha o mapping padrão do ReturnGO. Ele trabalha com o que a API retorna: a lista de RMAs e os detalhes de cada RMA viram registros de devolução aqui, e uma extração pode ser estreitada por número do pedido quando você procura uma devolução. Depois que o teste aprovar, execute uma extração e compare um RMA real lado a lado com o ReturnGO (referência do RMA, referência do pedido, itens e quantidades) e confira o fluxo de etiqueta de devolução desse retorno, antes de ativar. Se um campo do ReturnGO diferir do que você espera, ajuste esse campo no mapping em vez de mudar algo no ReturnGO.

Ativar#

Após ativar, a conexão traz RMAs do ReturnGO para o sistema de devoluções na frequência definida, lista e detalhes juntos, e o armazém trabalha aqui sobre essas devoluções, com etiquetas de devolução admitidas por esta conexão. Acompanhe as primeiras extrações em Runs / Logs e compare com o ReturnGO antes de deixar a conexão sem supervisão.

O que esta conexão não faz: não recebe devoluções por webhook, então uma devolução criada no ReturnGO não é enviada para cá no instante em que acontece: ela chega na próxima extração programada. Se uma devolução for urgente, execute uma extração manual para ela, estreitada pelo número do pedido, em vez de esperar pela programação.

Perguntas frequentes#

O teste para com MISSING_BASE_URL

O campo base_url está vazio. Esta conexão não tem um endereço de servidor integrado: a sondagem precisa da URL do servidor de API para saber para onde enviar GET /rmas, então sem endereço ela para antes de enviar qualquer solicitação e informa MISSING_BASE_URL.

Abra a documentação oficial da API do ReturnGO, copie o endereço do servidor da seção Servers exatamente como exibido, cole em base_url na forma https://…, salve e teste novamente.

A sondagem falha mesmo com a API key correta

A sondagem verifica mais do que a chave: ela também envia seu domínio de loja no cabeçalho x-shop-name e se comunica com o endereço em base_url. A causa habitual é shop_name: ele contém um nome de exibição da loja em vez do domínio registrado, então o ReturnGO não reconhece a loja mesmo que a chave em si seja válida. Uma base_url copiada do lugar errado falha do mesmo jeito.

Defina shop_name para o domínio registrado no ReturnGO, na forma demo-store.myshopify.com, e copie novamente base_url da seção Servers da documentação oficial da API. Mantenha a chave como está, salve e teste novamente.

Devo preencher api_key_header?

Na maioria dos casos, não. O cabeçalho que leva sua API key é x-api-key por padrão, e esse padrão já é o que a conexão usa. O campo existe apenas para lojas às quais o ReturnGO deu um nome de cabeçalho diferente durante a integração: preencher um nome inventado, ou mudá-lo sem orientação, faz uma chave que funciona parecer quebrada.

Deixe api_key_header como x-api-key, a menos que o ReturnGO tenha dado a você um nome diferente por escrito durante a integração. Se deu, preencha esse nome exato; se você o mudou ao investigar o problema, volte para x-api-key e teste novamente.

O teste aprovou sem credenciais preenchidas: estou conectado?

Não. Sem nenhuma credencial, o teste executa apenas uma verificação simulada e rotula o resultado como simulado. Ele nunca chega ao ReturnGO, então não prova nada sobre sua chave, seu domínio de loja ou seu endereço de servidor.

Preencha os três campos obrigatórios (api_key de Settings → API, shop_name como o domínio registrado e base_url copiada da seção Servers da documentação oficial da API), salve e teste novamente. Só o resultado da sondagem GET /rmas conta como aprovação real.

Conectado, mas uma devolução nova no ReturnGO não aparece aqui

Esta conexão extrai por API segundo uma programação e não tem webhook, então uma devolução criada há um minuto espera corretamente pela próxima extração. A outra causa comum é a loja: uma API key pode gerenciar várias lojas e esta conexão só extrai a loja nomeada pelo seu domínio shop_name; uma devolução criada em outra loja sob a mesma chave não aparecerá aqui.

Confirme que a devolução pertence à loja cujo domínio está em shop_name, execute uma extração manual, estreitada pelo número do pedido se você procura aquela devolução, e verifique Runs / Logs. Se ela chegar na extração manual, a conexão está bem e a extração programada trará as próximas.

A sondagem esgota o tempo sem resposta

A sondagem espera 12 segundos para o servidor em base_url responder a GET /rmas e nada voltou nesse tempo. Isso aponta para o próprio endereço: uma URL de servidor copiada da seção errada, digitada com uma parte faltando ou sobrando, ou de um ambiente diferente do que sua loja usa, não responderá a esta sondagem de loja.

Copie novamente base_url da seção Servers da documentação oficial da API do ReturnGO, cole exatamente como exibido, sem adicionar nem remover nada, salve e teste novamente. Não mude a chave nem o domínio da loja enquanto corrige o endereço: mude um valor de cada vez.