Descripción general
Esta documentación describe cómo registrar y configurar una Shopify Public App en el Shopify Dev Dashboard e integrarla en AdlerDo V6.1 para la instalación mediante OAuth. El proceso genera un Client ID y un Client Secret que AdlerDo utiliza para autenticarse frente a cualquier tienda de Shopify que instale la aplicación.
Contexto de la arquitectura
AdlerDo expone /api/shopify/install como punto de entrada de OAuth. La aplicación del Dev Dashboard redirige cada solicitud de instalación a este endpoint, que realiza el intercambio del código OAuth, persiste el token de acceso en la base de datos del inquilino (tenant) y registra los webhooks necesarios mediante trabajos en segundo plano de Hangfire.
Requisitos previos
Antes de empezar, asegúrate de lo siguiente:
- Acceso a la organización de Shopify de TecSee GmbH con permiso para gestionar aplicaciones
- Middleware de AdlerDo desplegado y accesible por HTTPS en el host público configurado para el entorno de destino
- Los endpoints
/api/shopify/install y /api/shopify/callback son accesibles y devuelven respuestas válidas
- Hay disponible una tienda de desarrollo para pruebas de extremo a extremo antes de promocionar las credenciales a producción
- La lista de ámbitos (scopes) de OAuth que requiere AdlerDo se ha finalizado y almacenado en la configuración
Paso 1 — Abre la página de desarrollo de aplicaciones
Inicia sesión en la organización de Shopify y navega a Settings → Apps and sales channels → App development. Haz clic en el botón "Build apps in Dev Dashboard".
Importante: NO uses el botón "Create an app" del panel de Legacy custom apps. Las aplicaciones personalizadas heredadas (legacy) dejarán de funcionar para los nuevos comerciantes el 1 de enero de 2026.
Paso 2 — Crea una nueva aplicación en el Dev Dashboard
El Dev Dashboard se abre en dev.shopify.com/dashboard/{organizationId}/apps. Haz clic en el botón "Create app" en la esquina superior derecha de la lista de aplicaciones.
Paso 3 — Elige una ruta de creación y establece el nombre de la aplicación
Se ofrecen dos rutas de creación:
- Start with Shopify CLI — genera la estructura de un proyecto Node/Remix de forma local. AdlerDo no necesita esta ruta.
- Start from Dev Dashboard — registra los metadatos de la aplicación directamente en el dashboard y genera de inmediato un Client ID y un Secret. Usa esta ruta para AdlerDo.
Introduce el nombre de la aplicación (por ejemplo: AdlerDo) y haz clic en Create.
Convención de nomenclatura
Usa un nombre estable y visible para el cliente que se muestre en la pantalla de consentimiento de instalación. Para TecSee, añade un prefijo por entorno si es necesario: AdlerDo (Production), AdlerDo Staging, AdlerDo Dev.
Paso 4 — Configura las URL, la versión de los webhooks y los ámbitos
Tras la creación, la aplicación se abre en la pestaña Versions con una nueva versión de borrador. Aquí es donde se definen la URL de instalación, la versión de la API de webhooks y los ámbitos.
6.1 App URL
Establece App URL en el endpoint público de instalación de AdlerDo:
https://whlvm133440.wawihost.de/api/shopify/install
Esta URL es a la que Shopify redirige cuando un comerciante instala la aplicación. El ShopifyInstallController de AdlerDo lee los parámetros de consulta shop y hmac, valida el HMAC y redirige a la página de concesión de OAuth de Shopify.
6.2 Embed app in Shopify admin
Deja activada la casilla "Embed app in Shopify admin". AdlerDo sirve una interfaz de administración embebida dentro del marco de administración de Shopify usando App Bridge.
6.3 Preferences URL
Opcional. Déjalo vacío a menos que la aplicación exponga una página de configuración independiente fuera de la experiencia embebida.
6.4 Versión de la API de webhooks
Fija la versión de la API de webhooks de forma explícita. El ejemplo muestra 2026-04, que es la versión que AdlerDo consume actualmente. Aumentar este valor requiere revisar cada mapeo de la carga útil (payload) de los webhooks.
6.5 Ámbitos de acceso
Haz clic en "Select scopes" y marca los ámbitos que requiere AdlerDo. Mantén la lista al mínimo que AdlerDo realmente utiliza: los comerciantes ven la lista completa en la pantalla de consentimiento de instalación.
La misma lista exacta también debe persistirse en la configuración de AdlerDo (appsettings.Shopify.json → Shopify:Scopes), ya que el controlador de instalación la pasa como parámetro de consulta scope. Una discrepancia forzará reinstalaciones.
Ámbitos opcionales frente a obligatorios
Los ámbitos opcionales pueden solicitarse en tiempo de ejecución tras la instalación. AdlerDo trata todos los ámbitos listados como obligatorios durante la instalación inicial, así que deja vacío el bloque de ámbitos opcionales.
6.6 Redirect URLs
Añade la URL de redirección de OAuth: la URL pública del callback de OAuth de AdlerDo:
https://whlvm133440.wawihost.de/api/shopify/callback
Añade una URL de redirección por entorno. Shopify rechaza el callback de OAuth si la URL proporcionada en el parámetro redirect_uri no está en esta lista blanca.
Paso 5 — Publica la versión
Después de guardar todos los campos, haz clic en Release en la parte inferior de la página de la versión.
- Version name — una etiqueta legible por humanos. Convención de TecSee:
alderdoo-{n}, donde n es el número de publicación autoincremental
- Version message — un breve registro de cambios (por ejemplo, "added read_locales scope", "bumped webhooks API to 2026-04")
Haz clic en Release. La nueva versión pasa a estar Active de inmediato y reemplaza a la versión Active anterior para todas las nuevas instalaciones.
Cambios de ámbito tras la publicación
Añadir un nuevo ámbito a una versión publicada NO lo concede automáticamente en las tiendas ya instaladas. El propietario de la tienda debe aprobar una reautorización. AdlerDo detecta la desviación de ámbitos (scope drift) en cada solicitud y activa una redirección de reinstalación cuando es necesario.
Paso 6 — Verifica la versión activa
Abre la pestaña Versions en la barra lateral izquierda. La versión publicada más recientemente está marcada con la insignia verde "Active". Todas las versiones anteriores permanecen visibles con fines de auditoría.
Desde esta vista puedes hacer clic en cualquier versión histórica para inspeccionar su configuración, lo que resulta útil al depurar una instalación en una tienda más antigua.
Paso 7 — Obtén el Client ID y el Secret
Abre la pestaña Settings en la barra lateral izquierda. El bloque Credentials en la parte superior expone el Client ID y el Secret.
9.1 Client ID
Identificador público. Es seguro incluirlo en la configuración. Cópialo con el icono del portapapeles y pégalo en la configuración de AdlerDo.
9.2 Client Secret
Sensible. Trátalo como una credencial. El secret solo se muestra una vez, al generarse por primera vez; después solo se muestra en su forma ofuscada. Usa el icono del ojo para revelarlo una vez y copiarlo, y luego almacénalo mediante la ruta estándar de almacenamiento de secretos de AdlerDo.
En AdlerDo, los secrets de las integraciones con marketplaces se persisten cifrados con AES-256 en la base de datos del inquilino a través de MarketplaceCredentialEncryptor.
9.3 Rotar el Secret
Haz clic en Rotate para generar un nuevo secret. El secret anterior queda invalidado de inmediato. Coordina la rotación con un despliegue del nuevo secret en AdlerDo.
9.4 Correo de contacto de la API
Establece este valor en un buzón supervisado (actualmente dev@tecsee.de). Shopify envía avisos de obsolescencia de la API y alertas de seguridad a esta dirección.
Conexión de las credenciales en AdlerDo
Una vez que tengas el Client ID y el Secret, añade las credenciales a la configuración de AdlerDo.
10.1 Configuración
Añade el siguiente bloque a la configuración específica del entorno:
"Shopify": {
"ClientId": "1d15c8413f636e7cfda6f4402d9ef552",
"ClientSecret": "<from Settings page>",
"Scopes": "read_products,write_products,read_orders,write_orders,…",
"WebhooksApiVersion": "2026-04",
"InstallRedirectUrl": "https://whlvm133440.wawihost.de/api/shopify/callback"
}
10.2 Flujo de instalación
El protocolo de instalación de extremo a extremo es:
- El comerciante hace clic en el enlace de instalación → Shopify redirige a App URL con los parámetros de consulta shop y hmac
/api/shopify/install de AdlerDo valida el HMAC frente al Client Secret y redirige a https://{shop}/admin/oauth/authorize con la lista de ámbitos configurada y un nonce de estado generado- El comerciante aprueba los ámbitos en la pantalla de consentimiento de Shopify
- Shopify redirige a
/api/shopify/callback con los parámetros code, hmac y state
- AdlerDo valida el HMAC y el nonce de estado, y luego envía por POST code + Client ID + Client Secret a
https://{shop}/admin/oauth/access_token para recibir el token de acceso offline
- El token se almacena cifrado con AES-256 asociado al inquilino; se registran las suscripciones de webhooks y los trabajos recurrentes de sincronización de Hangfire
- AdlerDo redirige al comerciante a la URL de administración embebida
10.3 Verificación de la instalación
Tras el protocolo de instalación:
- Confirma que existe una nueva entidad
ShopifyConnection en la base de datos del inquilino con un EncryptedAccessToken no nulo y la lista de ámbitos concedidos
- Confirma que los trabajos recurrentes (
SyncShopifyOrdersV2026, SyncShopifyProductsV2026) están registrados en Hangfire bajo el nuevo identificador de inquilino
- Activa un webhook de prueba desde la administración de Shopify y confirma que el handler de AdlerDo lo procesa sin errores de HMAC
Apéndice A — Ámbitos habituales usados por AdlerDo
| Ámbito |
Propósito en AdlerDo |
read_products, write_products |
Sincronización de catálogo: crear/actualizar productos y variantes desde Odoo o JTL-Wawi |
read_orders, write_orders |
Importar pedidos a AdlerDo y devolver ediciones de pedidos / cumplimientos (fulfillments) |
read_inventory, write_inventory |
Sincronización de niveles de stock por ubicación |
read_locations |
Resolver las ubicaciones de cumplimiento para inventario y envíos |
read_fulfillments, write_fulfillments |
Crear cumplimientos y enviar números de seguimiento desde transportistas: DHL, GLS, DPD, DB Schenker |
read_assigned_fulfillment_orders, write_assigned_fulfillment_orders |
Requerido cuando AdlerDo actúa como un servicio de cumplimiento registrado |
read_customers, write_customers |
Sincronización de clientes y segmentación B2B |
read_shipping |
Leer la configuración de transportistas y zonas para el cálculo de tarifas |
read_app_proxy, write_app_proxy |
Requerido para las rutas del proxy de administración embebido |
read_analytics |
Paneles de informes en la administración embebida |
Apéndice B — Resolución de problemas
La redirección de instalación devuelve 401 / HMAC no válido
Causa: El Client Secret de la configuración de AdlerDo no coincide con el secret de Settings, o el secret se rotó sin volver a desplegar.
Acción: Copia el secret desde la página Settings del Dev Dashboard y vuelve a desplegar.
El callback de OAuth devuelve 'redirect_uri is not whitelisted'
Causa: La URL de callback no está presente en el campo Redirect URLs de la versión activa.
Acción: Abre la versión activa, añade la URL, publica una nueva versión y vuelve a intentar la instalación.
La tienda se instala pero no aparecen trabajos de Hangfire
Causa: El intercambio del código OAuth se realizó correctamente, pero el arranque posterior a la instalación falló (por ejemplo, el aprovisionamiento del inquilino).
Acción: Inspecciona los registros de AdlerDo en torno a la marca temporal de la instalación; el ShopifyInstallController emite un registro Information por cada etapa y un registro Error con el paso que ha causado el problema.
Las entregas de webhooks fallan con errores de HMAC
Causa: AdlerDo calculó el HMAC del webhook sobre una carga útil analizada (parsed) en lugar del cuerpo sin procesar (raw).
Acción: Confirma que el middleware de solicitudes almacena en búfer el cuerpo de la solicitud sin procesar antes del enlace del modelo (model binding) para las rutas /api/shopify/webhooks/*.
El comerciante informa de datos faltantes tras añadir un ámbito
Causa: La tienda se instaló con una versión más antigua que no incluía el ámbito.
Acción: Activa una redirección de reinstalación: AdlerDo detecta la desviación de ámbitos en ShopifyConnectionMiddleware y redirige al endpoint de instalación, donde el comerciante aprueba el nuevo ámbito.
Deutsch
English
Polski
Čeština
Français
简体中文
