Conectar ReturnGO: traer RMAs por API, con etiquetas de devolución
Genere una API key en el dashboard de ReturnGO en Settings → API, copie la URL del servidor API desde la sección Servers de la documentación oficial de la API, complete la clave, el dominio de la tienda y la URL del servidor en Integration, supere una prueba real de solo lectura y active.
El conector de ReturnGO trae devoluciones (RMAs) de ReturnGO al sistema de devoluciones (RMS) a través de la API de ReturnGO: lee la lista de RMAs y los detalles de cada RMA, y esta conexión admite etiquetas de devolución. Funciona por extracción por API según un programa: no hay webhook en esta conexión, así que una devolución nueva en ReturnGO aparece aquí en la siguiente extracción, no en el instante en que se crea. La conexión tiene cuatro campos: una API key, el dominio de su tienda, la URL del servidor API que copia de la documentación oficial de la API y un nombre de encabezado opcional.
Requisitos previos#
- Una cuenta de ReturnGO a la que pueda acceder, con acceso a la página Settings → API del dashboard.
- Conoce el dominio de la tienda registrado en ReturnGO para la tienda que conecta: un dominio como demo-store.myshopify.com, no el nombre visible de la tienda que ven los compradores.
- Puede abrir la documentación oficial de la API de ReturnGO y encontrar la sección Servers: la URL del servidor API de esta conexión la copia usted desde allí; no hay un valor predeterminado integrado al que recurrir.
- Una API key de ReturnGO puede gestionar varias tiendas, así que lleve la cuenta de qué tienda corresponde a cada conexión: el campo de dominio de la tienda es lo que le dice a esta conexión de qué tienda está extrayendo.
Obtener credenciales#
- Inicie sesión en el dashboard de ReturnGO y abra Settings → API.
- Genere allí una API key y cópiela completa. Una clave puede gestionar varias tiendas, así que la misma clave puede usarse para más de una conexión de tienda.
- Anote el dominio de la tienda exactamente como está registrado en ReturnGO, por ejemplo demo-store.myshopify.com. Durante las solicitudes, este valor se envía en el encabezado x-shop-name, así que copie el dominio en sí, no un nombre visible.
- Abra la documentación oficial de la API de ReturnGO, encuentre la sección Servers y copie la dirección del servidor API que se muestra allí. Esta dirección es obligatoria y tiene que venir de esa sección: no adivine una ni reutilice una dirección de otro documento.
- Solo si ReturnGO le dio un nombre de encabezado de API key diferente durante la integración, anote también ese nombre. En la mayoría de los casos, el nombre del encabezado es x-api-key y no hay nada más que recoger.
Completar en Integration#
- Abra Integration → Marketplace → ReturnGO → Nueva conexión.
- api_key, obligatorio, ReturnGO API Key: pegue la clave generada en ReturnGO dashboard → Settings → API, completa. Es un campo de tipo contraseña y se guarda como secreto.
- shop_name, obligatorio, dominio de la tienda: complete el dominio de la tienda registrado en ReturnGO, por ejemplo demo-store.myshopify.com. Complete el dominio en sí, no el nombre visible de la tienda: las solicitudes llevan este valor en el encabezado x-shop-name.
- base_url, obligatorio, URL del servidor API: pegue la dirección del servidor API copiada de la sección Servers de la documentación oficial de la API de ReturnGO, en la forma https://… exactamente como se muestra allí. Este campo no tiene valor predeterminado: si se deja vacío, la prueba se detiene antes de enviar nada.
- api_key_header, opcional, nombre del encabezado de la API key: déjelo como x-api-key en el caso normal. Complételo solo cuando ReturnGO le haya dado un nombre de encabezado diferente durante la integración, y entonces complete ese nombre exactamente.
Probar la conexión#
Haga clic en Probar la conexión. Con las credenciales completadas, la prueba ejecuta una sonda real de solo lectura: envía GET {base_url}/rmas?pagesize=1 a la dirección del servidor API que completó, llevando su API key en su encabezado (x-api-key por defecto, o el nombre de encabezado que completó) y su dominio de tienda en el encabezado x-shop-name, y permite 12 segundos para la respuesta. Una respuesta correcta, el mensaje de sonda correcta para GET /rmas, cuenta como aprobada, porque la sonda prueba que la dirección del servidor responde, que la clave se acepta y que el dominio de la tienda se reconoce, sin cambiar nada. Si falta base_url, la prueba se detiene con MISSING_BASE_URL y no envía ninguna solicitud; si falta la clave o el dominio de la tienda, falla abiertamente por la credencial que falta en lugar de informar un aprobado falso. Si prueba sin completar ninguna credencial, el resultado es solo una comprobación simulada y viene etiquetado como simulado: complete los tres campos obligatorios y pruebe de nuevo para la sonda real.
Mapping / elegir plantilla#
Elija el mapping estándar de ReturnGO. Trabaja con lo que devuelve la API: la lista de RMAs y los detalles de cada RMA se convierten en registros de devolución aquí, y una extracción puede acotarse por número de pedido cuando busca una devolución. Tras aprobar la prueba, ejecute una extracción y compare un RMA real lado a lado con ReturnGO (referencia de RMA, referencia de pedido, artículos y cantidades) y revise el flujo de etiqueta de devolución de ese retorno, antes de activar. Si un campo de ReturnGO difiere de lo que espera, ajuste ese campo en el mapping en lugar de cambiar nada en ReturnGO.
Activar#
Tras activar, la conexión trae RMAs de ReturnGO al sistema de devoluciones según la frecuencia definida, lista y detalles juntos, y el almacén trabaja aquí sobre esas devoluciones, con etiquetas de devolución admitidas por esta conexión. Vigile las primeras extracciones en Runs / Logs y compárelas con ReturnGO antes de dejar la conexión sin supervisión.
Lo que esta conexión no hace: no recibe devoluciones por webhook, así que una devolución creada en ReturnGO no se envía aquí en el instante en que ocurre: llega en la siguiente extracción programada. Si una devolución es urgente, ejecute una extracción manual para ella, acotada por su número de pedido, en lugar de esperar al programa.
Preguntas frecuentes#
La prueba se detiene con MISSING_BASE_URL
El campo base_url está vacío. Esta conexión no tiene una dirección de servidor integrada: la sonda necesita la URL del servidor API para saber dónde enviar GET /rmas, así que sin dirección se detiene antes de enviar ninguna solicitud e informa MISSING_BASE_URL.
Abra la documentación oficial de la API de ReturnGO, copie la dirección del servidor desde la sección Servers exactamente como se muestra, péguela en base_url en la forma https://…, guarde y pruebe de nuevo.
La sonda falla aunque la API key es correcta
La sonda comprueba más que la clave: también envía su dominio de tienda en el encabezado x-shop-name y se comunica con la dirección de base_url. La causa habitual es shop_name: contiene un nombre visible de la tienda en lugar del dominio registrado, así que ReturnGO no reconoce la tienda aunque la clave en sí sea válida. Una base_url copiada del lugar equivocado falla de la misma manera.
Ponga shop_name en el dominio registrado en ReturnGO, en la forma demo-store.myshopify.com, y vuelva a copiar base_url desde la sección Servers de la documentación oficial de la API. Mantenga la clave como está, guarde y pruebe de nuevo.
¿Debo completar api_key_header?
En la mayoría de los casos, no. El encabezado que lleva su API key es x-api-key por defecto, y ese valor ya es el que usa la conexión. El campo existe solo para tiendas a las que ReturnGO dio un nombre de encabezado diferente durante la integración: completar un nombre inventado, o cambiarlo sin que se lo indiquen, hace que una clave que funciona parezca rota.
Deje api_key_header como x-api-key, salvo que ReturnGO le haya dado un nombre diferente por escrito durante la integración. Si lo hizo, complete ese nombre exacto; si lo cambió mientras buscaba el problema, vuelva a ponerlo en x-api-key y pruebe de nuevo.
La prueba aprobó sin credenciales completadas: ¿estoy conectado?
No. Sin ninguna credencial, la prueba ejecuta solo una comprobación simulada y etiqueta el resultado como simulado. Nunca llega a ReturnGO, así que no prueba nada sobre su clave, su dominio de tienda ni su dirección de servidor.
Complete los tres campos obligatorios (api_key desde Settings → API, shop_name como el dominio registrado y base_url copiada de la sección Servers de la documentación oficial de la API), guarde y pruebe de nuevo. Solo el resultado de la sonda GET /rmas cuenta como un aprobado real.
Conectado, pero una devolución nueva en ReturnGO no aparece aquí
Esta conexión extrae por API según un programa y no tiene webhook, así que una devolución creada hace un minuto espera correctamente a la siguiente extracción. La otra causa común es la tienda: una API key puede gestionar varias tiendas y esta conexión solo extrae la tienda nombrada por su dominio shop_name; una devolución creada en otra tienda bajo la misma clave no aparecerá aquí.
Confirme que la devolución pertenece a la tienda cuyo dominio está en shop_name, ejecute una extracción manual, acotada por el número de pedido si busca esa devolución, y revise Runs / Logs. Si llega con la extracción manual, la conexión está bien y la extracción programada traerá las siguientes.
La sonda agota el tiempo sin respuesta
La sonda espera 12 segundos a que el servidor de base_url responda a GET /rmas y en ese tiempo no volvió nada. Eso apunta a la propia dirección: una URL de servidor copiada de la sección equivocada, escrita con una parte de más o de menos, o de un entorno distinto al que usa su tienda, no responderá a esta sonda de tienda.
Vuelva a copiar base_url desde la sección Servers de la documentación oficial de la API de ReturnGO, péguela exactamente como se muestra, sin añadir ni quitar nada, guarde y pruebe de nuevo. No cambie la clave ni el dominio de la tienda mientras corrige la dirección: cambie un valor cada vez.