Cómo crear y solicitar la app pública de Shopify

Procedimiento operativo para TimeLiber Commerce. La app actual TimeLiber Connect es Custom distribution y queda reservada a DEV/piloto. Este procedimiento crea una app de producción separada.

0. Qué puede hacer el equipo y qué debes hacer tú

El repositorio puede preparar el código, TOML, webhooks, secretos montados, pruebas, listing copy, screencast y documentación. El propietario de la cuenta de Shopify debe ejecutar en el Dev Dashboard los clics que crean la app, seleccionan distribución y envían la revisión. Esas acciones generan credenciales y compromisos externos; no se automatizan desde el servidor.

Nunca envíes client secrets, refresh tokens, connection codes o credenciales de reviewer por chat, git, capturas, tickets o logs.

1. Requisitos previos

Antes de crear la app pública, deben existir:

dominio HTTPS estable: https://commerce.timeliber.com.co;
aplicación incrustada operativa en /app;
API GraphQL Admin y scopes mínimos (read_orders para el MVP);
almacenamiento cifrado de sesiones offline en el conector;
app/uninstalled, app/scopes_update y los tres webhooks de privacidad;
páginas legales accesibles: /privacy, /terms, /support;
email de contacto de API y contacto de emergencia;
icono PNG/JPG de 1200×1200 px, máximo 1 MB;
cuenta/tienda de revisión y screencast reproducible.

La checklist normativa y las decisiones de arquitectura están en Shopify App Integration Standard.

2. Crear la app de producción en Dev Dashboard

Abre Shopify Dev Dashboard → Apps → Create app.
Selecciona Start from Dev Dashboard.
Usa el nombre final de marca de producción. Debe ser distintivo y no iniciar con “Shopify”. Si el nombre TimeLiber Connect no está disponible, detén el proceso y decide el nombre legal/comercial; no improvises uno en el listing.
Crea la app y entra en Versions → New version.
Configura:

Campo	Valor esperado
App URL	`https://commerce.timeliber.com.co/app`
Embedded	`true`
Redirect URL	`https://commerce.timeliber.com.co/auth/callback`
API version	la versión soportada por el release validado
Required scopes	`read_orders`
Optional scopes	vacío hasta justificar una capacidad concreta

Guarda la versión, pero no copies el secreto a ningún documento.

3. Seleccionar Public distribution

En la app nueva abre Distribution → Choose distribution.
Selecciona Public distribution.
Confirma la decisión sólo después de verificar que no estás dentro de la app Custom de DEV. Shopify no permite cambiar el método después.
Crea el listing y selecciona Limit visibility para el primer lanzamiento público controlado. La visibilidad limitada sigue requiriendo revisión, pero no aparece en búsquedas/categorías.

No uses el enlace install_custom_app de la app DEV para comerciantes externos. El botón de Commerce debe apuntar al listing oficial de la app pública; Shopify se ocupa del login, selector de tienda y permisos.

4. Configurar webhooks

Un webhook es una notificación HTTP que Shopify envía cuando sucede un evento. No es un permiso ni un token: es un contrato de entrega para que el sistema reaccione sin preguntar continuamente a Shopify.

Tema	URL	Para qué sirve	Respuesta mínima
`app/uninstalled`	`/webhooks/app/uninstalled`	Revocar/invalidar sesión y marcar tienda desinstalada	`2xx` tras encolar trabajo
`app/scopes_update`	`/webhooks/app/scopes_update`	Registrar permisos concedidos/revocados	`2xx`
`customers/data_request`	`/webhooks/customers/data_request`	Solicitud de datos de una persona	`2xx`, ejecutar dentro del plazo legal
`customers/redact`	`/webhooks/customers/redact`	Borrado de datos de cliente	`2xx`, ejecutar redacción
`shop/redact`	`/webhooks/shop/redact`	Borrado de datos de la tienda tras desinstalación	`2xx`, ejecutar redacción

Reglas para cada endpoint:

Leer los bytes originales y verificar X-Shopify-Hmac-Sha256 antes de interpretar el JSON.
Responder 401 si la firma es inválida.
Deduplicar usando X-Shopify-Webhook-Id; Shopify puede reintentar.
No asumir orden de eventos.
Responder rápido y delegar el trabajo durable a un job idempotente.
No incluir payload, firma, tokens o PII en logs.
Probar una entrega real y una firma inválida; el CLI trigger por sí solo no demuestra que la suscripción esté registrada.

Shopify reintenta entregas fallidas y puede eliminar una suscripción persistente; por eso el panel de Monitoring y una reconciliación periódica son obligatorios.

5. URLs que deben registrarse

