feat: public Shopify App (OAuth+webhooks+billing) + SEO + partners program

app/blog/posts.py

@@ -810,6 +810,110 @@ POSTS: list[Post] = [
             """<p>If you are looking for a Crisp alternative, you probably already have it and notice the same thing many small stores do: you pay for a huge suite and, in the end, you only use the chat. Crisp is a versatile, well-made tool; that is not in doubt. But for a one-person store, all those features can turn into a toolbox left half-assembled. Let us look at it honestly and without making up numbers, and then I will tell you where Atendyo fits and what you give up by switching.</p><h2>Why people look for a Crisp alternative</h2><p>The reasons that lead to looking for something different are usually these:</p><ul><li><strong>Too many features for what you need.</strong> Crisp brings a knowledge base, CRM, campaigns, bot flows, a team inbox. If you only want the AI to answer the repetitive stuff, you pay for modules you never open.</li><li><strong>It has to be set up.</strong> A broad suite pays off when someone configures it: writing the knowledge base, segmenting the CRM, preparing campaigns, defining flows. Whoever is flat out with their store rarely has that time, and the tool ends up half-done.</li><li><strong>Price grows with modules and seats.</strong> Its plans start affordable, but the real cost depends on what you switch on and how many people use it. Check their website for the exact price and limits, which change.</li></ul><p>If you really will use the CRM, the campaigns and the knowledge base, Crisp can be worth it. If not, read on.</p><h2>Atendyo as an alternative for small stores</h2><p>Atendyo goes the opposite way from a suite: instead of giving you many pieces to assemble, it does a few things well. It is an AI assistant focused on serving and selling, using your own store's information. What it offers:</p><ul><li><strong>Flat price of 29 EUR a month</strong>, no setup fee and no surprises from modules or seats. You have the details on the <a href="https://atendyo.com/#precio">pricing page</a>.</li><li><strong>AI trained on your store</strong> (your website, your PDFs, your catalog) that answers on its own from day one, without you building flows or configuring trees.</li><li><strong>Web and WhatsApp</strong> with the same assistant and the same information.</li><li><strong>50+ languages</strong> with automatic detection.</li><li><strong>Shopify catalog</strong> with live photo, price and stock inside the chat.</li><li><strong>Instant demo:</strong> paste your website and within a minute you chat with an assistant that already knows it.</li><li><strong>GDPR and EU-native.</strong></li></ul><h2>Be honest: what you give up switching from Crisp to Atendyo</h2><p>Moving from a suite to a focused tool has a cost, and it would be dishonest to hide it. If you come from Crisp, here is what you leave behind:</p><ul><li><strong>Public knowledge base.</strong> Crisp lets you build a help center with articles. Atendyo does not publish that center; it answers in the conversation with your information.</li><li><strong>CRM and campaigns.</strong> Crisp's segments, lightweight CRM and email or in-app campaigns are not Atendyo's terrain.</li><li><strong>Inbox for several agents and many channels.</strong> If you need a team working at once in a shared inbox across many channels, Crisp gives you more for that.</li></ul><p>Put plainly: if you are genuinely going to use the CRM, the campaigns and the knowledge base, do not switch expecting to find them in Atendyo. If you only use the chat and want the AI to answer on its own without half a day of setup, Atendyo fits better.</p><h2>The honest way to decide: try it with your store</h2><p>The key is being honest with yourself about how much of a suite you will actually use. Many small stores pay for everything and only touch the chat. To see whether the simple thing is enough, <a href="https://atendyo.com/demo">open the Atendyo demo with your own store</a>: paste your website address and within a minute you check whether it answers as you expect, no sign-up. If you then find you need all the extra pieces of a suite, then Crisp makes sense.</p>"""
         ),
     ),