Tipo	URL	Quién la usa
App URL	`https://commerce.timeliber.com.co/app`	Shopify abre App Home aquí
Auth callback	`https://commerce.timeliber.com.co/auth/callback`	SDK de Shopify en flujos de autenticación
Uninstall	`https://commerce.timeliber.com.co/webhooks/app/uninstalled`	Shopify lifecycle
Scopes update	`https://commerce.timeliber.com.co/webhooks/app/scopes_update`	Shopify lifecycle
Privacy data request	`https://commerce.timeliber.com.co/webhooks/customers/data_request`	Shopify privacidad
Privacy customer redact	`https://commerce.timeliber.com.co/webhooks/customers/redact`	Shopify privacidad
Privacy shop redact	`https://commerce.timeliber.com.co/webhooks/shop/redact`	Shopify privacidad
Privacy policy	`https://commerce.timeliber.com.co/privacy`	Listing y pantalla de permisos
Terms of service	`https://commerce.timeliber.com.co/terms`	Listing/contrato TimeLiber
Support	`https://commerce.timeliber.com.co/support`	Merchant y reviewer

No se debe registrar una URL de Cloudflare Tunnel, localhost, IP desnuda, example.com ni un dominio con “Shopify” en el nombre. Todas las URLs públicas deben responder por HTTPS válido antes de enviar.

6. Credenciales y despliegue

Después de crear la app, Shopify muestra un nuevo client ID y client secret.

Guarda el secret en el gestor de secretos del host, con archivo montado sólo al conector.
Genera una clave de cifrado de session store exclusiva para producción.
Usa una base de sesiones exclusiva para la app pública.
Actualiza el client_id de la configuración de producción; no reemplaces el secreto DEV ni mezcles sesiones.
Ejecuta el preflight de secretos sin imprimir valores.
Despliega con shopify app deploy/release de versión y reinicia el conector.
Comprueba /shopify/health, App Home y logs sanitizados.

El navegador nunca recibe el client secret, access token ni refresh token.

7. Protected Customer Data nivel 1

Aunque el MVP no muestra nombre, email, teléfono ni dirección, los pedidos están relacionados con clientes. En la app pública abre API access requests → Protected customer data access, solicita nivel 1 y declara exactamente:

identificadores de pedido;
fechas/estados financieros y de fulfillment;
totales y moneda;
líneas compradas, SKU, cantidades y precios.

No selecciones Name, Address, Email o Phone hasta tener una función, política, tests y justificación de nivel 2.

8. Listing y App Review

El listing debe explicar hechos verificables, no promesas de IA o inventario. Debe incluir:

beneficio y función principal;
permisos y datos procesados;
precio real o “gratis” si aún no hay cobro;
privacidad, términos y soporte;
capturas sin datos reales ni secretos;
screencast del recorrido completo en inglés o con subtítulos en inglés;
instrucciones y credenciales funcionales del reviewer en el formulario privado.

Antes de pulsar Submit for review:

Instala desde el listing en una Development Store.
Verifica login Shopify, selección de tienda y permisos.
Comprueba que App Home autentica inmediatamente y no solicita dominio.
Crea/vincula la cuenta TimeLiber sin un código manual de producción.
Abre Pedidos y concilia contra Shopify.
Prueba reinstall, uninstall, scopes update y redacciones.
Ejecuta todos los automated checks de Shopify.
Confirma que no hay 3xx/4xx/5xx inesperados ni secretos en logs.

El envío es una acción del propietario de Partner/Dev Dashboard. Si Shopify devuelve observaciones, se corrigen en una nueva versión y se vuelven a ejecutar los checks; no se ocultan errores con una página de bienvenida.

9. Flujo que verá el comerciante

Commerce: Conectar Shopify
  → listing oficial Shopify
  → login/selector de tienda Shopify
  → permisos y política
  → Instalar
  → TimeLiber Connect incrustada
  → alta automática o vincular cuenta existente
  → App Home y Commerce muestran Conectada

En producción no aparece un campo para escribir la tienda, un código copiable ni una segunda contraseña obligatoria. La configuración básica de conexión permanece en App Home, como exige Shopify para integraciones de terceros.

10. Evidencia que debe archivarse

En el informe de release, no en secretos ni datos personales:

client ID público y versión desplegada;
fecha de instalación/reinstalación en tienda de prueba;
resultados de automated checks;
respuestas HTTP sanitizadas de App Home y webhooks;
captura del permiso read_orders sin PII;
pedido de prueba conciliado;
resultado de uninstall/redaction;
enlace al listing y al screencast;
responsable y fecha de cada aprobación.