+    Post(
+        slug="chatbot-para-shopify-en-espanol",
+        lang="es",
+        pair_slug="ai-chatbot-for-shopify",
+        title="Chatbot para Shopify en español: cómo poner uno que atiende y vende",
+        meta_description=(
+            "Pon un chatbot de IA en tu Shopify en español: se entrena con tu tienda, "
+            "responde envíos, stock y pedidos, web y WhatsApp, 29 EUR/mes."
+        ),
+        keywords=[
+            "chatbot para shopify",
+            "chatbot shopify español",
+            "chatbot ia shopify",
+            "asistente shopify",
+            "atencion al cliente shopify",
+        ],
+        date="2026-06-17",
+        excerpt=(
+            "Si tienes una tienda Shopify y quieres un chatbot de IA en español que "
+            "responda de verdad con la información de tu tienda, aquí tienes cómo "
+            "ponerlo, qué hace y qué no hace."
+        ),
+        body_html=(
+            """<p>La mayoría de los chatbots para Shopify están pensados en inglés y para tiendas grandes con un equipo de soporte detrás. Si tu tienda es pequeña y atiendes en español, eso se nota: la IA traduce regular, te obliga a montar flujos y, al final, no responde sola. Vamos a ver cómo poner un chatbot que SÍ funciona en español con tu Shopify, sin inventarnos nada y diciendo también qué cede.</p><h2>Por qué "en español" importa más de lo que parece</h2><p>Un cliente que pregunta "¿hacéis envíos a Canarias y cuánto tarda?" espera una respuesta natural, no una traducción rara. Un asistente pensado en español (y que detecta el idioma del cliente, sea catalán, gallego o cualquier otro) responde como lo haría una persona de tu tienda. Esa naturalidad es la diferencia entre que el cliente confíe y compre, o que se vaya.</p><h2>Cómo poner el chatbot en tu Shopify</h2><p>Con Atendyo hay dos caminos, los dos sencillos:</p><ul><li><strong>Pegando una línea de código</strong> en tu tema (antes de la etiqueta de cierre del body). El asistente aparece como una burbuja de chat en tu tienda.</li><li><strong>Conectando tu tienda Shopify</strong> para que además lea tu catálogo en vivo (foto, precio y stock reales) y el estado de los pedidos. Se conecta concediendo unos permisos de lectura; no toca nada de tu tienda.</li></ul><p>No tienes que programar ni montar árboles de decisión: la IA se entrena con tu propia web (productos, envíos, devoluciones) y responde sola desde el primer día.</p><h2>Qué responde dentro de tu Shopify</h2><ul><li><strong>Productos, precios y stock</strong> en vivo, mostrados como tarjetas con foto y botón de comprar.</li><li><strong>Estado de pedidos y seguimiento</strong> (pidiendo email + un dato para verificar).</li><li><strong>Zonas y tarifas de envío</strong> reales configuradas en tu Shopify (sí, incluye responder a Canarias).</li><li><strong>Envíos, devoluciones, tallas, compatibilidades</strong> y las dudas repetidas de siempre.</li><li>Y si no sabe algo, lo dice con sinceridad y recoge el contacto para que respondas tú.</li></ul><h2>Web y WhatsApp, el mismo asistente</h2><p>El mismo bot atiende en tu web y en tu WhatsApp con la misma información. Para una tienda pequeña eso es tener soporte 24/7 sin contratar a nadie.</p><h2>Seamos honestos: qué NO es</h2><p>Atendyo no es un helpdesk para un equipo grande con bandeja compartida y muchos agentes, ni un CRM, ni una herramienta de campañas. Hace pocas cosas y las hace bien: atender y vender con la info de tu tienda. Si necesitas todo lo de una suite grande, esto se te quedará corto.</p><h2>Pruébalo con tu propia tienda antes de instalar</h2><p>La mejor forma de decidir es verlo con tu tienda: <a href="https://atendyo.com/demo">abre la demo de Atendyo</a>, pega la dirección de tu web y en un minuto chateas con un asistente que ya la conoce, sin registrarte. Si te gusta cómo responde, lo activas 14 días gratis sin tarjeta. Tienes el precio (29 EUR/mes plano) en la <a href="https://atendyo.com/#precio">página de precios</a>.</p>"""
+        ),
+    ),
+    Post(
+        slug="ai-chatbot-for-shopify",
+        lang="en",
+        pair_slug="chatbot-para-shopify-en-espanol",
+        title="AI chatbot for Shopify: how to add one that answers and sells",
+        meta_description=(
+            "Add an AI chatbot to your Shopify: trained on your store, answers "
+            "shipping, stock and orders, web and WhatsApp, 29 EUR/mo. Easy install."
+        ),
+        keywords=[
+            "ai chatbot for shopify",
+            "shopify chatbot",
+            "shopify ai assistant",
+            "shopify customer support",
+            "chatbot shopify",
+        ],
+        date="2026-06-17",
+        excerpt=(
+            "If you run a Shopify store and want an AI chatbot that actually answers "
+            "with your store's own information, here is how to add one, what it does "
+            "and what it does not."
+        ),
+        body_html=(
+            """<p>Most Shopify chatbots are built for large stores with a support team behind them, and they make you build flows before they answer anything. If your store is small, you want the opposite: an assistant that answers on its own with your store's information, in your customer's language. Let us look at how to add one to Shopify, what it does and — honestly — what it does not.</p><h2>How to add the chatbot to your Shopify</h2><p>With Atendyo there are two simple paths:</p><ul><li><strong>Paste one line of code</strong> into your theme (just before the closing body tag). The assistant shows up as a chat bubble on your store.</li><li><strong>Connect your Shopify store</strong> so it also reads your live catalog (real photo, price and stock) and order status. You connect it by granting a few read-only permissions; it never changes anything in your store.</li></ul><p>No coding and no decision trees: the AI is trained on your own website (products, shipping, returns) and answers on its own from day one.</p><h2>What it answers inside Shopify</h2><ul><li><strong>Products, prices and stock</strong> live, shown as cards with a photo and a buy button.</li><li><strong>Order status and tracking</strong> (asking for email plus one detail to verify).</li><li><strong>Shipping zones and rates</strong> configured in your Shopify.</li><li><strong>Shipping, returns, sizes, compatibility</strong> and the repetitive questions.</li><li>And when it does not know something, it says so honestly and captures the contact so you reply.</li></ul><h2>Web and WhatsApp, one assistant</h2><p>The same bot serves your website and your WhatsApp with the same information — 24/7 support without hiring anyone.</p><h2>Being honest: what it is not</h2><p>Atendyo is not a helpdesk for a big team with a shared inbox and many agents, nor a CRM, nor a campaigns tool. It does a few things well: serving and selling with your store's information. If you need a full suite, this will fall short.</p><h2>Try it with your own store first</h2><p><a href="https://atendyo.com/demo">Open the Atendyo demo</a>, paste your website and within a minute you chat with an assistant that already knows it, no sign-up. If you like how it answers, activate a 14-day free trial with no card. Pricing (flat 29 EUR/mo) is on the <a href="https://atendyo.com/#precio">pricing page</a>.</p>"""
+        ),
+    ),
+    Post(
+        slug="alternativa-a-intercom-tienda-pequena",
+        lang="es",
+        pair_slug="intercom-alternative-small-store",
+        title="Alternativa a Intercom para tiendas pequeñas: Atendyo, en español y sin complicarte",
+        meta_description=(
+            "¿Intercom te queda grande y caro para tu tienda? Atendyo: IA entrenada con "
+            "tu web, español nativo, web y WhatsApp, 29 EUR/mes plano. Comparativa honesta."
+        ),
+        keywords=[
+            "alternativa a intercom",
+            "intercom alternativa español",
+            "intercom fin precio",
+            "alternativa intercom tienda pequena",
+            "chatbot atencion al cliente ecommerce",
+        ],
+        date="2026-06-17",
+        excerpt=(
+            "Si miras Intercom para tu tienda pequeña y te parece grande y caro, esta "
+            "es una comparativa honesta: qué ganas con una alternativa más simple en "
+            "español y qué cedes."
+        ),
+        body_html=(
+            """<p>Si has llegado buscando una alternativa a Intercom, seguramente lo has mirado y has visto dos cosas: es potentísimo, y está pensado (y con un precio pensado) para empresas con equipo de soporte. Para una tienda pequeña eso se traduce en pagar mucho por funciones que no vas a tocar. Vamos a ser honestos con ambas partes, sin inventarme cifras, y luego te cuento dónde encaja Atendyo y qué cedes si cambias.</p><h2>Por qué la gente busca una alternativa a Intercom</h2><ul><li><strong>El precio escala rápido.</strong> Intercom cobra por asiento y, su IA (Fin), por resolución/conversación resuelta. Para un volumen alto está bien; para una tienda pequeña, el coste se dispara y es difícil de prever. Mira su web para el precio exacto, que cambia.</li><li><strong>Es una plataforma enorme.</strong> Bandeja para equipos, CRM, campañas, product tours, flujos. Si solo quieres que la IA responda lo repetitivo, pagas por un montón de cosas que no abres.</li><li><strong>Hay que montarlo y está en inglés.</strong> Sacarle partido pide configurarlo, y el producto y muchos recursos están pensados en inglés. Para atender en español a una tienda pequeña, es desproporcionado.</li></ul><p>Si de verdad vas a usar la bandeja de equipo, el CRM y las campañas, Intercom es de lo mejor que hay. Si no, sigue leyendo.</p><h2>Atendyo como alternativa para tiendas pequeñas</h2><p>Atendyo va al revés que una plataforma enorme: hace pocas cosas y bien. Es un asistente de IA centrado en atender y vender con la información de tu propia tienda:</p><ul><li><strong>Precio plano de 29 EUR al mes</strong>, sin coste por resolución ni por asiento. Lo tienes en la <a href="https://atendyo.com/#precio">página de precios</a>.</li><li><strong>IA entrenada con tu tienda</strong> (tu web, tus PDFs, tu catálogo) que responde sola desde el primer día, sin montar flujos.</li><li><strong>Español nativo</strong> y detección automática de más de 50 idiomas.</li><li><strong>Web y WhatsApp</strong> con el mismo asistente y la misma información.</li><li><strong>Catálogo Shopify</strong> con foto, precio y stock en vivo dentro del chat.</li><li><strong>Demo instantánea</strong> y nativo de la UE (RGPD).</li></ul><h2>Seamos honestos: qué cedes al cambiar de Intercom a Atendyo</h2><ul><li><strong>Bandeja para equipos grandes.</strong> Si tienes varios agentes trabajando a la vez en una bandeja compartida con SLAs, Intercom te da mucho más para eso.</li><li><strong>CRM, campañas y product tours.</strong> No son el terreno de Atendyo.</li><li><strong>Ecosistema e integraciones enterprise.</strong> Intercom tiene un catálogo de integraciones enorme; Atendyo se centra en tienda online (Shopify) y WhatsApp.</li></ul><p>Dicho claro: si vas a usar de verdad la bandeja de equipo, el CRM y las campañas, no cambies esperando encontrarlas en Atendyo. Si solo quieres que la IA atienda sola, en español, sin medio día de configuración y a precio fijo, Atendyo encaja mejor.</p><h2>La forma honesta de decidir: pruébalo con tu tienda</h2><p><a href="https://atendyo.com/demo">Abre la demo de Atendyo con tu propia tienda</a>: pega la dirección de tu web y en un minuto compruebas si responde como esperas, sin registrarte. Si luego ves que necesitas todo lo de una plataforma como Intercom, entonces Intercom tiene sentido.</p>"""
+        ),
+    ),
+    Post(
+        slug="intercom-alternative-small-store",
+        lang="en",
+        pair_slug="alternativa-a-intercom-tienda-pequena",
+        title="Intercom alternative for small stores: Atendyo, simpler and flat-priced",
+        meta_description=(
+            "Is Intercom too big and pricey for your store? Atendyo: AI trained on your "
+            "site, web and WhatsApp, flat 29 EUR/mo. An honest comparison."
+        ),
+        keywords=[
+            "intercom alternative",
+            "intercom alternative small business",
+            "intercom fin pricing",
+            "cheaper than intercom",
+            "ecommerce customer support chatbot",
+        ],
+        date="2026-06-17",
+        excerpt=(
+            "If you looked at Intercom for your small store and it feels big and "
+            "expensive, here is an honest comparison: what you gain with a simpler "
+            "alternative and what you give up."
+        ),
+        body_html=(
+            """<p>If you are looking for an Intercom alternative, you have probably seen two things: it is extremely powerful, and it is built (and priced) for companies with a support team. For a small store that means paying a lot for features you will never touch. Let us be honest about both sides, without making up numbers, and then I will tell you where Atendyo fits and what you give up by switching.</p><h2>Why people look for an Intercom alternative</h2><ul><li><strong>The price scales fast.</strong> Intercom charges per seat, and its AI (Fin) charges per resolution. Great at high volume; for a small store the cost climbs and is hard to predict. Check their website for the exact, changing price.</li><li><strong>It is a huge platform.</strong> Team inbox, CRM, campaigns, product tours, flows. If you only want the AI to answer the repetitive stuff, you pay for a lot you never open.</li><li><strong>It has to be set up.</strong> Getting value out of it takes configuration, and the product is English-first. For serving a small store, it is overkill.</li></ul><p>If you will genuinely use the team inbox, the CRM and the campaigns, Intercom is among the best there is. If not, read on.</p><h2>Atendyo as an alternative for small stores</h2><ul><li><strong>Flat 29 EUR a month</strong>, no per-resolution or per-seat cost. See the <a href="https://atendyo.com/#precio">pricing page</a>.</li><li><strong>AI trained on your store</strong> that answers on its own from day one, no flows to build.</li><li><strong>50+ languages</strong> with automatic detection.</li><li><strong>Web and WhatsApp</strong> with the same assistant.</li><li><strong>Shopify catalog</strong> with live photo, price and stock in the chat.</li><li><strong>Instant demo</strong> and EU-native (GDPR).</li></ul><h2>Being honest: what you give up switching from Intercom to Atendyo</h2><ul><li><strong>Team inbox at scale</strong> with SLAs and many agents.</li><li><strong>CRM, campaigns and product tours.</strong></li><li><strong>Enterprise integrations ecosystem.</strong> Atendyo focuses on online stores (Shopify) and WhatsApp.</li></ul><p>Plainly: if you will really use the team inbox, the CRM and the campaigns, do not switch expecting to find them in Atendyo. If you just want the AI to answer on its own, with no half-day setup and a flat price, Atendyo fits better.</p><h2>The honest way to decide: try it with your store</h2><p><a href="https://atendyo.com/demo">Open the Atendyo demo with your own store</a>: paste your website and within a minute you check whether it answers as you expect, no sign-up. If you then find you need everything a platform like Intercom offers, then Intercom makes sense.</p>"""
+        ),
+    ),
 ]
 
 

app/config.py

@@ -69,6 +69,28 @@ class Settings(BaseSettings):
     shopify_api_version: str = "2026-01"
     shopify_app_proxy_secret: str = ""
     shopify_read_all_orders: bool = False
+    # PUBLIC Shopify App (App Store) — app-level OAuth credentials (NOT per-tenant).
+    # When shopify_app_key is set, the 1-click OAuth install flow + webhooks are
+    # live; otherwise those routes 503 and only the custom-app path is used.
+    shopify_app_key: str = ""
+    shopify_app_secret: str = ""
+    # Scopes requested at install. read_shipping lets the bot quote delivery rates.
+    shopify_app_scopes: str = "read_products,read_orders,read_customers,read_shipping"
+    # Public base URL of THIS backend (for OAuth redirect_uri + webhook addresses).
+    # Falls back to the request's own origin when empty.
+    public_base_url: str = ""
+    # Shopify Billing API plan (charged through Shopify, App Store requirement).
+    # test=True issues non-charging test subscriptions (use on dev stores).
+    shopify_billing_test: bool = False
+    shopify_plan_name: str = "Atendyo"
+    shopify_plan_price: str = "29.00"
+    shopify_plan_currency: str = "EUR"
+    shopify_plan_trial_days: int = 14
+
+    # Partner / reseller program: recurring commission % shown on /partners and
+    # the email partners apply at. Both editable here without touching the page.
+    partner_commission_pct: str = "25"
+    partner_email: str = "comercial@flexigotech.com"
 
     # Admin
     admin_token: str = ""

app/main.py

@@ -18,8 +18,11 @@ from app.routes import (
     health,
     landing,
     legal,
+    partners,
     portal,
     reviews,
+    shopify_oauth,
+    shopify_webhooks,
     stripe_billing,
     whatsapp,
     widget,
@@ -108,6 +111,9 @@ def create_app() -> FastAPI:
     app.include_router(whatsapp.router)
     app.include_router(portal.router)
     app.include_router(stripe_billing.router)
+    app.include_router(shopify_oauth.router)
+    app.include_router(shopify_webhooks.router)
+    app.include_router(partners.router)
     app.include_router(landing.router)
     app.include_router(blog.router)
     app.include_router(legal.router)

app/models.py

@@ -139,6 +139,18 @@ class Tenant(Base):
     last_portal_seen_at: Mapped[datetime | None] = mapped_column(
         DateTime(timezone=True), nullable=True
     )
+    # PUBLIC Shopify App (App Store) install: the OAuth OFFLINE access token
+    # (encrypted). When set, the Shopify client uses it directly (it never
+    # expires) instead of the per-tenant custom-app client_credentials exchange.
+    shopify_oauth_token_enc: Mapped[str] = mapped_column(Text, default="", server_default="")
+    # How this tenant connected its store: "" (none/manual), "custom" (pasted
+    # client_id/secret) or "oauth" (1-click App Store install).
+    shopify_install_source: Mapped[str] = mapped_column(
+        String(12), default="", server_default=""
+    )
+    # Partner/agency attribution: the referral code that brought this tenant in
+    # (for the reseller/affiliate program). Empty = direct.
+    referred_by: Mapped[str] = mapped_column(String(64), default="", server_default="", index=True)
 
 
 class KnowledgeSource(Base):

app/routes/partners.py

@@ -0,0 +1,110 @@
+"""Partner / reseller program: a public landing + referral attribution.
+
+GET /partners       -> the program page (the sales asset Victor sends agencies).
+GET /r/{code}       -> set the referral cookie and bounce to the site, so any
+                       store that signs up afterwards is attributed to the partner.
+
+Attribution is read from the `atendyo_ref` cookie at sign-up time (e.g. the
+Shopify OAuth callback writes it to Tenant.referred_by). The admin sees
+referred_by per tenant to pay commissions.
+"""
+# ruff: noqa: E501 - inline HTML/CSS landing template
+
+from __future__ import annotations
+
+import re
+
+from fastapi import APIRouter, Depends
+from fastapi.responses import HTMLResponse, RedirectResponse
+
+from app.config import Settings, get_settings
+
+router = APIRouter()
+
+REF_COOKIE = "atendyo_ref"
+_REF_MAX_AGE = 90 * 24 * 3600  # 90-day attribution window
+_CODE_RE = re.compile(r"^[A-Za-z0-9_-]{2,64}$")
+
+
+@router.get("/r/{code}")
+async def referral(code: str) -> RedirectResponse:
+    """Stamp the referral cookie and send the visitor to the site."""
+    resp = RedirectResponse("/", status_code=302)
+    if _CODE_RE.match(code or ""):
+        resp.set_cookie(
+            REF_COOKIE, code, max_age=_REF_MAX_AGE, samesite="lax",
+            secure=True, httponly=False, path="/",
+        )
+    return resp
+
+
+@router.get("/partners", response_class=HTMLResponse)
+async def partners(settings: Settings = Depends(get_settings)) -> HTMLResponse:
+    pct = settings.partner_commission_pct
+    email = settings.partner_email
+    return HTMLResponse(_page(pct, email))
+
+
+def _page(pct: str, email: str) -> str:
+    return f"""<!doctype html><html lang="es"><head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Programa de partners — Atendyo</title>
+<meta name="description" content="Gana una comisión recurrente del {pct}% por cada tienda que traigas a Atendyo. Para agencias y freelancers de Shopify en español. Sin coste, con material y demos listas.">
+<link rel="canonical" href="https://atendyo.com/partners">
+<style>
+:root{{--blue:#1c59e9}}
+*{{box-sizing:border-box}}
+body{{font-family:system-ui,-apple-system,Segoe UI,Roboto,sans-serif;color:#16202e;margin:0;line-height:1.6}}
+.wrap{{max-width:820px;margin:0 auto;padding:0 22px}}
+header{{padding:46px 0 8px}}
+h1{{font-size:2.2rem;line-height:1.15;margin:.2em 0}}
+.sub{{font-size:1.18rem;color:#475569;max-width:640px}}
+.btn{{display:inline-block;background:var(--blue);color:#fff;text-decoration:none;padding:13px 22px;border-radius:11px;font-weight:700;margin:8px 8px 8px 0}}
+.btn.ghost{{background:#eef2fb;color:var(--blue)}}
+.grid{{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:16px;margin:18px 0}}
+.card{{background:#f7f9fc;border:1px solid #e5ebf3;border-radius:14px;padding:18px}}
+.card h3{{margin:.1em 0 .3em}}
+.big{{font-size:2.4rem;font-weight:800;color:var(--blue)}}
+h2{{margin-top:34px}}
+ul{{padding-left:1.1em}}
+footer{{margin:46px 0;color:#64748b;font-size:.92rem}}
+a{{color:var(--blue)}}
+</style></head><body>
+<div class="wrap">
+<header>
+  <p style="font-weight:700;color:var(--blue);letter-spacing:.04em">ATENDYO · PARTNERS</p>
+  <h1>Recomienda Atendyo a tus clientes y gana una comisión recurrente</h1>
+  <p class="sub">Si montas o gestionas tiendas Shopify (o WooCommerce), ya tienes a los clientes que a nosotros nos cuesta llegar. Tú les pones el asistente de IA; tú te llevas una comisión <b>todos los meses</b> que sigan.</p>
+  <p><a class="btn" href="mailto:{email}?subject=Quiero%20ser%20partner%20de%20Atendyo">Quiero ser partner</a>
+  <a class="btn ghost" href="https://atendyo.com/demo">Ver la demo primero</a></p>
+</header>
+
+<div class="grid">
+  <div class="card"><div class="big">{pct}%</div><div>comisión <b>recurrente</b> por cada cliente, mientras siga pagando.</div></div>
+  <div class="card"><div class="big">0 €</div><div>entrar es gratis. Sin cuotas, sin mínimos, sin exclusividad.</div></div>
+  <div class="card"><div class="big">1 min</div><div>montas una demo de la tienda de tu cliente y se la enseñas funcionando.</div></div>
+</div>
+
+<h2>Por qué encaja contigo</h2>
+<ul>
+  <li><b>Es un extra fácil de vender:</b> tus clientes ya te piden "atención al cliente" y "vender más". Atendyo lo resuelve sin que tú mantengas nada.</li>
+  <li><b>No te da trabajo:</b> se entrena solo con la web del cliente, se instala con una línea de código o en 1 clic desde Shopify, y nosotros llevamos el soporte.</li>
+  <li><b>En español:</b> pensado para tiendas que atienden en español (y en más de 50 idiomas). Menos competencia que en inglés.</li>
+  <li><b>Honesto:</b> precio plano, prueba de 14 días sin tarjeta, y si no encaja se apaga solo. No vas a quemar tu relación con el cliente.</li>
+</ul>
+
+<h2>Cómo funciona</h2>
+<ul>
+  <li><b>1.</b> Nos escribes y te damos tu enlace de partner (con tu código).</li>
+  <li><b>2.</b> Se lo pasas a tu cliente o le montas la demo de su tienda. Cuando activa Atendyo desde tu enlace, queda atribuido a ti automáticamente.</li>
+  <li><b>3.</b> Cobras tu {pct}% cada mes que tu cliente siga. Tú ves a tus clientes; nosotros te pagamos.</li>
+</ul>
+
+<h2>Para quién es</h2>
+<p>Agencias y freelancers de Shopify/ecommerce, sobre todo en España y LATAM; consultores que ya gestionan varias tiendas; y cualquiera con una audiencia de dueños de tienda. Si te encaja, escríbenos.</p>
+
+<p style="margin:28px 0"><a class="btn" href="mailto:{email}?subject=Quiero%20ser%20partner%20de%20Atendyo">Escríbenos y empezamos</a></p>
+
+<footer>Atendyo — La IA que atiende tu web y tu WhatsApp. <a href="https://atendyo.com/">atendyo.com</a></footer>
+</div>
+</body></html>"""

app/routes/shopify_oauth.py

@@ -0,0 +1,245 @@
+"""Public Shopify App — 1-click OAuth install.
+
+GET /shopify/install?shop=foo.myshopify.com  -> redirect to Shopify authorize.
+GET /shopify/callback?...                     -> verify, exchange, provision tenant.
+
+Only active when SHOPIFY_APP_KEY/SECRET are configured; otherwise 503 (the
+custom-app path is unaffected). The merchant ends up with a tenant whose Shopify
+client uses the OAuth offline token, and is handed their client-portal key.
+"""
+
+# ruff: noqa: E501 - the install success page is an inline HTML/CSS template
+from __future__ import annotations
+
+import hashlib
+import hmac
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import HTMLResponse, RedirectResponse
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.billing import _slugify, _unique_slug
+from app.config import Settings, get_settings
+from app.crypto import encrypt
+from app.db import get_session
+from app.models import Tenant
+from app.shopify import oauth
+from app.tenancy import generate_dashboard_token
+
+log = logging.getLogger(__name__)
+router = APIRouter()
+
+
+def _origin(request: Request, settings: Settings) -> str:
+    """Public https origin for redirect_uri (configured, else request-derived)."""
+    if settings.public_base_url:
+        return settings.public_base_url.rstrip("/")
+    origin = str(request.base_url).rstrip("/")
+    if origin.startswith("http://"):
+        origin = "https://" + origin[len("http://"):]
+    return origin
+
+
+def _state_for(shop: str, secret: str) -> str:
+    """CSRF state bound to the shop via our secret (no server-side storage)."""
+    return hmac.new(secret.encode(), shop.encode(), hashlib.sha256).hexdigest()[:32]
+
+
+@router.get("/shopify/install")
+async def shopify_install(
+    request: Request, shop: str = "", settings: Settings = Depends(get_settings)
+) -> RedirectResponse:
+    if not (settings.shopify_app_key and settings.shopify_app_secret):
+        raise HTTPException(status_code=503, detail="Public Shopify app not configured")
+    shop_n = oauth.normalize_shop(shop)
+    if not shop_n:
+        raise HTTPException(status_code=400, detail="invalid shop")
+    redirect_uri = f"{_origin(request, settings)}/shopify/callback"
+    url = oauth.build_install_url(
+        shop_n,
+        settings.shopify_app_key,
+        settings.shopify_app_scopes,
+        redirect_uri,
+        _state_for(shop_n, settings.secret_key),
+    )
+    return RedirectResponse(url, status_code=302)
+
+
+@router.get("/shopify/callback")
+async def shopify_callback(
+    request: Request,
+    db: AsyncSession = Depends(get_session),
+    settings: Settings = Depends(get_settings),
+) -> HTMLResponse:
+    if not (settings.shopify_app_key and settings.shopify_app_secret):
+        raise HTTPException(status_code=503, detail="Public Shopify app not configured")
+
+    params = dict(request.query_params)
+    shop = oauth.normalize_shop(params.get("shop", ""))
+    code = params.get("code", "")
+    state = params.get("state", "")
+    if not shop or not code:
+        raise HTTPException(status_code=400, detail="missing shop/code")
+    # 1) integrity: Shopify HMAC over the query string (app secret)
+    if not oauth.verify_hmac(params, settings.shopify_app_secret):
+        raise HTTPException(status_code=400, detail="bad hmac")
+    # 2) CSRF: state must match the shop-bound nonce we issued
+    if not hmac.compare_digest(state, _state_for(shop, settings.secret_key)):
+        raise HTTPException(status_code=400, detail="bad state")
+
+    # 3) exchange the code for a permanent OFFLINE token
+    try:
+        data = await oauth.exchange_code(
+            shop, code, settings.shopify_app_key, settings.shopify_app_secret
+        )
+    except Exception as exc:  # noqa: BLE001 - surface a clean error, never 500-leak
+        log.warning("oauth token exchange failed for %s: %s", shop, exc)
+        raise HTTPException(status_code=502, detail="token exchange failed") from None
+    token = data.get("access_token", "")
+    if not token:
+        raise HTTPException(status_code=502, detail="no access token")
+
+    # 4) link or create the tenant for this shop, store the token (encrypted)
+    tenant = (
+        await db.execute(select(Tenant).where(Tenant.shopify_shop == shop))
+    ).scalar_one_or_none()
+    new = tenant is None
+    if new:
+        store_name = shop.split(".")[0]
+        slug = await _unique_slug(db, _slugify(store_name))
+        tenant = Tenant(
+            slug=slug,
+            name=store_name,
+            shopify_shop=shop,
+            shopify_install_source="oauth",
+        )
+        # Partner attribution: the referral cookie (set by /r/{code}) tags who
+        # brought this store in, for the reseller commission.
+        from app.routes.partners import _CODE_RE, REF_COOKIE
+        ref = (request.cookies.get(REF_COOKIE) or "").strip()
+        if ref and _CODE_RE.match(ref):
+            tenant.referred_by = ref
+        db.add(tenant)
+        await db.flush()
+    tenant.shopify_oauth_token_enc = encrypt(token)
+    tenant.shopify_install_source = "oauth"
+    # An install (or re-install) un-pauses any prior billing/uninstall pause.
+    if tenant.disabled_reason in ("billing", ""):
+        tenant.chatbot_enabled = True
+        tenant.disabled_reason = ""
+    if not tenant.dashboard_token:
+        await generate_dashboard_token(db, tenant)
+    from app.tenancy import _registry
+    _registry.invalidate(tenant.id)
+    await db.commit()
+    log.info("shopify oauth install %s tenant=%s (new=%s)", shop, tenant.slug, new)
+
+    origin = _origin(request, settings)
+    return HTMLResponse(_success_html(origin, tenant.slug, tenant.dashboard_token))
+
+
+@router.post("/shopify/billing/start")
+async def billing_start(
+    request: Request,
+    db: AsyncSession = Depends(get_session),
+    settings: Settings = Depends(get_settings),
+) -> dict:
+    """Create a recurring Shopify charge for the authenticated tenant and return
+    the confirmation URL (the merchant approves it in their Shopify admin).
+    Portal-token authed; requires the tenant's Shopify (OAuth) connection."""
+    from app.routes.portal import require_portal_tenant
+    from app.shopify import billing as shopify_billing
+    from app.tenancy import tenant_shopify_client
+
+    tenant = await require_portal_tenant(request.headers.get("authorization", ""), db)
+    client = tenant_shopify_client(tenant)
+    if client is None:
+        raise HTTPException(status_code=409, detail="Shopify not connected for this store")
+    return_url = f"{_origin(request, settings)}/shopify/billing/return?shop={tenant.shopify_shop}"
+    try:
+        out = await shopify_billing.create_app_subscription(
+            client,
+            name=settings.shopify_plan_name,
+            amount=settings.shopify_plan_price,
+            currency=settings.shopify_plan_currency,
+            return_url=return_url,
+            trial_days=settings.shopify_plan_trial_days,
+            test=settings.shopify_billing_test,
+        )
+    except Exception as exc:  # noqa: BLE001
+        log.warning("shopify billing start failed for %s: %s", tenant.slug, exc)
+        raise HTTPException(status_code=502, detail="billing start failed") from None
+    if not out.get("confirmation_url"):
+        raise HTTPException(status_code=502, detail="no confirmation url")
+    return out
+
+
+@router.get("/shopify/billing/return")
+async def billing_return(
+    request: Request,
+    shop: str = "",
+    db: AsyncSession = Depends(get_session),
+    settings: Settings = Depends(get_settings),
+) -> HTMLResponse:
+    """Merchant landed back after approving the charge: confirm the subscription
+    is active and (re)enable the bot. Verified against Shopify, never trusting the
+    redirect alone."""
+    from app.shopify import billing as shopify_billing
+    from app.tenancy import _registry, tenant_shopify_client
+
+    shop_n = oauth.normalize_shop(shop)
+    tenant = (
+        await db.execute(select(Tenant).where(Tenant.shopify_shop == shop_n))
+    ).scalar_one_or_none() if shop_n else None
+    active = False
+    if tenant:
+        client = tenant_shopify_client(tenant)
+        if client is not None:
+            active = await shopify_billing.has_active_subscription(client)
+        if active:
+            tenant.chatbot_enabled = True
+            tenant.disabled_reason = ""
+            _registry.invalidate(tenant.id)
+            await db.commit()
+            log.info("shopify billing active for tenant=%s", tenant.slug)
+    origin = _origin(request, settings)
+    msg = (
+        "Tu suscripción está activa. ¡Gracias!" if active
+        else "No hemos podido confirmar la suscripción todavía. Si acabas de aprobarla, "
+        "espera unos segundos y recarga, o entra en tu panel."
+    )
+    return HTMLResponse(
+        f"""<!doctype html><html lang="es"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1"><title>Atendyo</title>
+<style>body{{font-family:system-ui,sans-serif;max-width:600px;margin:8vh auto;padding:0 20px;line-height:1.5}}
+a.btn{{display:inline-block;background:#1c59e9;color:#fff;text-decoration:none;padding:11px 18px;border-radius:10px;font-weight:600}}</style>
+</head><body><h1>Atendyo</h1><p>{msg}</p>
+<p><a class="btn" href="{origin}/portal">Ir a mi panel</a></p></body></html>"""
+    )
+
+
+def _success_html(origin: str, slug: str, key: str) -> str:
+    snippet = f'&lt;script src="{origin}/widget.js?t={slug}" defer&gt;&lt;/script&gt;'
+    return f"""<!doctype html><html lang="es"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Atendyo — instalado</title>
+<style>body{{font-family:system-ui,Segoe UI,Roboto,sans-serif;max-width:640px;margin:6vh auto;padding:0 20px;color:#1a1a1a;line-height:1.5}}
+.card{{background:#f6f8fb;border:1px solid #e3e8ef;border-radius:14px;padding:22px;margin:18px 0}}
+code{{background:#eef1f6;padding:2px 6px;border-radius:6px;word-break:break-all}}
+a.btn{{display:inline-block;background:#1c59e9;color:#fff;text-decoration:none;padding:11px 18px;border-radius:10px;font-weight:600}}</style>
+</head><body>
+<h1>Atendyo está instalado</h1>
+<p>Tu asistente ya está conectado a tu tienda Shopify. Entra en tu panel para
+configurarlo (marca, conocimiento, WhatsApp) y copiar tu código de instalación.</p>
+<div class="card">
+  <p><b>Tu clave de acceso al panel</b> (guárdala):</p>
+  <p><code>{key}</code></p>
+  <p style="margin-top:14px"><a class="btn" href="{origin}/portal">Ir a mi panel</a></p>
+</div>
+<div class="card">
+  <p><b>Código del widget</b> (pégalo antes de &lt;/body&gt; en tu tema):</p>
+  <p><code>{snippet}</code></p>
+</div>
+</body></html>"""

app/routes/shopify_webhooks.py

@@ -0,0 +1,122 @@
+"""Mandatory Shopify App webhooks (required to pass App Store review).
+
+POST /shopify/webhooks/app_uninstalled      -> pause + unlink the tenant
+POST /shopify/webhooks/customers_data_request-> GDPR: log a data-access request
+POST /shopify/webhooks/customers_redact      -> GDPR: erase a customer's data
+POST /shopify/webhooks/shop_redact           -> GDPR: purge all shop data (48h post-uninstall)
+
+Every request is verified with the X-Shopify-Hmac-Sha256 header (base64 HMAC-
+SHA256 of the raw body, keyed by the app secret). An unverified call is 401.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import Settings, get_settings
+from app.db import get_session
+from app.models import Tenant
+from app.tenancy import _registry, purge_tenant
+
+log = logging.getLogger(__name__)
+router = APIRouter()
+
+
+def verify_webhook(body: bytes, header_hmac: str, app_secret: str) -> bool:
+    if not header_hmac or not app_secret:
+        return False
+    digest = base64.b64encode(
+        hmac.new(app_secret.encode(), body, hashlib.sha256).digest()
+    ).decode()
+    return hmac.compare_digest(digest, header_hmac)
+
+
+async def _verified_body(request: Request, settings: Settings) -> dict:
+    secret = settings.shopify_app_secret
+    if not secret:
+        raise HTTPException(status_code=503, detail="Public Shopify app not configured")
+    body = await request.body()
+    if not verify_webhook(body, request.headers.get("X-Shopify-Hmac-Sha256", ""), secret):
+        raise HTTPException(status_code=401, detail="invalid hmac")
+    try:
+        return json.loads(body or b"{}")
+    except ValueError:
+        return {}
+
+
+def _shop_of(request: Request, payload: dict) -> str:
+    return (
+        request.headers.get("X-Shopify-Shop-Domain", "")
+        or payload.get("shop_domain", "")
+        or payload.get("myshopify_domain", "")
+    ).strip().lower()
+
+
+@router.post("/shopify/webhooks/app_uninstalled")
+async def app_uninstalled(
+    request: Request,
+    db: AsyncSession = Depends(get_session),
+    settings: Settings = Depends(get_settings),
+) -> dict:
+    payload = await _verified_body(request, settings)
+    shop = _shop_of(request, payload)
+    tenant = (
+        await db.execute(select(Tenant).where(Tenant.shopify_shop == shop))
+    ).scalar_one_or_none() if shop else None
+    if tenant:
+        # The OAuth token is dead after uninstall: clear it and pause the bot.
+        # Keep the account/data (shop/redact purges 48h later if they don't return).
+        tenant.shopify_oauth_token_enc = ""
+        tenant.chatbot_enabled = False
+        tenant.disabled_reason = "billing"  # treated like a lapse; re-install re-enables
+        _registry.invalidate(tenant.id)
+        await db.commit()
+        log.info("app_uninstalled: paused tenant=%s shop=%s", tenant.slug, shop)
+    return {"status": "ok"}
+
+
+@router.post("/shopify/webhooks/customers_data_request")
+async def customers_data_request(
+    request: Request, settings: Settings = Depends(get_settings)
+) -> dict:
+    # We don't retain customer PII beyond auto-expiring chat sessions, so there is
+    # no profile to export; we acknowledge and log the request (GDPR compliance).
+    payload = await _verified_body(request, settings)
+    log.info("GDPR customers/data_request shop=%s", _shop_of(request, payload))
+    return {"status": "ok"}
+
+
+@router.post("/shopify/webhooks/customers_redact")
+async def customers_redact(
+    request: Request, settings: Settings = Depends(get_settings)
+) -> dict:
+    payload = await _verified_body(request, settings)
+    log.info("GDPR customers/redact shop=%s", _shop_of(request, payload))
+    return {"status": "ok"}
+
+
+@router.post("/shopify/webhooks/shop_redact")
+async def shop_redact(
+    request: Request,
+    db: AsyncSession = Depends(get_session),
+    settings: Settings = Depends(get_settings),
+) -> dict:
+    # Sent ~48h after uninstall: erase ALL data for the shop.
+    payload = await _verified_body(request, settings)
+    shop = _shop_of(request, payload)
+    tenant = (
+        await db.execute(select(Tenant).where(Tenant.shopify_shop == shop))
+    ).scalar_one_or_none() if shop else None
+    if tenant:
+        await purge_tenant(db, tenant)
+        await db.commit()
+        log.info("GDPR shop/redact: purged tenant shop=%s", shop)
+    return {"status": "ok"}

app/schemas.py

@@ -188,6 +188,8 @@ class TenantOut(BaseModel):
     is_paid: bool = False              # has an active Stripe subscription
     disabled_reason: str = ""          # "", "trial", "billing", "admin"
     last_portal_seen_at: str | None = None  # last time the client opened their portal
+    shopify_install_source: str = ""   # "", "custom", "oauth" (App Store 1-click)
+    referred_by: str = ""              # partner/agency referral code, "" = direct
 
     @classmethod
     def from_tenant(cls, t) -> TenantOut:
@@ -233,4 +235,6 @@ class TenantOut(BaseModel):
                 t.last_portal_seen_at.isoformat()
                 if getattr(t, "last_portal_seen_at", None) else None
             ),
+            shopify_install_source=getattr(t, "shopify_install_source", "") or "",
+            referred_by=getattr(t, "referred_by", "") or "",
         )

app/shopify/billing.py

@@ -0,0 +1,97 @@
+"""Shopify Billing API (App Store apps must charge through it, not Stripe).
+
+Creates a recurring app subscription and reads the active ones, via the Admin
+GraphQL API using the merchant's OAuth token (the same client the rest of the
+app uses). Charging flow:
+  1. create_app_subscription(...) -> returns a confirmation_url.
+  2. Redirect the merchant there; they approve the charge in their admin.
+  3. Shopify redirects back to return_url; the subscription is then active.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.shopify.client import ShopifyError, ShopifyGraphQLClient
+
+_CREATE = """
+mutation AppSubscriptionCreate($name: String!, $returnUrl: URL!, $test: Boolean!,
+  $trialDays: Int!, $amount: Decimal!, $currency: CurrencyCode!, $interval: AppPricingInterval!) {
+  appSubscriptionCreate(
+    name: $name
+    returnUrl: $returnUrl
+    test: $test
+    trialDays: $trialDays
+    lineItems: [{
+      plan: { appRecurringPricingDetails: {
+        price: { amount: $amount, currencyCode: $currency }
+        interval: $interval
+      } }
+    }]
+  ) {
+    confirmationUrl
+    appSubscription { id status }
+    userErrors { field message }
+  }
+}
+"""
+
+_ACTIVE = """
+query ActiveSubscriptions {
+  currentAppInstallation {
+    activeSubscriptions { id name status }
+  }
+}
+"""
+
+
+async def create_app_subscription(
+    client: ShopifyGraphQLClient,
+    *,
+    name: str,
+    amount: str,
+    return_url: str,
+    currency: str = "EUR",
+    interval: str = "EVERY_30_DAYS",  # or ANNUAL
+    trial_days: int = 14,
+    test: bool = False,
+) -> dict[str, Any]:
+    """Create a recurring charge. Returns {confirmation_url, subscription_id,
+    status}. Raises ShopifyError on userErrors so the caller never silently
+    proceeds without a confirmation URL."""
+    data = await client.execute(
+        _CREATE,
+        {
+            "name": name,
+            "returnUrl": return_url,
+            "test": test,
+            "trialDays": int(trial_days),
+            "amount": str(amount),
+            "currency": currency,
+            "interval": interval,
+        },
+    )
+    res = (data or {}).get("appSubscriptionCreate") or {}
+    errors = res.get("userErrors") or []
+    if errors:
+        raise ShopifyError(f"appSubscriptionCreate: {errors}")
+    sub = res.get("appSubscription") or {}
+    return {
+        "confirmation_url": res.get("confirmationUrl"),
+        "subscription_id": sub.get("id"),
+        "status": sub.get("status"),
+    }
+
+
+async def list_active_subscriptions(client: ShopifyGraphQLClient) -> list[dict[str, Any]]:
+    data = await client.execute(_ACTIVE)
+    inst = (data or {}).get("currentAppInstallation") or {}
+    return list(inst.get("activeSubscriptions") or [])
+
+
+async def has_active_subscription(client: ShopifyGraphQLClient) -> bool:
+    try:
+        subs = await list_active_subscriptions(client)
+    except ShopifyError:
+        return False
+    return any((s.get("status") or "").upper() == "ACTIVE" for s in subs)

app/shopify/oauth.py

@@ -0,0 +1,94 @@
+"""Public Shopify App OAuth (authorization-code grant → permanent offline token).
+
+This is the 1-click App Store install path, separate from the per-tenant custom
+app (client_credentials). Flow:
+  1. /shopify/install?shop=foo.myshopify.com -> redirect to Shopify authorize.
+  2. Merchant approves -> Shopify redirects to /shopify/callback with code+hmac.
+  3. We verify the HMAC (app secret), exchange the code for an OFFLINE access
+     token, and store it on the tenant (auto-creating/linking by shop domain).
+
+All request data from Shopify is HMAC-verified or strictly validated before use.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import re
+from urllib.parse import urlencode
+
+import httpx
+
+# A valid myshopify domain — validated before it is ever interpolated into a URL
+# or a redirect, so a crafted ?shop= value can't point us at another host.
+_SHOP_RE = re.compile(r"^[a-z0-9][a-z0-9-]*\.myshopify\.com$", re.IGNORECASE)
+
+
+def is_valid_shop(shop: str) -> bool:
+    return bool(_SHOP_RE.match((shop or "").strip()))
+
+
+def normalize_shop(shop: str) -> str:
+    """Accept 'foo', 'foo.myshopify.com' or a full URL; return the bare domain
+    if it is a valid myshopify host, else ''."""
+    s = (shop or "").strip().lower()
+    s = s.removeprefix("https://").removeprefix("http://").split("/")[0]
+    if "." not in s:
+        s = f"{s}.myshopify.com"
+    return s if is_valid_shop(s) else ""
+
+
+def build_install_url(
+    shop: str, api_key: str, scopes: str, redirect_uri: str, state: str
+) -> str:
+    """The Shopify authorize URL to redirect the merchant to. ``shop`` MUST be a
+    validated myshopify domain (caller checks)."""
+    q = urlencode(
+        {
+            "client_id": api_key,
+            "scope": scopes,
+            "redirect_uri": redirect_uri,
+            "state": state,
+        }
+    )
+    return f"https://{shop}/admin/oauth/authorize?{q}"
+
+
+def verify_hmac(params: dict[str, str], app_secret: str) -> bool:
+    """Verify the `hmac` on an OAuth callback / App Proxy-less query string.
+
+    Shopify signs all params EXCEPT `hmac` (and the legacy `signature`): sort by
+    key, join as k=v&..., HMAC-SHA256 with the app secret, compare hex (constant
+    time)."""
+    given = params.get("hmac", "")
+    if not given or not app_secret:
+        return False
+    msg = "&".join(
+        f"{k}={params[k]}" for k in sorted(params) if k not in ("hmac", "signature")
+    )
+    digest = hmac.new(app_secret.encode(), msg.encode(), hashlib.sha256).hexdigest()
+    return hmac.compare_digest(digest, given)
+
+
+async def exchange_code(
+    shop: str,
+    code: str,
+    api_key: str,
+    app_secret: str,
+    *,
+    client: httpx.AsyncClient | None = None,
+) -> dict:
+    """Exchange the authorization code for a permanent OFFLINE access token.
+    Returns the Shopify JSON ({"access_token", "scope"})."""
+    owns = client is None
+    cl = client or httpx.AsyncClient(timeout=20.0)
+    try:
+        resp = await cl.post(
+            f"https://{shop}/admin/oauth/access_token",
+            json={"client_id": api_key, "client_secret": app_secret, "code": code},
+        )
+        resp.raise_for_status()
+        return resp.json()
+    finally:
+        if owns:
+            await cl.aclose()

app/shopify/token.py

@@ -29,12 +29,17 @@ class ShopifyTokenManager:
         *,
         now: Callable[[], datetime] = _now,
         client: httpx.AsyncClient | None = None,
+        static_token: str = "",
     ) -> None:
         self.shop = shop
         self.client_id = client_id
         self.client_secret = client_secret
         self._now = now
         self._client = client
+        # A PUBLIC-app OAuth offline token never expires, so we just hold it and
+        # skip the client_credentials exchange entirely. A 401 means the merchant
+        # uninstalled / re-auth is needed (handled by re-running the OAuth flow).
+        self._static = static_token or ""
         self._token: str | None = None
         self._expires_at: datetime | None = None
         self._lock = asyncio.Lock()
@@ -60,6 +65,8 @@ class ShopifyTokenManager:
         )
 
     async def get_token(self) -> str:
+        if self._static:
+            return self._static
         if self._is_fresh():
             return self._token  # type: ignore[return-value]
         async with self._lock:

app/tenancy.py

@@ -170,12 +170,37 @@ class _ShopifyRegistry:
             self._cache.pop(tenant_id, None)
 
     def for_tenant(self, tenant: Tenant) -> ShopifyGraphQLClient | None:
+        if not tenant.shopify_shop:
+            return None
+        # PUBLIC App (1-click install): use the OAuth offline token directly. It
+        # never expires, so no client_credentials exchange — and no per-tenant
+        # client_id/secret needed (those belong to the app).
+        oauth_token = (
+            decrypt(tenant.shopify_oauth_token_enc)
+            if tenant.shopify_oauth_token_enc
+            else ""
+        )
+        if oauth_token:
+            fingerprint = (
+                f"oauth|{tenant.shopify_shop}|{tenant.shopify_api_version}|{oauth_token[:6]}"
+            )
+            cached = self._cache.get(tenant.id)
+            if cached and cached[0] == fingerprint:
+                return cached[1]
+            tm = ShopifyTokenManager(
+                tenant.shopify_shop, "", "", static_token=oauth_token
+            )
+            client = ShopifyGraphQLClient(tenant.shopify_shop, tenant.shopify_api_version, tm)
+            self._cache[tenant.id] = (fingerprint, client)
+            return client
+
+        # Custom-app path (merchant pasted client_id/secret): client_credentials.
         secret = (
             decrypt(tenant.shopify_client_secret_enc)
             if tenant.shopify_client_secret_enc
             else ""
         )
-        if not (tenant.shopify_shop and tenant.shopify_client_id and secret):
+        if not (tenant.shopify_client_id and secret):
             return None
         fingerprint = (
             f"{tenant.shopify_shop}|{tenant.shopify_client_id}"

docs/SHOPIFY-APP-STORE-PLAN.md

@@ -0,0 +1,53 @@
+# Atendyo en el Shopify App Store — plan accionable
+
+> Decisión: **SÍ montarla, como track de medio plazo en paralelo.** Su valor real
+> no es "discovery mágico" (la categoría está reventada y sin reviews quedas
+> enterrado), sino: **instalación en 1 clic** (hoy el cliente tiene que crear una
+> custom app y pegar client_id/secret = fricción que pierde demos) + el **flywheel
+> de reviews** + aparecer cuando alguien busca "chatbot" dentro de Shopify.
+> Empezar el papeleo YA porque el review tarda 4-6 semanas. NO es el cliente de mañana.
+
+## La verdad de los plazos (verificada 2026)
+- Review: **5-10 días hábiles** por ronda, normalmente **2-3 rondas** → presupuesta
+  **4-6 semanas** desde envío hasta publicado.
+- Exige: estándares de seguridad, **rendimiento (Lighthouse)** en las páginas que toca,
+  **webhooks GDPR obligatorios** (`customers/data_request`, `customers/redact`,
+  `shop/redact`) + `app/uninstalled`, **Billing API** (si cobras a través de la app),
+  **OAuth** (instalación), y app **embebida** (App Bridge) recomendada para "Built for Shopify".
+- Fuente: shopify.dev/docs/apps/launch/shopify-app-store/app-store-requirements
+
+---
+
+## Qué construyo YO (en este repo, sin romper el flujo custom-app actual)
+
+| Pieza | Estado | Notas |
+|---|---|---|
+| **OAuth install** (`/shopify/install` → `/shopify/callback`) | en curso | authorize → code → token offline permanente, HMAC verificado, auto-crea/linka tenant |
+| **Token offline por tenant** (`shopify_oauth_token_enc`) | en curso | el registro usa este token estático si existe; si no, cae al `client_credentials` actual (ambos conviven) |
+| **Webhooks obligatorios** | pendiente | `app/uninstalled` (pausa/limpia tenant) + GDPR ×3, todos con HMAC del app secret |
+| **Billing API de Shopify** | pendiente | `appSubscriptionCreate` (recurring), plan + trial 14 días; alternativa a Stripe DENTRO de la app |
+| **App embebida (App Bridge)** | pendiente | el portal del cliente servido dentro del admin de Shopify (iframe + session token); v1 puede ser no-embebida y migrar después |
+| **Theme app extension (widget)** | parcial | `extension/shopify.app.toml` ya existe con app_proxy + scopes; falta el app-embed block del widget |
+| **shopify.app.toml** completo | parcial | scopes ya incluyen `read_shipping`; falta `application_url`, `redirect_urls`, webhooks, `[access.admin]` |
+
+## Qué tienes que hacer TÚ (no lo puedo hacer por ti — son cuentas/portales externos)
+1. **Cuenta de Shopify Partners** (gratis): partners.shopify.com → crear.
+2. **Crear la app** en el Partner Dashboard → obtener **API key + API secret** (a nivel de app, NO por cliente). Me los pasas → los pongo como secrets (`SHOPIFY_APP_KEY`, `SHOPIFY_APP_SECRET`).
+3. **Configurar URLs** en el Partner Dashboard: App URL = `https://atendyo.com` (o el backend HF), Allowed redirection URL(s) = `https://<backend>/shopify/callback`.
+4. **Contenido del listado** (esto vende o entierra la app): nombre, icono, **capturas reales**, vídeo demo, descripción, categoría (Customer support), pricing. Las capturas/vídeo las preparo yo con el bot real; tú las subes al portal.
+5. **Enviar a revisión** y atender las 2-3 rondas de feedback (te preparo las respuestas).
+6. **Reviews**: pedir a los primeros clientes (incl. Toorx/BAI) una review en cuanto esté publicada — es el flywheel.
+
+## Secuencia recomendada
+1. (YO) OAuth + webhooks + Billing + tests → app instalable de punta a punta. ← **empezando ahora**
+2. (TÚ) Partner account + crear app + pasarme key/secret.
+3. (YO) Conecto las credenciales, pruebo install real en una dev store, preparo capturas/vídeo.
+4. (TÚ) Subes listado + envías a revisión.
+5. (AMBOS) Iteramos el feedback de revisión.
+6. Publicado → pedir reviews a los clientes actuales.
+
+## Expectativa honesta
+Listarse **no** trae instalaciones solo. El App Store es un **canal de conversión y
+confianza** (instalar fácil + reviews + "está en la tienda oficial"), que alimenta
+lo que de verdad capta: la máquina de demos, el SEO en español y los partners. Por eso
+va en paralelo, no en el camino crítico de conseguir el próximo cliente.

migrations/versions/0024_shopify_oauth_app.py

@@ -0,0 +1,33 @@
+"""Public Shopify App (App Store): per-tenant OAuth offline token + install
+source + partner referral attribution.
+
+Additive, idempotent on Postgres (ADD COLUMN IF NOT EXISTS). On other dialects
+it is a no-op (tests/dev use create_all which already has the columns).
+"""
+
+from __future__ import annotations
+
+from alembic import op
+
+revision = "0024_shopify_oauth_app"
+down_revision = "0023_last_portal_seen"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    if op.get_bind().dialect.name != "postgresql":
+        return
+    op.execute("ALTER TABLE tenants ADD COLUMN IF NOT EXISTS shopify_oauth_token_enc TEXT DEFAULT ''")
+    op.execute("ALTER TABLE tenants ADD COLUMN IF NOT EXISTS shopify_install_source VARCHAR(12) DEFAULT ''")
+    op.execute("ALTER TABLE tenants ADD COLUMN IF NOT EXISTS referred_by VARCHAR(64) DEFAULT ''")
+    op.execute("CREATE INDEX IF NOT EXISTS ix_tenants_referred_by ON tenants (referred_by)")
+
+
+def downgrade() -> None:
+    if op.get_bind().dialect.name != "postgresql":
+        return
+    op.execute("DROP INDEX IF EXISTS ix_tenants_referred_by")
+    op.execute("ALTER TABLE tenants DROP COLUMN IF EXISTS referred_by")
+    op.execute("ALTER TABLE tenants DROP COLUMN IF EXISTS shopify_install_source")
+    op.execute("ALTER TABLE tenants DROP COLUMN IF EXISTS shopify_oauth_token_enc")