Estado: v1 (2026-09-30). La especificación pública de cómo cualquier plataforma de e-commerce se conecta con Spaidoo.
1 Qué es un conector
Spaidoo da a una tienda online un widget (guardar para más tarde, listas, avisos de bajada de precio, búsqueda) y un conjunto de acciones de comunicación (mailing, push, posts). El widget funciona en cualquier web con una sola etiqueta <script>. Un conector es la pieza de software que vive dentro de una plataforma de tienda (un módulo, una app, un plugin, un backend headless…) y le permite a Spaidoo hacer lo que un script solo no puede:
| Capacidad | Qué añade |
|---|---|
catalog.feed | Spaidoo conoce los productos de la tienda (precio, stock, imágenes) — obligatoria |
catalog.changes | Los cambios de precio y de stock llegan a Spaidoo en segundos en lugar de en la siguiente lectura diaria |
storefront.saveAnchors | El conector imprime los botones de guardar en el tema (§7); el admin de Spaidoo le indica al comerciante que vienen del conector |
identity | Un cliente con sesión iniciada en la tienda conserva sus productos guardados en todos sus dispositivos, sin cuenta de Spaidoo |
customers | Spaidoo puede pedir a la tienda el email (y el consentimiento de marketing) de un cliente identificado cuando el comerciante lo necesita |
customerLookup | La ruta de clientes también responde por email: el comerciante puede importar listas desde un fichero exportado de otra app de wishlist |
marketingConsent | Cuando un cliente con sesión iniciada en la tienda acepta, en el widget, recibir los emails de la tienda, Spaidoo pide a la tienda que active su consentimiento de email marketing |
customerErase | Borrar un cliente en la tienda borra sus datos en Spaidoo para esa tienda |
wishlistImport | Las listas de una extensión de wishlist anterior se traen a Spaidoo |
push | Las notificaciones web push se sirven desde el propio dominio de la tienda |
domainVerification | La tienda demuestra que es dueña de su dominio sin cambios de DNS |
billing.platform | La plataforma cobra el plan de Spaidoo de la tienda y le dice a Spaidoo qué plan tiene (§4.12). Solo para apps que Spaidoo ha habilitado para ello |
panel.widget | El conector tiene panel propio en el admin de la plataforma (instalación, apariencia, estado, importación): el admin de Spaidoo envía allí al comerciante en lugar de repetir esas pantallas |
Regla del contrato: Spaidoo decide qué hacer a partir de las capacidades que un conector declara, nunca a partir del nombre de su plataforma. Cualquier plataforma puede construir un conector; el campo platform es solo informativo.
Un conector puede implementar cualquier subconjunto, siempre que incluya catalog.feed.
2 Convenciones
- URL base de las llamadas conector → Spaidoo:
https://api-plugin.spaidoo.com/connector/v1 - JSON de entrada y de salida, UTF-8.
Content-Type: application/json. - Los tiempos son segundos Unix (enteros) salvo que un campo diga otra cosa.
- Los ids de la tienda (id de cliente, id de producto) son strings, aunque la plataforma use números.
- El dinero es un string decimal con punto (
"19.90") más un código ISO 4217. - Los idiomas son códigos ISO 639-1 (
es,ca,en); las monedas, ISO 4217 (EUR). - Compatibilidad hacia delante: las dos partes DEBEN ignorar los campos que no conocen. Dentro de v1 pueden aparecer campos opcionales nuevos y capacidades nuevas. Todo lo que rompa un conector existente va a
/connector/v2. - Errores de Spaidoo: estado HTTP + cuerpo
{ "errorCode": "SOME_CODE", "message": "human text" }. Un cuerpo que no encaja con la ruta es400 VALIDATION_ERROR, condetails: [ { field, message } ]. Solo401significa que la API key ya no es válida (la tienda se desconectó o se sustituyó su key): el conector debe mostrar "desconectado". Un403es de esa llamada concreta, nunca de la key: suerrorCodedice por qué (INTEGRATION_REQUIRES_PLAN, un plan que la tienda no tiene, §4.19;SHOP_NOT_VERIFIED, un dominio aún sin demostrar, §4.10), y el conector sigue conectado. ElerrorCodedel401esAPI_KEY_MISSING(sin cabeceraAuthorization: Bearer) oAPI_KEY_INVALID(una key que Spaidoo no conoce); su cuerpo conserva ademásvalid: falseyerrorpara los lectores antiguos.429llevaRetry-After; el límite general de la API respondeerrorCode: "RATE_LIMITED", y el límite propio de una ruta, su propio código (CATALOG_CHANGES_RATE_LIMIT…). Cualquier5xxo fallo de red significa "prueba más tarde": un conector DEBE seguir funcionando (la tienda nunca debe romperse) cuando Spaidoo no responde.
2.1 Los dos secretos
| Secreto | Qué es | Para qué se usa |
|---|---|---|
| API key | String opaco emitido en el emparejamiento | Authorization: Bearer <apiKey> en cada llamada conector → Spaidoo |
| Identity secret | 32 bytes aleatorios, base64url, emitido por Spaidoo | Firmas HMAC: aserciones de identidad (§5) y verificación de las llamadas Spaidoo → tienda (§6) |
Los dos son secretos de la tienda. DEBEN guardarse en el servidor y no imprimirse nunca en las páginas.
3 Emparejamiento
Una tienda se conecta con OAuth 2 y PKCE (RFC 6749, RFC 7636), como app de conector registrada. La API key nunca pasa por un navegador ni por una URL.
3.1 Registra tu conector
Registra el conector una vez en el área de partners de developers.spaidoo.com (Mis conectores) y obtienes su client_id (sc_…, público). Hay dos tipos de app:
redirectMode | Para | Vuelta (redirect_uri) |
|---|---|---|
fixed | Un conector alojado por ti o por la plataforma (el admin del comerciante no está en el dominio de la tienda) | Una de las redirectUris que registras, coincidencia exacta |
shop | Un conector instalado en cada tienda (un módulo, un plugin) | Una URL https en el dominio de la tienda que se conecta (o un subdominio suyo); no hay nada que registrar |
serverDomains: los dominios donde pueden vivir tus rutas de servidor (urls.customers) además de los de la tienda (§4.1).
adminDomains y billingPlatform los configura Spaidoo, no tú: pídelos cuando tu plataforma cobre ella misma sus apps (un marketplace de apps con facturación propia). billingPlatform: true (solo apps fixed) permite a tu conector declarar billing.platform; adminDomains son los dominios del admin de la plataforma donde pueden vivir urls.billing y urls.panel (§4.1, §4.12).
platform es texto libre que cumple ^[a-z0-9-]{2,32}$ (my-platform, my-headless-shop, acme-commerce…). Una app suspendida no conecta tiendas nuevas; las ya conectadas siguen funcionando.
Una app fixed recibe además un client_secret (scs_…), que se muestra una sola vez al crearla; puedes renovarlo desde Mis conectores (el anterior deja de funcionar al momento). Guárdalo en tu servidor: es lo que permite a tu conector dar de alta tiendas él mismo (§3.4).
3.2 El flujo
- Tu servidor genera un
statealeatorio y uncode_verifier(43–128 caracteres de[A-Za-z0-9-._~]), guarda los dos y calculacode_challenge = base64url(SHA-256(code_verifier))sin relleno. - Tu página de admin abre un popup (
window.open, unos 460×780, con el clic del comerciante) en:https://admin.spaidoo.com/connect?client_id=sc_…&redirect_uri=…&state=… &code_challenge=…&code_challenge_method=S256 &domain=shop.example.com&name=<shop name>&email=<merchant email> &mode=signup|login&verify=<urls.verify>&lang=<iso>domaines obligatorio;name,email,mode(la pestaña que se abre primero),verify(solo condomainVerification) ylangson opcionales. - Spaidoo comprueba el
client_idy laredirect_uri. Si alguno no es válido muestra el error y nunca redirige. - El comerciante se registra o inicia sesión y acepta los términos. Una tienda que ya existe en el directorio de Spaidoo solo se entrega cuando se demuestra su dominio (§3.3).
- Spaidoo envía el popup a
redirect_uri?code=…&state=…. Si el comerciante cancela:redirect_uri?error=access_denied&state=…; una petición mal formada:error=invalid_request. - Tu servidor comprueba
statey canjea el código en menos de 60 segundos (un código sirve para un solo canje):
POST /pairing/token — la única llamada sin API key:
{ "client_id": "sc_…", "code": "…", "code_verifier": "…", "redirect_uri": "<la misma>" }→ 200 { "apiKey": "…", "shopId": "…" }. Errores: 400 OAUTH_INVALID_GRANT (código desconocido, caducado o ya usado, o client_id, redirect_uri o code_verifier no coinciden), 403 CONNECTOR_APP_SUSPENDED.
- Guarda la key en el servidor y llama a
POST /handshake(§4.1). Después, la página deredirect_uriavisa a tu página de admin (postMessageawindow.opener, solo a tu propio origen y nunca con la key) y cierra el popup; tu admin muestra la tienda conectada.
3.3 Una tienda del directorio de Spaidoo
Cuando el dominio ya pertenece a una tienda del directorio de Spaidoo y la petición lleva verify, Spaidoo primero envía el popup a:
redirect_uri?state=…&verification_code=spaidoo-verify-…&resume=https://admin.spaidoo.com/connect?…Tu vuelta comprueba state, guarda el código para que urls.verify lo sirva (§4.9), conserva el code_verifier y envía el popup a resume tal como ha llegado. Spaidoo lee el código en urls.verify y sigue; el código llega después a la misma vuelta, con el mismo state. Sin verify, el comerciante demuestra el dominio a mano con un archivo (§4.9).
Una tienda nueva se conecta directamente; su conector demuestra el dominio después, con su key, antes de publicar (§4.9).
3.4 Alta automática: tu servidor da de alta la tienda (apps alojadas)
Cuando el admin de la plataforma no debe enviar al comerciante a iniciar sesión en otro sitio, una app fixed puede dar de alta la tienda desde su servidor, con los datos que la plataforma ya garantiza. La cuenta que crea no tiene contraseña: el comerciante entra en el admin de Spaidoo con POST /sso (§4.11) y allí acepta los términos de Spaidoo antes de cambiar nada.
POST /pairing/provision (sin API key):
{ "client_id": "sc_…", "client_secret": "scs_…", "domain": "shop.example.com", "name": "<nombre de la tienda>", "email": "<email del comerciante>",
"verify": "https://shop.example.com/…/verify", "lang": "es", "panel_url": "https://admin.platform.example/store/my-shop/apps/spaidoo" }→ 201 { "provisionToken": "…", "state": "new" | "claim" | "ready", "verificationCode": "spaidoo-verify-…" | null }
lang(opcional): el idioma propio de la tienda, una etiqueta corta:xx,xx-YYoxx-Yyyy(es,pt-BR,zh-Hant; también vale_). Spaidoo se queda con sus dos letras. Una tienda que se crea ahora lo toma como suyo: es el idioma en que escribe sus textos (primaryLanguage, §4.14–§4.17) si los avisos lo hablan, y el de los emails que Spaidoo envía al comerciante. Sin él, el idioma de la petición. No cambia una tienda que ya existe.panel_url(opcional,https, hasta 500): dónde gestiona el comerciante Spaidoo dentro del admin de la plataforma; el botón del email de bienvenida que envía Spaidoo lleva allí. Solo para las apps propias de Spaidoo (abajo); el de la app de un partner se ignora.resend_confirmation(opcional, booleano): el comerciante ha pedido otra vez el email deSHOP_LINK_CONFIRMATION_REQUIRED(abajo). Envíalo solo cuando él haga clic.claim: el dominio es de una tienda del directorio de Spaidoo. SirveverificationCodeenverify(§4.9) antes de completar.ready: una tienda que tu app ya conectó (la app reinstalada) vuelve tal como estaba, en su cuenta. Una tienda de la cuenta que el comerciante conectó con otra app no es tuya para cogerla: pasa porSHOP_LINK_CONFIRMATION_REQUIREDcomo una nueva, y cuando la cuenta dice que sí tu app recibe una key nueva (la de la otra app deja de funcionar).409 SHOP_LINK_CONFIRMATION_REQUIRED: el email tiene una cuenta que creó tu app y esta tienda no está en ella (otra tienda del mismo comerciante, o alguien que ha escrito ese email en su propia tienda). La plataforma responde de la tienda, no del email, así que la tienda no se añade: Spaidoo envía a esa cuenta un enlace, válido 24 horas, que la añade cuando el dueño del buzón hace clic. Hasta entonces no se crea nada. Dile al comerciante que mire su correo y vuelve a llamar aPOST /pairing/provisioncada pocos segundos mientras tanto: cuando haga clic, responde201y el flujo sigue. Volver a preguntar no envía otro email;resend_confirmation: truesí, como mucho una vez por minuto y tres veces por solicitud. Una cuenta recibe como mucho cinco solicitudes al día, y después de que conteste «no es mía» desde el enlace, tu app no provoca ningún email nuevo para ese dominio durante 30 días.409 SHOP_LINK_UNAVAILABLE: como el anterior, pero ahora no se ha podido enviar ningún email (ese «no es mía», o la cuota del día de la cuenta): díselo así al comerciante, no «mira tu correo», y vuelve a preguntar mucho más tarde (una hora).- Apps propias de Spaidoo (las que publica el propio Spaidoo en la tienda de apps de una plataforma, no las de un partner): la plataforma entrega el dominio y solo el propietario de la tienda puede instalar la app, así que esa es la prueba. Una tienda del directorio se entrega en el acto:
state: "ready",verificationCode: null, nada que servir. La app de un partner siempre demuestra el dominio. 409 EMAIL_ALREADY_REGISTERED(el email tiene una cuenta que no creó tu app) o409 SHOP_HAS_OWNER(el dominio tiene propietario): no se crea nada; envía al comerciante por el flujo del §3.2 para que inicie sesión.400 DOMAIN_NOT_VERIFIABLE:domainno es un nombre de host simple que se pueda demostrar (un puerto, una dirección IP, credenciales).429 CLAIM_RATE_LIMIT_EXCEEDED: se han pedido demasiadas pruebas para ese dominio; vuelve a intentarlo más tarde.401 OAUTH_INVALID_CLIENT: app desconocida, secreto incorrecto o app que no esfixed.403 CONNECTOR_APP_SUSPENDED.
POST /pairing/provision/complete { "client_id", "client_secret", "provision_token" } → 200 { "apiKey": "…", "shopId": "…" }. El token vale una hora, una sola vez, y solo para la app que lo pidió: 401 ONBOARDING_EXPIRED si no (empieza de nuevo con POST /pairing/provision). Para claim, Spaidoo lee antes el código en verify: 403 SHOP_NOT_VERIFIED mientras no esté.
Después guarda la key y llama a POST /handshake (§4.1), igual que tras el §3.2.
3.5 POST /shop-redact — borrar lo que trajo un conector desinstalado (apps alojadas)
Algunas plataformas piden a sus apps, un tiempo después de que una tienda las desinstale, que borren los datos de clientes de esa tienda (un webhook de cumplimiento normativo que llega, por ejemplo, 48 horas después de la desinstalación). Para entonces el conector puede haber descartado la API key de la tienda, así que una app fixed se identifica con su client secret (§3.1), como en §3.4. Sin API key:
{
"client_id": "sc_my_platform_app",
"client_secret": "scs_Q2xpZW50U2VjcmV0T2ZUaGVIb3N0ZWRBcHA",
"shopId": "7f3c2a10-5b1e-4c8a-9f0d-2e6b8a4c1d90"
}→ 200 {"customersErased": 42, "contactsErased": 7, "pushDevicesErased": 12, "productsErased": 398, "productsKept": 14, "eventsErased": 9120}
- Solo para una tienda conectada con esa app y desinstalada (
POST /uninstall, §4.4): si no,409 SHOP_STILL_CONNECTED.404 NOT_FOUNDsi la app nunca conectó esa tienda.401 OAUTH_INVALID_CLIENT,403 CONNECTOR_APP_SUSPENDEDcomo en §3.4. - Se borra todo lo que trajo el conector: el catálogo, todas las cifras de la tienda (eventos, contadores diarios, historial), todo cliente de la tienda que conozca Spaidoo con sus listas y su vinculación a una cuenta de Spaidoo (lo que hace
POST /customers/erasecon uno, §4.7), lo que guardaron los visitantes anónimos en la tienda, los emails dados a la tienda para sus avisos y los navegadores suscritos a sus notificaciones push. - Se conserva: la tienda en Spaidoo (es pública desde Spaidoo) y siempre las listas de una cuenta de Spaidoo: una vinculación rota deja a la cuenta sus productos, y un producto que guarda una cuenta se queda, fuera de venta (
productsKept). - Se puede repetir: una llamada cortada a medias la termina la siguiente; repetirla no borra nada más.
4 Conector → Spaidoo
Todas las llamadas: Authorization: Bearer <apiKey>.
4.1 POST /handshake — declarar qué puede hacer el conector
Llámalo después del emparejamiento, después de cada actualización del conector y siempre que cambie una URL o una capacidad. Es idempotente.
{
"contractVersion": 1,
"platform": { "id": "my-platform", "version": "3.2.0", "name": "My Platform" },
"connector": { "version": "2.0.0" },
"storeUrl": "https://shop.example.com",
"storeName": "My Shop",
"testShop": false,
"capabilities": {
"catalog.feed": true,
"catalog.changes": true,
"identity": true,
"customers": true,
"customerLookup": true,
"marketingConsent": true,
"customerErase": true,
"wishlistImport": false,
"push": true,
"domainVerification": true,
"storefront.saveAnchors": true,
"billing.platform": true,
"panel.widget": true
},
"urls": {
"identity": "https://shop.example.com/spaidoo/identity",
"login": "https://shop.example.com/login?back={back}",
"customers": "https://shop.example.com/spaidoo/customers",
"marketingConsent": "https://shop.example.com/spaidoo/marketing-consent",
"verify": "https://shop.example.com/spaidoo/verify",
"pushWorker": "https://shop.example.com/spaidoo/push-sw.js",
"billing": "https://admin.platform.example/store/my-shop/apps/spaidoo/plans",
"panel": "https://admin.platform.example/store/my-shop/apps/spaidoo"
},
"storefront": {
"pushScope": "/spaidoo-push/",
"domains": ["shop.example.com", "my-shop.platform.example"],
"excludePaths": ["^/checkout", "^/cart"]
},
"identitySecretFingerprint": "<sha256 hex of the identity secret it holds, or null>"
}- Toda URL DEBE ser
https. Las URL de escaparate (identity,login,pushWorker), que el widget llama desde la página del cliente, yverify, que demuestra el dominio, DEBEN estar en uno de los dominios de la tienda. Las URL de servidor (customers,marketingConsent), que Spaidoo llama firmadas, PUEDEN estar también en uno de losserverDomainsde la app con la que se conectó la tienda (§3.1). Una URL solo es obligatoria para una capacidad declarada que la necesite. storeName(opcional, hasta 100 caracteres): el nombre de la tienda en la plataforma, tal como lo ven sus clientes. Spaidoo renombra la tienda cuando cambia allí, para que los textos del widget sigan el cambio («My Shop te escribirá…»). Un nombre que el comerciante haya puesto en el admin de Spaidoo se mantiene hasta que el de la plataforma vuelva a cambiar. Envíalo en cada handshake; vuelve a enviar el handshake cuando la tienda cambie de nombre.testShop:truecuando la plataforma indica que es una tienda de desarrollo o de pruebas (una tienda de desarrollo de partner, una instalación de staging). Queda fuera de las cifras de Spaidoo y, si lleva 30 días desinstalada sin haber verificado nunca su dominio, Spaidoo la elimina con sus datos. Si no se envía, valefalse.storefront.domains: otros dominios en los que se sirve el escaparate (un subdominio de la plataforma y el dominio propio de la tienda, por ejemplo), solo el nombre de host. El widget funciona en todos; para publicar sigue haciendo falta la prueba del dominio destoreUrl(§4.9).loginDEBE contener el marcador literal sin codificar{back}; el widget lo sustituye por la página a la que volver.storefront.excludePaths: expresiones regulares (sin distinguir mayúsculas y minúsculas) sobre la ruta + query donde el widget no debe ejecutarse nunca. El widget no se carga nunca en el carrito, el checkout ni las páginas de pago: inclúyelas todas (como en el ejemplo). El conector DEBERÍA además no imprimir el script ahí (§7); esta lista es la red de seguridad. El loader de Spaidoo también se salta por su cuenta las rutas habituales de carrito y checkout (/cart/,/checkout/,/carrito/…), pero las de una plataforma pueden ser otras.storefront.pushScope(conpush): el alcance del service worker de push (§7.1). Si no se envía:/spaidoo-push/.- Conectar no es publicar. Una tienda que se conecta ahora (su primer handshake, o el primero después de
POST /uninstall) empieza con el widget enpreview(§4.10), salvo que ya estuviera enlive: reconectar una tienda pública no les quita el widget a sus clientes. Una actualización del conector no cambia nada. - Un dominio declarado (
storeUrlostorefront.domains) que ya pertenece a otra tienda de Spaidoo con propietario demostrado se deja fuera de los dominios del widget, sin error; el soporte de Spaidoo lo revisa. El resto del handshake se aplica. identitySecretFingerprint: permite que un conector que ha perdido su secreto (reinstalado, restaurado desde una copia de seguridad) obtenga uno nuevo por su cuenta.null= no tiene ninguno.platform.name(opcional, hasta 50 caracteres): el nombre de la plataforma tal como lo conocen los comerciantes. El admin de Spaidoo lo usa en sus textos («tu plan lo cobra …»);platform.idsigue siendo el id técnico e informativo.panel.widgetyurls.panel: el conector tiene panel propio en el admin de la plataforma, donde el comerciante instala y configura el widget, ve su estado e importa listas. El admin de Spaidoo oculta entonces las pantallas que lo repetirían y enlaza aurls.panel. Comourls.billing,urls.panelDEBE serhttpsen uno de losadminDomainsde la app; sin ellos la capacidad se rechaza (se omite). Cualquier plataforma con panel puede declararla.billing.platformyurls.billing: la plataforma cobra el plan de Spaidoo de la tienda (§4.12).urls.billinges la página del admin donde el comerciante elige o cambia el plan; el admin de Spaidoo lo envía allí en lugar de ofrecer su propio pago. DEBE serhttpsen uno de losadminDomainsde la app con la que se conectó la tienda (§3.1). La capacidad solo se acepta si Spaidoo ha habilitadobillingPlatformen esa app; si no, se rechaza como cualquier capacidad desactivada (se omite, no es un error).
Respuesta 200:
{
"shopId": "7f3c…",
"contractVersion": 1,
"capabilities": { "catalog.changes": true, "identity": true, "…": "…" },
"identitySecret": "b64url…"
}capabilitiesson las que Spaidoo ha aceptado. El conector debe comportarse según esta lista. Una capacidad se rechaza (se omite, no es un error) cuando Spaidoo la tiene desactivada;customers,customerLookup,marketingConsentywishlistImportse rechazan sinidentity;billing.platformse rechaza si la app no tienebillingPlatform.customerLookupusaurls.customers.identitySecretestá presente cuando el conector debe guardar uno nuevo (§4.2).
Errores: 400 CONNECTOR_CATALOG_REQUIRED (sin catalog.feed), 400 CONNECTOR_URL_INVALID con field (falta la URL de una capacidad declarada, no es https en un dominio permitido, o login sin el {back} sin codificar; para billing.platform, solo si la app tiene billingPlatform), 400 CONNECTOR_EXCLUDE_PATH_INVALID.
4.2 Entrega y rotación del identity secret
- Spaidoo emite el secreto en el handshake y lo devuelve en las respuestas de
/handshakey/statushasta que el conector lo confirma. POST /identity-secret/ack{ "fingerprint": "<sha256 hex of the secret>" }→200 { "acknowledged": true }(falsesi no es el secreto actual). El conector DEBE confirmar cada secreto que recibe, después de guardarlo.POST /identity-secret/rotate→200 { "shopId": "…", "identitySecret": "…" }: el comerciante pide uno nuevo.409 CONNECTOR_NOT_CONFIGUREDsi Spaidoo no aceptóidentitypara esta tienda.- Mientras Spaidoo tenga la identidad desactivada,
ackyrotateresponden404 NOT_FOUND. - Periodo de gracia: después de una rotación, Spaidoo sigue aceptando aserciones firmadas con el secreto anterior y sigue firmando sus propias llamadas con el secreto anterior hasta que se confirma el nuevo, y durante 10 minutos después de la confirmación. Un conector que pierde una respuesta sigue funcionando.
4.3 GET /status — latido y estado
Llámalo cuando el comerciante abra el panel del conector (y, si no, como mucho cada pocos minutos).
{
"shopId": "7f3c…",
"identitySecret": "b64url…",
"connector": { "contractVersion": 1, "platform": "my-platform", "version": "2.0.0", "capabilities": { "catalog.feed": true }, "urls": {}, "storefront": { "excludePaths": [] } },
"store": {
"name": "Mi tienda", "plan": "growth", "status": "active", "verified": true, "identityOn": true,
"scriptUrl": "https://widget.spaidoo.com/loaders/7f3c….js",
"adminUrl": "https://admin.spaidoo.com",
"billing": { "provider": "platform", "plan": "growth", "status": "trialing" },
"termsAccepted": true, "termsVersion": "2026-09-10",
"termsUrls": { "es": "https://…/es/", "en": "https://…/en/" },
"stats": { "savedProducts": 1840, "widgetOpens": 9120, "historyProducts": 15230, "catalogueProducts": 412, "productVisits": 318,
"audience": { "total": 640, "shopIdentified": 210, "spaidooAccount": 95, "anonymous": 335 }, "followers": 0,
"alertsSent": 96, "alertClicks": 21 },
"feeds": [ { "language": "es", "url": "https://shop.example.com/spaidoo/feed?lang=es", "type": "url", "source": "plugin" } ],
"feedHistory": [ { "initProcess": "2026-10-04T06:00:00.000Z", "endProcess": "2026-10-04T06:00:41.000Z", "results": [ { "language": "es", "type": "url" } ] } ],
"pluginConfig": {
"mode": "live", "domains": ["shop.example.com"],
"desktop": { "showButton": true, "position": "bottom-right", "orientation": "vertical", "chatAI": false, "showSearchButton": false },
"mobile": { "showButton": true, "position": "custom", "offsets": { "bottom": 96, "right": 16 }, "orientation": "vertical", "chatAI": false, "showSearchButton": false },
"theme": "dark", "accent": "#0A0A0A", "icon": "bookmark", "productCircle": true,
"saveAnchors": { "position": "top-right", "product": true, "list": true, "header": true },
"searchProvider": { "type": "none" }, "aiProvider": { "type": "none" }
}
}
}| Campo | Qué es |
|---|---|
identitySecret | Solo mientras haya un secreto por entregar (§4.2) |
connector | Lo que Spaidoo tiene del último handshake (ver más abajo) |
store.plan | El plan que la tienda usa ahora: starter · growth · pro. Puede ser superior al cobrado (una prueba o una concesión de Spaidoo) |
store.status | active (la tienda aparece en el portal de Spaidoo) o pending_review. No detiene el widget |
store.verified | El dominio está demostrado (§4.9): hace falta para publicar (live) |
store.identityOn | La identidad (§5) funciona ahora mismo para esta tienda |
store.billing | { provider, plan, status }: quién cobra el plan (platform · stripe · internal), el plan cobrado y su estado con el vocabulario de §4.12 (active · trialing · frozen · cancelled). El detalle: GET /billing (§4.12) |
store.termsAccepted | La tienda ha aceptado la versión vigente de las condiciones de Spaidoo. Mientras sea false, las escrituras de §4.10 y las importaciones (§4.8) responden 409 TERMS_NOT_ACCEPTED (§4.13) |
store.termsVersion | La versión vigente de las condiciones (AAAA-MM-DD). Una versión nueva vuelve a poner termsAccepted a false |
store.termsUrls | El texto de las condiciones, por idioma (es, en): enlázalo junto a la aceptación |
store.stats | Totales para el panel (ver más abajo) |
store.feeds | Los feeds de catálogo que tiene Spaidoo, por idioma: { language, url, type: "url" | "upload", source?: "plugin" }. source: "plugin" = publicado por el conector (§4.5) |
store.feedHistory | Las 10 últimas lecturas del catálogo, la más reciente primero: { initProcess, endProcess, results: [ { language, type, error?, notReady?, … } ], retryAt? }. Aquí las fechas son cadenas ISO 8601. Informativo: pueden aparecer más campos |
store.catalogSetup | Cómo va el primer catálogo de la tienda: { state, products? }, ver §4.5 |
store.pluginConfig | Los ajustes del widget: mode (off · preview · live), domains, desktop / mobile (el botón flotante, ver más abajo), theme, accent, iconColor?, satelliteColor?, satelliteIconColor?, icon, productCircle, saveButton? (ver más abajo), customCss? (los estilos propios de la tienda por pieza, §4.10.1), librarySelector? (el elemento propio que abre la lista, §4.10), searchHeader y searchSelector? (abrir el buscador desde la cabecera y el elemento propio que lo abre, §4.10), saveAnchors (ver más abajo), hints (los textos del widget que la tienda ha cambiado, §4.10; una pieza que no viene dice el texto propio del widget), hintLanguages ({ languages, primary }: los idiomas en que la tienda escribe esos textos, el suyo primero), searchProvider? / aiProvider?, productAnchor? / actionsAnchor?, brand? (todos ver más abajo). Un campo marcado con ? no viene si no está configurado |
store.stats:
| Campo | Qué cuenta |
|---|---|
savedProducts | Productos guardados en las listas de la tienda, ahora |
widgetOpens | Veces que se ha abierto el widget, desde siempre |
historyProducts | Productos en el historial de navegación de los clientes |
catalogueProducts | Productos activos del catálogo que tiene Spaidoo |
productVisits | Visitas que Spaidoo ha enviado a los productos de la tienda en los últimos 30 días (widget, avisos, carruseles, búsqueda, push) |
audience | { total, shopIdentified, spaidooAccount, anonymous }: las personas con productos guardados, según cómo se las conoce |
alertsSent | Avisos (bajada de precio, vuelta al stock, recordatorios) enviados a los clientes de la tienda en los últimos 30 días |
alertClicks | Avisos en los que el cliente hizo clic (cada aviso cuenta una vez), últimos 30 días |
followers | Obsoleto (se mantiene para conectores antiguos). No lo muestres |
scriptUrl es lo que el conector imprime en la tienda (§7). Puede cambiar: usa siempre el último.
store.pluginConfig.saveAnchors dice dónde quiere el comerciante el icono de guardar sobre las fotos de producto, y se configura en el panel de Spaidoo. Solo lo necesita un conector que coloca él mismo los anclajes sobre las fotos (§7):
"saveAnchors": { "position": "top-right", "product": true, "list": true, "header": true, "listPhoto": ".card__media", "productPhoto": ".product__media" }position: la esquina de la foto,top-right·top-left·bottom-right·bottom-left.product/list: si el icono se muestra en la ficha de producto y en las tarjetas de producto. El widget ya no dibuja nada donde está desactivado; el conector también puede no imprimir esos anclajes.header: si el conector pone en la cabecera de la tienda, junto al carrito, un icono que abre la lista del cliente (spaidoo:show-sectioncon{ section: "library" }). Toma el aspecto de los iconos de la cabecera del tema; si no encuentra el carrito, no pone ninguno.listPhoto/productPhoto(opcional): el selector CSS del elemento que contiene la foto, para temas que el conector no sabe leer. Si no viene, el conector encuentra la foto por sí mismo.productSize/listSize(opcional): el diámetro del botón en px en la ficha y en los listados (28–80). Si no viene, el del widget (34).productStrokeWidth/listStrokeWidth(opcional): el grosor del trazo del símbolo en la ficha y en los listados, en su caja de 24 unidades (1–3, de 0,25 en 0,25). Si no viene, el del widget (2).
El diseño del icono (pluginConfig.saveButton, si el comerciante tiene uno propio) y su tamaño también los aplica el widget: el conector no le da estilos al icono. El conector puede cambiar todo esto desde su panel con POST /widget/save-buttons (§4.10).
El resto de store.pluginConfig:
| Campo | Qué es |
|---|---|
desktop / mobile | El botón flotante por dispositivo: { showButton, position, orientation, offsets?, chatAI, showSearchButton }. position: bottom-left · bottom-right · bottom-center (solo móvil) · custom. Con custom, offsets son sus píxeles desde los bordes de la pantalla, solo los lados definidos: { top | bottom, left | right } (si falta un lado: 20 px desde abajo / desde la derecha). chatAI / showSearchButton: los botones del asistente y del buscador. Se cambian con POST /widget/placement y POST /widget/search (§4.10) |
saveButton | El diseño propio del botón de guardar, si el comerciante tiene uno: { idle?, saved? }, cada uno { background?, icon?, fill? } como en POST /widget/save-buttons (§4.10). Si no viene: los colores del botón flotante |
searchProvider / aiProvider | El buscador y el asistente que usa el widget ahora: { type, customSelector? }, type none · spaidoo (el propio de Spaidoo) · custom (el propio de la tienda, que se abre con customSelector) · doofinder · kimera (motores de terceros). El buscador de Spaidoo está en todos los planes, sin cuotas. Spaidoo no ofrece ahora asistente propio: aiProvider solo trae uno vinculado. Si no vienen: nunca se configuraron |
productAnchor / actionsAnchor | Botones propios de Spaidoo colocados en la página de la tienda con un selector (un botón de guardar junto al de comprar; iconos fijos de la lista, el buscador y el asistente), que se configuran en el admin de Spaidoo; solo vienen si están activados. Informativos: muestra que están activados y enlaza al admin de Spaidoo para cambiarlos (POST /sso, widget-setup). Su forma puede crecer |
brand | Obsoleto: antiguos ajustes de color que el widget ya no usa. Ignóralo |
connector es lo que Spaidoo tiene del último handshake (contractVersion, platform, platformName si se declaró, version, capabilities aceptadas, urls, storefront), o null antes del primero. Nunca el secreto.
4.3.1 GET /stats — las cifras del panel por periodo
GET /stats?period=7d|30d|90d (por defecto 30d) — lo que la tienda ha obtenido del widget en los últimos 7, 30 o 90 días, comparado con el periodo anterior, para la pantalla de inicio del conector.
GET /stats?from=AAAA-MM-DD&to=AAAA-MM-DD — cualquier rango de días UTC, los dos incluidos: hoy, ayer, este mes, el mes pasado, los últimos 12 meses o el que elija el comerciante. Responde period: "custom" y lo compara con los mismos días justo antes. from y to van juntos y mandan sobre period; to como mucho hoy y como mucho 366 días. Si no, 400 STATS_RANGE_INVALID. Se guarda 5 minutos por rango.
{
"period": "30d",
"from": 1756944000,
"to": 1759536000,
"timezone": "UTC",
"totals": {
"saves": 412,
"savers": 133,
"widgetOpens": 2210,
"productVisits": 318,
"alertsSent": 96,
"alertClicks": 21
},
"previous": {
"saves": 350,
"savers": 120,
"widgetOpens": 1980,
"productVisits": 270,
"alertsSent": 80,
"alertClicks": 15
},
"series": [
{
"date": "2026-09-04",
"saves": 12,
"productVisits": 9
},
{
"date": "2026-09-05",
"saves": 15,
"productVisits": 11
}
],
"topProducts": [
{
"productId": "987",
"product": { "name": "Abrigo de lana", "image": "https://shop.example.com/media/987.jpg", "url": "https://shop.example.com/products/abrigo-de-lana" },
"saves": 31
},
{
"productId": "111",
"product": null,
"saves": 24
}
],
"topViewed": [
{
"productId": "111",
"viewers": 58
},
{
"productId": "987",
"viewers": 41
}
],
"updatedAt": 1759500000
}| Campo | |
|---|---|
period | 7d, 30d, 90d, o custom si se ha pedido por from/to |
from / to | El periodo, en segundos Unix: días UTC enteros (to es el final del último día; en los periodos fijos, el de hoy). Los días son UTC porque los contadores diarios de Spaidoo se guardan así |
totals | saves (productos guardados), savers (personas que han guardado), widgetOpens, productVisits (visitas que Spaidoo ha enviado a los productos de la tienda), alertsSent, alertClicks (como en §4.3) |
previous | Los mismos totales del periodo justo anterior, de la misma duración |
series | Una fila por día del periodo, incluidos los días sin actividad: { date: "AAAA-MM-DD", saves, productVisits } |
topProducts | Los 5 productos más guardados del periodo: { productId, product, saves }, el id de producto del feed. product: { name, image, url } del catálogo de Spaidoo, en el idioma propio de la tienda (image puede ser null), la misma ficha que en GET /events (§4.18); null si el producto ya no está en el catálogo |
topViewed | Los 5 productos más vistos del periodo, del historial que el widget guarda a cada cliente: { productId, product, viewers }, las personas que han visto la ficha (una por persona, con su última visita en el periodo) |
updatedAt | Cuándo se calcularon las cifras. Se guardan 5 minutos: preguntar más a menudo devuelve la misma respuesta |
Los mismos eventos que los informes del admin de Spaidoo: los dos muestran las mismas cifras. Los informes completos: POST /sso con intent: "reports" (§4.11).
4.3.2 GET /analytics — la página de analítica
?period=7d|30d|90d (por defecto 30d), o ?from=AAAA-MM-DD&to=AAAA-MM-DD como en /stats (§4.3.1). Lo que la página de analítica del conector necesita además de /stats: el periodo anterior día a día, las oportunidades, a quién puede llegar la tienda, cómo vuelven y desde dónde guardan.
{
"period": "30d",
"from": 1756944000,
"to": 1759536000,
"timezone": "UTC",
"previousSeries": [
{
"date": "2026-08-05",
"saves": 9,
"productVisits": 7
},
{
"date": "2026-08-06",
"saves": 11,
"productVisits": 10
}
],
"topProducts": [
{
"productId": "987",
"product": { "name": "Abrigo de lana", "image": "https://shop.example.com/media/987.jpg", "url": "https://shop.example.com/products/abrigo-de-lana" },
"saves": 31
},
{
"productId": "111",
"product": null,
"saves": 24
}
],
"topViewed": [
{
"productId": "111",
"viewers": 58
},
{
"productId": "987",
"viewers": 41
}
],
"opportunities": {
"viewedNotSaved": {
"total": 2,
"products": [
{
"productId": "555",
"viewers": 40,
"savers": 3
},
{
"productId": "222",
"viewers": 17,
"savers": 1
}
]
},
"priceDropped": {
"people": 38,
"products": [
{
"productId": "987",
"savers": 21
},
{
"productId": "333",
"savers": 17
}
]
},
"dormant": {
"people": 54,
"days": 15
},
"savedNotClicked": {
"total": 12,
"products": [
{
"productId": "444",
"savers": 6
},
{
"productId": "111",
"savers": 4
}
]
},
"revisited": {
"people": 27,
"products": [
{
"productId": "987",
"people": 11
},
{
"productId": "111",
"people": 6
}
]
},
"removed": {
"total": 5,
"products": [
{
"productId": "222",
"removals": 9
},
{
"productId": "555",
"removals": 4
}
]
},
"topClients": {
"people": 12,
"minSaves": 3
},
"unavailable": {
"people": 7,
"soldOutPeople": 5,
"removedPeople": 2,
"products": [
{
"productId": "333",
"savers": 5,
"reason": "sold_out"
}
]
},
"sharedLists": {
"total": 4,
"products": [
{
"productId": "987",
"lists": 3
},
{
"productId": "111",
"lists": 1
}
]
}
},
"reach": {
"total": 312,
"shopCustomers": 120,
"spaidooAccounts": 45,
"anonymous": 160,
"email": 128,
"push": 64
},
"returning": {
"value": 97,
"previous": 81
},
"savedRevisits": {
"value": 64,
"previous": 52
},
"listAdds": {
"value": 143,
"previous": 120
},
"communication": {
"alerts": {
"sent": 340,
"seen": 281,
"clicked": 58,
"previousSent": 303,
"previousClicked": 44
},
"notifications": {
"sent": 4,
"seen": 3,
"clicked": 1
},
"recovered": 21,
"board": {
"impressions": 1240,
"clicks": 96
},
"carousels": {
"impressions": 8400,
"clicks": 310
}
},
"surfaces": [
{
"surface": "launcher",
"saves": 214
},
{
"surface": "product",
"saves": 158
},
{
"surface": "listing",
"saves": 40
},
{
"surface": "library",
"saves": 0
}
],
"updatedAt": 1759500000
}| Campo | |
|---|---|
previousSeries | El periodo anterior día a día, como series de /stats: para dibujar los dos periodos uno encima del otro |
topProducts / topViewed | Como en /stats, hasta 10. Cada entrada con productId, aquí y en opportunities.*.products, lleva también su ficha product (§4.3.1) |
opportunities.viewedNotSaved | Productos que han visto 3 personas o más (historial del widget) y ha guardado como mucho 1 de cada 5: { productId, viewers, savers }. total cuenta todos; la lista, hasta 10 |
opportunities.priceDropped | Productos guardados que han bajado de precio en el periodo, y people, las personas que los tienen en sus favoritos |
opportunities.dormant | Personas con favoritos sin actividad en la tienda desde hace days días |
opportunities.savedNotClicked | Productos guardados en el periodo que nadie ha vuelto a abrir desde que los guardó: { productId, savers } |
opportunities.revisited | Personas que han vuelto a mirar un producto que ya tenían guardado (su historial, más de una hora después de guardarlo) y, por producto, cuántas: { people, products: [{ productId, people }] }. Las más cerca de comprar; los avisos de «visita sin compra» son para ellas |
opportunities.removed | Los productos más quitados de favoritos en el periodo: { total, products: [{ productId, removals }] } |
opportunities.topClients | Ahora, sin periodo: cuántas personas tienen minSaves productos guardados o más. Solo el número, nunca quiénes |
opportunities.unavailable | Ahora: productos guardados que nadie puede comprar, agotados (ninguna variante con stock, como los carruseles) o que la tienda ya no ofrece (inactivos en su catálogo). people en total, soldOutPeople y removedPeople por motivo, y cada producto con su reason (sold_out · removed) |
opportunities.sharedLists | Ahora: productos en listas compartidas (ListIx), por cuántas de ellas los tienen: { total, products: [{ productId, lists }] } |
reach | A quién puede llegar la tienda ahora (sin periodo): total, por identidad (shopCustomers, spaidooAccounts, anonymous; una persona vinculada cuenta en las dos primeras), y cuántos tienen email (con consentimiento) o push |
returning | Personas que han vuelto a la tienda teniendo algo guardado de antes: { value, previous } |
savedRevisits | Productos guardados que la persona ha vuelto a ver (la ficha, más de una hora después de guardarlo); cada persona y producto cuenta una vez: { value, previous } |
listAdds | Productos añadidos a listas en el periodo, cada lista cuenta (el mismo producto en 5 listas son 5) y solo los que siguen en ellas: { value, previous }. A diferencia de saves, que cuenta cada producto una vez por persona |
communication | La comunicación de la tienda en el periodo, sumada (se gestiona en el admin de Spaidoo): alerts (avisos automáticos: enviados, vistos, con clic, y los del periodo anterior), notifications (notificaciones escritas a mano), recovered (productos avisados a los que la persona volvió en 7 días), board (impresiones y clics del tablón) y carousels (de los carruseles) |
surfaces | Guardados del periodo según desde dónde: launcher (botón flotante), product (botón de la ficha), listing (botón en el listado), library (dentro del panel). Solo cuentan los guardados desde que el widget lo envía |
Las oportunidades llevan a una acción en Spaidoo (avisar, recordar): el conector la abre con POST /sso (§4.11). Calculado con los informes del admin de Spaidoo y guardado 5 minutos, los tres periodos a la vez.
4.3.3 GET /search-analytics — qué buscan los clientes de la tienda
?period=7d|30d|90d (por defecto 30d), o ?from=AAAA-MM-DD&to=AAAA-MM-DD como en /stats (§4.3.1). Las búsquedas que hacen los clientes en el buscador de Spaidoo de la tienda (§4.10 /widget/search) y los clics en sus resultados. Spaidoo las suma cada hora: lo de la última hora puede no estar todavía.
Por plan. Growth y Pro reciben el informe entero (access: "full"). Starter recibe una muestra (access: "teaser"): siempre los últimos 7 días, pida lo que pida; el número de búsquedas, las 3 más buscadas y las 3 primeras sin resultados (solo la búsqueda, cuántas veces y cuántos resultados), cuántas más hay en cada lista (more) y report: null. El plan se lee en cada petición: al subir de plan, la siguiente respuesta ya es el informe entero.
{
"access": "full",
"period": "30d",
"from": 1756944000,
"to": 1759536000,
"timezone": "UTC",
"searches": { "value": 1240, "previous": 1105 },
"topQueries": [
{ "q": "abrigo", "searches": 182, "results": 24, "clickedSearches": 121, "clicks": 160, "averagePosition": 1.8 },
{ "q": "botas mujer", "searches": 97, "results": 11, "clickedSearches": 15, "clicks": 17, "averagePosition": 4.6 }
],
"zeroResults": [
{ "q": "zapatillas niño", "searches": 23, "results": 0 },
{ "q": "chubasquero", "searches": 9, "results": 0 }
],
"more": { "topQueries": 412, "zeroResults": 37 },
"report": {
"totals": { "searches": 1240, "zeroResults": 96, "filtered": 210, "clickedSearches": 702, "clicks": 915, "views": 1018 },
"previous": { "searches": 1105, "zeroResults": 101, "filtered": 188, "clickedSearches": 610, "clicks": 790, "views": 930 },
"series": [
{ "date": "2026-09-04", "searches": 38, "zeroResults": 3, "clicks": 29 },
{ "date": "2026-09-05", "searches": 44, "zeroResults": 2, "clicks": 31 }
],
"noClick": [
{ "q": "botas mujer", "searches": 97, "results": 11, "clickedSearches": 15, "clicks": 17, "averagePosition": 4.6 }
],
"trending": [
{ "q": "lino", "searches": 41, "previous": 12 },
{ "q": "sandalias plataforma", "searches": 16, "previous": 0 }
],
"products": [
{
"productId": "987",
"product": { "name": "Abrigo de lana", "image": "https://shop.example.com/media/987.jpg", "url": "https://shop.example.com/products/abrigo-de-lana" },
"clicks": 88,
"averagePosition": 1.4
},
{ "productId": "111", "product": null, "clicks": 41, "averagePosition": 3.2 }
],
"positions": { "1": 402, "2": 188, "3": 97, "4": 61, "5": 40, "6": 31, "7": 22, "8": 18, "9": 14, "10": 11, "11+": 31 }
},
"updatedAt": 1759500000
}En Starter:
{
"access": "teaser",
"period": "7d",
"from": 1758931200,
"to": 1759536000,
"timezone": "UTC",
"searches": { "value": 286, "previous": null },
"topQueries": [
{ "q": "abrigo", "searches": 41, "results": 24 },
{ "q": "botas mujer", "searches": 22, "results": 11 },
{ "q": "bufanda", "searches": 17, "results": 6 }
],
"zeroResults": [
{ "q": "zapatillas niño", "searches": 6, "results": 0 },
{ "q": "chubasquero", "searches": 3, "results": 0 },
{ "q": "guantes tactiles", "searches": 2, "results": 0 }
],
"more": { "topQueries": 131, "zeroResults": 14 },
"report": null,
"updatedAt": 1759500000
}| Campo | |
|---|---|
access | full (Growth, Pro) o teaser (Starter) |
period / from / to / timezone | Como en /stats (§4.3.1). En Starter, siempre 7d |
searches | Búsquedas del periodo: { value, previous }, previous el periodo anterior (null en Starter). Una búsqueda cuenta una vez por página vista, aunque sus resultados cambien con un filtro |
topQueries | Las más buscadas: { q, searches, results, clickedSearches, clicks, averagePosition }, hasta 20 (3 en Starter, solo q, searches y results). averagePosition, dónde se pulsaron sus resultados de media (1 = el primero; null sin clics). q tal como se buscó, en minúsculas y con espacios simples; results, lo que encontró la última vez |
zeroResults | Las que no encontraron nada, por cuántas veces: { q, searches, results: 0 }, hasta 20 (3 en Starter). Lo que los clientes quieren y la tienda no tiene, o tiene con otro nombre |
more | Cuántas búsquedas distintas quedan fuera de cada lista: { topQueries, zeroResults } |
report.totals | searches, zeroResults, filtered (con algún filtro puesto), clickedSearches (con al menos un clic en un resultado), clicks, views (páginas vistas en las que se buscó) |
report.previous | Los mismos totales del periodo justo anterior, de la misma duración |
report.series | Una fila por día del periodo, incluidos los días sin búsquedas: { date, searches, zeroResults, clicks } |
report.noClick | Buscadas 2 veces o más, con resultados, y con clic en como mucho 1 de cada 5: { q, searches, results, clickedSearches, clicks, averagePosition }, hasta 20. Los resultados no convencen |
report.trending | Hasta 10 búsquedas, con 2 o más en el periodo, que suben frente al periodo anterior o son nuevas (previous: 0): { q, searches, previous }, primero la que más sube. Vacía si en el periodo anterior no hubo ninguna búsqueda |
report.products | Los 10 productos más pulsados desde el buscador: { productId, product, clicks, averagePosition }, con su ficha product (§4.3.1) y la posición media en la que se pulsaron (1 = el primero) |
report.positions | Clics por la posición del resultado pulsado: "1" … "10" y "11+". Si se pulsa mucho más abajo del primero, el orden de los resultados se puede mejorar |
updatedAt | Cuándo se calculó. Se guarda 5 minutos |
Anónimo: Spaidoo no sabe quién buscó, solo qué y cuántas veces. Solo cuentan las búsquedas desde la página de la propia tienda.
4.3.3.1 GET /search-analytics/find — una lista con un texto
Solo Growth y Pro: en Starter responde 403 SEARCH_FILTER_REQUIRES_PLAN. ?list=topQueries|zeroResults|noClick|trending|products&contains=<texto> (1 a 100 caracteres), más el periodo como en /search-analytics. Devuelve solo lo de esa lista que contiene el texto, sin distinguir mayúsculas ni acentos: las búsquedas por su texto y los productos por su nombre. Mismos límites y filas que la lista del informe (20 búsquedas, 10 en trending y products) y more, cuántos más coinciden (0 en noClick y trending).
{ "list": "topQueries", "contains": "camis", "rows": [ { "q": "camisa", "searches": 12, "results": 3, "clickedSearches": 7, "clicks": 8, "averagePosition": 2.1 } ], "more": 0 }4.4 POST /uninstall — {} → 204
El conector se está desinstalando, o el comerciante desconecta Spaidoo desde el panel del conector: las dos cosas son la misma llamada. Spaidoo deja de leer el catálogo que publicó el conector (los feeds añadidos a mano en el admin de Spaidoo se quedan), retira de la venta los productos si ese era el único catálogo, apaga la identidad y regenera el loader. La API key sigue funcionando: los datos se conservan y un nuevo POST /handshake continúa donde se quedó (una reconexión). La key sí cambia cuando la tienda cambia de manos: conectada con otra app (§3), o de otra cuenta que ha demostrado su dominio. Entonces la key vieja recibe 401 y el conector se vuelve a emparejar.
4.5 Catálogo — catalog.feed (obligatoria)
PUT /catalog/feeds
{ "feeds": [ { "language": "es", "url": "https://shop.example.com/spaidoo/feed?lang=es" } ] }La lista completa: un idioma que falte en ella se elimina. Hasta 50 feeds, cada url http(s) de hasta 1000 caracteres. Spaidoo lee cada feed aproximadamente una vez al día.
Mientras el conector esté conectado, el catálogo es del conector: el admin de Spaidoo muestra los feeds en solo lectura, y cambiar o subir un feed allí responde 409 FEEDS_MANAGED_BY_CONNECTOR (pedir que se vuelvan a leer sigue funcionando). Después de POST /uninstall (§4.4) el comerciante vuelve a gestionar los feeds.
POST /catalog/feeds/read → 202 { "queued": true } — "leer ahora" (p. ej. un botón en el panel). 429 { "queued": false, "retryInSeconds": n } con Retry-After si se vuelve a pedir demasiado pronto (3 minutos).
El feed es un feed de productos de Google Merchant (RSS 2.0 o Atom, espacio de nombres g: opcional) con un <item>/<entry> por variante:
| Campo | Obligatorio | Notas |
|---|---|---|
g:id | ✅ | Id de la variante |
g:item_group_id | si hay variantes | El id de producto para Spaidoo (una fila por producto). Sin él, g:id es el id de producto |
g:title, g:link | ✅ | Localizados; link es la URL canónica del producto |
g:price | ✅ | "19.90 EUR": la moneda base de la tienda |
g:sale_price | Misma moneda que g:price | |
g:availability | ✅ | in_stock · out_of_stock · preorder · backorder |
g:image_link, g:additional_image_link | ||
g:description, g:brand, g:product_type (A > B > C), g:color, g:size, g:mpn | ||
spaidoo:price currency="USD" | Espacio de nombres https://spaidoo.com/ns/feed/1. Precio exacto en cada una de las otras monedas en las que vende la tienda (repetible) | |
spaidoo:sale_price currency="USD" |
El id de producto es el que se usa en el resto de este contrato (data-sp-id, catalog.changes, importación de wishlists).
Mientras se genera un feed grande, responde 202 (o 503/429) con Retry-After: <seconds>: Spaidoo vuelve entonces y no lo trata como un catálogo vacío. Cualquier otro error conserva el catálogo anterior.
El primer catálogo. Una tienda sin productos que publica sus feeds no enseña el widget hasta que Spaidoo ha leído su catálogo: sin él, un cliente no podría guardar nada. Da igual el modo (§4.10) y que el conector active el widget en la tienda. store.catalogSetup (§4.3) dice cómo va, para que el panel lo enseñe:
state | Qué significa | ¿Widget visible? |
|---|---|---|
reading | Spaidoo espera a leer el feed | No |
importing | Los productos están entrando | No |
failed | No se pudo leer ningún feed, ni tras tres reintentos en unos 15 minutos (mientras tanto sigue en reading o importing). Ofrece volver a intentarlo: POST /catalog/feeds/read | No |
search | El catálogo ya está (products, cuántos); se prepara el buscador | Sí, sin buscador |
empty | La tienda aún no tiene productos | Sí, sin buscador |
ready | Terminado. También es el valor de cualquier tienda que ya tenía catálogo | Sí |
Con el primer paquete de búsqueda, el buscador de Spaidoo se enciende solo, salvo que la tienda haya elegido antes otra cosa, también apagarlo. Hasta entonces, encenderlo no enseña el botón: aparece cuando el paquete está listo. Las lecturas diarias no vuelven a cerrar el widget.
4.5.1 GET /catalog/products — los productos de la tienda, tal como los tiene Spaidoo
El catálogo de la tienda tal como Spaidoo lo leyó de los feeds: un selector de productos para el panel del conector (avisos, carruseles) y los nombres y fotos de los productos que ya eligió, sin preguntar a su plataforma. Solo los productos de la tienda de la API key, y solo los que siguen en su feed. Sin capacidad.
GET /catalog/products?q=camisa— los títulos que contienenq(de 2 a 100 caracteres), en cualquiera de los idiomas del feed, sin distinguir mayúsculas ni acentos (pantalonencuentra «Pantalón»).GET /catalog/products?ids=987,111— los productos de esos ids, hasta 100, separados por comas, en el orden pedido. Un id que el catálogo no tiene (desconocido, o que ya no está en el feed) se omite: muéstralo como retirado.GET /catalog/products— el catálogo entero, página a página.
limit (de 1 a 50, 20 por defecto) y cursor paginan la búsqueda y el catálogo entero; ids los responde todos de una vez y va solo. language (es, pt-BR…, leído por sus dos letras): los títulos y enlaces en ese idioma cuando el feed lo tiene, si no en el de la tienda.
{
"products": [
{
"id": "111",
"title": "Camisa de lino blanca",
"image": "https://cdn.shop.example.com/products/111.jpg",
"url": "https://shop.example.com/products/camisa-de-lino-blanca",
"price": "59.00",
"salePrice": "44.90",
"currency": "EUR",
"available": true
}
],
"nextCursor": "OTg3"
}| Campo | Qué es |
|---|---|
id | El id de producto del feed (g:item_group_id, si no g:id, §4.5): el mismo id de productIds en §4.14 y §4.17 y de las importaciones (§4.8) |
title, url | Del feed, en language (o en el de la tienda) |
image | g:image_link; null cuando el feed no tiene |
price, salePrice, currency | Dinero como en §2, en la moneda base de la tienda (g:price). salePrice solo mientras está por debajo de price. price y currency son null cuando el feed no los da |
available | false cuando todas las variantes que informa el feed están out_of_stock; un producto sin datos de stock está disponible |
nextCursor | Solo cuando hay más: devuélvelo como cursor, con el mismo q, para la página siguiente. Opaco |
Los productos llegan en un orden estable (por id), no por relevancia. Lo que dice el feed es lo que responde Spaidoo: un cambio en la tienda se ve aquí tras la siguiente lectura (§4.5) o su catalog.changes (§4.6).
400 BAD_REQUEST: ids con q o cursor, más de 100 ids, q de menos de 2 caracteres, limit fuera de 1–50, o un cursor que esta ruta no dio.
4.6 Cambios de catálogo — catalog.changes
Cuando un producto cambia en la tienda, el conector se lo dice a Spaidoo en ese momento. Los avisos de bajada de precio salen en minutos en lugar de en la siguiente lectura diaria. La lectura diaria del feed se mantiene como conciliación.
POST /catalog/changes
{
"changes": [
{
"type": "product.updated",
"id": "123",
"at": 1759219200,
"price": { "amount": "24.90", "currency": "EUR" },
"salePrice": { "amount": "19.90", "currency": "EUR" },
"prices": [ { "currency": "USD", "price": "27.90", "salePrice": "21.90" } ],
"availability": "in_stock",
"variants": [
{ "sku": "123-1", "price": "24.90", "salePrice": "19.90", "availability": "in_stock" },
{ "sku": "123-2", "price": "24.90", "salePrice": null, "availability": "out_of_stock" }
]
},
{ "type": "product.deleted", "id": "456", "at": 1759219230 }
]
}ides el id de producto del feed (item_group_id, oidsin variantes).product.updatedlleva solo lo que puede cambiar sin tocar la estructura del catálogo:price,salePrice(null= sin oferta),prices,availability,variants. Todos los campos son opcionales; un campo presente sustituye al valor guardado.variants: para un producto con variantes, las variantes que han cambiado, porsku(elg:iddel feed), con los importes en la moneda deprice. Las bajadas de precio se miden sobre la variante más barata, igual que con el feed. Las variantes que no se envían conservan sus valores.product.deleted: el producto ya no se vende (borrado o desactivado).ates cuándo ocurrió el cambio en la tienda. Spaidoo ignora un cambio más antiguo que el que ya ha aplicado a ese producto, así que los reintentos y la entrega desordenada son seguros.- Los importes son strings decimales con 4 decimales como máximo (
"24.90").priceysalePricedeben estar en la misma moneda; los importes de las variantes también están en esa moneda. Los cambios en una moneda distinta de la moneda base de un idioma no tocan los precios de ese idioma. availability:in_stock·out_of_stock·preorder·backorder.- Un
aten el futuro se toma como ahora. 400 CATALOG_CHANGE_CURRENCY_MISMATCHconid(el primer cambio cuyopriceysalePriceestán en monedas distintas): no se aplica nada de la petición.- Hasta 100 cambios por petición y 60 peticiones por minuto por tienda (
429 CATALOG_CHANGES_RATE_LIMIT+Retry-After). El conector DEBERÍA agrupar las ráfagas (una edición masiva de precios de 2 000 productos son 20 peticiones, no 2 000). 409 CONNECTOR_CAPABILITY_MISSINGsi el handshake no declarócatalog.changes.- Durante las 24 horas siguientes a un cambio, el feed no sobrescribe los precios ni el stock de ese producto (un feed generado antes del cambio lo desharía); sí actualiza el resto.
- Los productos nuevos, y los cambios de título, enlace, imágenes o categorías, llegan con la siguiente lectura del feed. Un conector puede llamar a
POST /catalog/feeds/readdespués de una importación masiva.
Respuesta 202 (los cambios se aplican de forma asíncrona, en segundos):
{ "accepted": 1, "unknown": ["456"] }unknown lista los ids que Spaidoo todavía no tiene; programa una lectura del feed. La entrega es best effort: si falla, reintenta con backoff durante 1 hora como máximo y luego descarta — la lectura diaria del feed lo corrige todo.
4.7 POST /customers/erase — borrar un cliente (customerErase)
{ "customerId": "123" } → 204. Cualquier conector puede llamarla, haya declarado customerErase o no: un borrado se acepta siempre (la capacidad solo le dice a Spaidoo que el conector los envía, §8). La tienda ha borrado a este cliente (o ha recibido una solicitud de supresión del RGPD). Spaidoo borra la lista del cliente vinculada a esta tienda y desvincula de ella cualquier cuenta de Spaidoo. No hace falta enviar a los invitados (clientes sin cuenta).
4.7.1 POST /customers/export — lo que Spaidoo tiene de un cliente
{ "customerId": "123" } → 200. Un cliente ha pedido sus datos a la tienda (una solicitud de acceso del RGPD, el customers/data_request de una plataforma): Spaidoo responde todo lo que tiene de él para esta tienda, y el conector se lo entrega al comerciante (que responde al cliente). No necesita ninguna capacidad, como §4.7: funciona siempre.
{
"customerId": "123",
"known": true,
"since": 1756684800,
"spaidooAccountLinked": false,
"favorites": [
{
"name": "Blue shirt",
"url": "https://shop.example.com/products/blue-shirt",
"savedAt": 1757000000
}
],
"lists": [
{
"name": "Birthday",
"products": [
{
"name": "Red scarf",
"url": "https://shop.example.com/products/red-scarf",
"savedAt": 1757100000
}
]
}
],
"emailConsents": [
{
"email": "ana@example.com",
"source": "widget",
"consentedAt": 1757200000,
"textVersion": "2026-09-10"
}
],
"pushDevices": 1
}known: false(y listas vacías): Spaidoo no tiene nada de este cliente.favorites: productos guardados sueltos;lists: sus listas, solo con los productos de esta tienda. Cada producto{ name, url, savedAt }.spaidooAccountLinked: el cliente ha vinculado también una cuenta de Spaidoo a la de la tienda (§5). Solo viene lo que esa cuenta guarda de esta tienda; el resto es la relación del cliente con Spaidoo, que se lo pide a Spaidoo.emailConsents: los emails dados a la tienda en el widget, para sus avisos (source: "widget"), o el email de la cuenta de Spaidoo vinculada autorizado para ello (spaidoo_account), con cuándo y con qué texto. Spaidoo no guarda los emails de los clientes de la tienda (§6.2).pushDevices: navegadores suscritos a las notificaciones push de la tienda.
4.7.2 GET /shop-data y GET /shop-data/export — los clientes y contactos de la tienda
Para que el comerciante se lleve sus datos desde el panel del conector, igual que desde el admin de Spaidoo. No necesita capacidad.
GET /shop-data → 200: cuántos hay, sin preguntar nada a la tienda.
{ "customers": 120, "contacts": 37, "contactsLocked": false, "leavingUntil": null }customers: los clientes identificados de la tienda (su lista está anclada a la tienda, §5) que han guardado al menos un producto, también los que han vinculado una cuenta de Spaidoo. Un cliente que no ha guardado nada se deja fuera: su email y su consentimiento ya son de la tienda.contacts: personas que no son clientes de la tienda y han aceptado sus emails en el widget: un email escrito por un visitante anónimo, o el email de una cuenta de Spaidoo. Son los contactos que Spaidoo ha traído a la tienda.contactsLocked: siemprefalse, todos los planes se llevan sus contactos. Se mantiene por compatibilidad.leavingUntil: la tienda se ha ido (POST /uninstall, §4.4). Hasta esa fecha —90 días desde el último contacto del conector— se lo lleva todo, los clientes por id y sin email (Spaidoo ya no puede preguntar a la tienda); después Spaidoo borra sus contactos.nullen otro caso. Una plataforma que borra antes los datos de la tienda (POST /shop-redact, §3.5) lo acorta.
GET /shop-data/export?format=json|csv → 200, el propio archivo (Content-Disposition: attachment), el mismo que da el admin de Spaidoo. Sin format, JSON:
{
"shop": { "id": "shop_123", "name": "Mi tienda" },
"exportedAt": "2026-10-08T09:00:00.000Z",
"customers": [
{
"customerId": "123",
"email": "ana@example.com",
"spaidooAccountLinked": false,
"since": "2026-09-01T00:00:00.000Z",
"favorites": [{ "productId": "8812345600001", "name": "Blue shirt", "url": "https://shop.example.com/products/blue-shirt", "savedAt": "2026-09-04T15:33:20.000Z" }],
"lists": []
}
],
"contacts": [
{
"email": "marta@example.com",
"source": "widget",
"consentedAt": "2026-09-20T10:00:00.000Z",
"consentTextVersion": "shop-mail-save-v1",
"favorites": [],
"lists": []
}
],
"contactsLocked": false
}- Es un archivo para una persona: las fechas van en ISO 8601, no en segundos Unix.
productIdes el id propio de la tienda (el del feed);nullpara un producto añadido a mano a una lista. - CSV: una fila por producto guardado, como exportan otras apps de wishlist:
type(customer|contact),customer_id,email,source(shop_customer,shop_customer_linked,widget,spaidoo_account),consented_at,product_id,product_title,product_url,list_name(vacío: guardado suelto, no en una lista),added_at. Un contacto que no ha guardado nada tiene una fila con las columnas del producto vacías; un cliente que no ha guardado nada no está en el archivo. Los nombres son los que lee la importación de Spaidoo. customers[].emailse pide a la tienda en ese momento (§6.2): Spaidoo no lo guarda. Si la tienda no responde,503 SHOP_EMAILS_UNAVAILABLEy no hay archivo: uno sin emails parecería completo y no lo es.- Solo vienen quienes autorizaron a la tienda: una cuenta de Spaidoo sin ese consentimiento no sale nunca. Un contacto escrito en el widget viene con sus favoritos de la tienda; el email de una cuenta de Spaidoo viene solo (autorizó el email, no su biblioteca).
4.8 POST /wishlists/import — wishlistImport
{
"customers": [
{ "customerId": "123", "lists": [
{ "id": "1", "name": "My wishlist", "isDefault": true, "products": ["123", "789"] }
] }
]
}Hasta 50 clientes por llamada, 100 listas por cliente y 1 000 productos por lista. Los productos son ids de producto del feed. Idempotente: importar la misma lista dos veces no la duplica.
4.8.1 POST /wishlists/import/rows — wishlistImport, fila a fila
La misma importación, para un conector que tiene las listas como filas (un producto guardado por fila) y no quiere agruparlas: por ejemplo, un fichero exportado de otra app de wishlist que el conector ha leído. Spaidoo resuelve los productos y agrupa las listas. Spaidoo no recibe nunca un email aquí: cuando la app antigua identifica al cliente por email, el conector lo convierte antes en su propio id de cliente (con la API de clientes de la plataforma) y deja fuera las filas que no puede emparejar.
{
"dryRun": true,
"rows": [
{ "customerId": "123", "productId": "987", "list": "Birthday", "addedAt": 1756684800 },
{ "customerId": "123", "variantId": "987-2" },
{ "customerId": "124", "handle": "blue-shirt" }
]
}- Hasta 2 000 filas por llamada. Envía todas las filas de un cliente en la misma llamada (así los recuentos de una llamada describen clientes enteros).
customerId: el id de cliente de la tienda, como en §5 (un id global de la plataforma comogid://…/Customer/123se lee como123). Los invitados no tienen id: deja fuera sus filas.- El producto:
productId(el id de producto del feed), ovariantId(elg:idde una variante), ohandle(el último segmento de la URL del producto, o la URL entera). Al menos uno; Spaidoo los prueba en ese orden. list: el nombre de la lista en la app antigua. Si no viene o está vacío = la lista principal del cliente, que va a la biblioteca (comoisDefaulten §4.8). Un cliente con una sola lista la recibe como lista principal, se llame como se llame.addedAt(opcional): cuándo la guardó el cliente, en segundos Unix. Informativo.dryRun: trueno cambia nada y responde qué pasaría (la vista previa que el conector enseña antes de importar). Después, las mismas filas condryRun: false.- Idempotente como §4.8: repetirlo solo trae lo nuevo.
Respuesta 200:
{
"dryRun": true,
"counts": { "rows": 3, "accepted": 2, "rejected": 1, "duplicates": 0, "customers": 1, "lists": 2, "products": 2 },
"rejected": [ { "row": 2, "reason": "PRODUCT_NOT_FOUND" } ]
}counts.rows=accepted+rejected+duplicates.duplicates: filas que repiten un cliente, lista y producto que ya están en la llamada.customers,listsyproductsdescriben lo que se importa (o se importaría): los productos se cuentan una vez por cliente y lista.rejected: todas las filas rechazadas, por su posición enrows(desde 0), con sureason:PRODUCT_NOT_FOUND(no está en el catálogo que tiene Spaidoo),PRODUCT_MISSING(sinproductId,variantIdnihandle),CUSTOMER_INVALID(un id vacío o mal formado),LIMIT_EXCEEDED(más de 100 listas para el cliente o de 1 000 productos en una lista). Pueden aparecer motivos nuevos: muestra uno desconocido como «no importado».- Con
dryRun: falsela respuesta lleva ademásresult, el mismo objeto que responde §4.8:{ customers, listsCreated, productsAdded, alreadyImported, notInCatalogue, overLimit, listsRemovedInSpaidoo, customersSkipped }.
Errores (también para §4.8), en este orden: 409 TERMS_NOT_ACCEPTED (§4.13), 409 CONNECTOR_CAPABILITY_MISSING con capability: "wishlistImport" (no aceptada en el handshake), 409 WISHLIST_IMPORT_IDENTITY_OFF (la capacidad se aceptó pero la identidad no funciona ahora: nadie podría abrir las listas), 409 WISHLIST_IMPORT_NO_CATALOGUE (Spaidoo aún no tiene catálogo de la tienda).
4.8.2 POST /wishlists/import/file — wishlistImport, desde un fichero que sube el comerciante
La importación de un fichero exportado de otra app de wishlist, para un conector que no quiere resolver él los clientes: lee el fichero en filas y Spaidoo hace el resto. A diferencia del §4.8.1, el cliente puede venir por email: Spaidoo le pregunta a la tienda quién es con customerLookup (§6.3), y confirma un id de cliente con customers (§6.2). Spaidoo usa los emails para esa pregunta y los olvida: nunca los guarda.
{
"dryRun": true,
"rows": [
{ "customer": "ana@example.com", "productId": "987", "list": "Birthday" },
{ "customer": "ana@example.com", "variantId": "987-2" },
{ "customer": "124", "handle": "blue-shirt" },
{ "customer": "Guest", "productId": "555" }
]
}- Hasta 2 000 filas por llamada (como mínimo 1). Envía todas las filas de un cliente en la misma llamada.
customer(hasta 254): un email, o el id de cliente de la tienda (un id global de plataforma comogid://…/Customer/123se lee como123). Vacío oGuest: un invitado, se cuenta y se deja fuera.- Solo se importan los clientes que la tienda confirma: un email que la consulta no encuentra, o un id que la ruta de clientes no devuelve, se deja fuera (
customersNotFound). - El producto:
productId(el id de producto del feed, hasta 200),variantId(elg:idde una variante, hasta 200) ohandle(el último tramo de la URL del producto, o la URL entera, hasta 1000), probados en ese orden.list(hasta 250): como en el §4.8.1; sin nombre, o la única lista de un cliente, va a la biblioteca. dryRun: trueno cambia nada y responde la vista previa; después, las mismas filas condryRun: false. Idempotente como el §4.8.
Respuesta 200:
{
"preview": { "rows": 4, "guests": 1, "customers": 2, "customersNotFound": 0, "customersUnconfirmable": 0, "lists": 3, "productsNotFound": 0, "products": 3 },
"result": { "customers": 2, "listsCreated": 3, "productsAdded": 3, "alreadyImported": 0, "notInCatalogue": 0, "overLimit": 0, "listsRemovedInSpaidoo": 0, "customersSkipped": 0 }
}preview:rows;guests(filas de un invitado);customers(los ha confirmado la tienda);customersNotFound(emails o ids distintos que la tienda no tiene);customersUnconfirmable(emails o ids distintos por los que no se le puede preguntar a la tienda);lists;productsNotFound(filas de un cliente confirmado cuyo producto no está en el catálogo);products(lo que se trae, una vez por cliente y lista).result, solo condryRun: false: el mismo objeto que en el §4.8.1.
Errores, en este orden:
409 TERMS_NOT_ACCEPTED(§4.13).409 CONNECTOR_CAPABILITY_MISSINGconcapability:wishlistImportno aceptada; o el fichero nombra clientes por email y no se aceptócustomerLookup; o los nombra por id y no se aceptócustomers.409 WISHLIST_IMPORT_IDENTITY_OFF: la identidad no funciona ahora.409 WISHLIST_IMPORT_NO_CATALOGUE: Spaidoo aún no tiene catálogo de la tienda.503 SHOP_EMAILS_UNAVAILABLE: la tienda no ha respondido a la consulta o a la ruta de clientes; no se ha importado nada, vuelve a intentarlo más tarde.
4.9 Verificación de dominio — domainVerification
POST /domain-verification→{ "verified": false, "verificationCode": "spaidoo-verify-…", "domain": "shop.example.com" }. El conector guarda el código y lo sirve enurls.verifycomotext/plain, sin nada más en el cuerpo.urls.verifydebe estar en el dominio que se demuestra (o en suwww.) y no debe contener el código. Spaidoo no sigue redirecciones.POST /domain-verification/check→{ "verified": true }. Spaidoo ha pedidourls.verifyy ha encontrado el código.- Una tienda con el dominio ya demostrado responde
{ "verified": true }a las dos. - El dominio es siempre el de la propia tienda (el de su página en Spaidoo). Un
storeUrldistinto declarado en el handshake no es lo que se demuestra: demostrar un dominio del conector nunca verifica una tienda de otro. 400 DOMAIN_NOT_VERIFIABLE: Spaidoo no tiene ningún dominio que demostrar para la tienda o todavía no la tiene ninguna cuenta.429 CLAIM_RATE_LIMIT_EXCEEDED: se han pedido demasiados códigos; vuelve a intentarlo más tarde.- Sin la capacidad, el comerciante puede verificar igualmente subiendo el código como
https://<domain>/spaidoo-verify.txt.
4.10 Ajustes del widget desde el panel del conector (opcional)
Un conector puede dejar que el comerciante cambie algunos ajustes del widget sin salir del back-office. Son las únicas escrituras que puede hacer un conector sobre el widget:
| Llamada | Cuerpo |
|---|---|
POST /widget/state | { "mode": "off" | "preview" | "live" } — 403 SHOP_NOT_VERIFIED para live en un dominio sin verificar |
POST /widget/placement | { "desktop"?: {…}, "mobile"?: {…} } cada uno { position?: "bottom-left"|"bottom-right"|"bottom-center"|"custom", offsets?: { top?|bottom?, left?|right? }, orientation?: "vertical"|"horizontal", showButton?: bool }. custom coloca el botón por píxeles desde los bordes de la pantalla (offsets, enteros de 0 a 2000; uno de top/bottom y uno de left/right; si falta un lado: 20 px desde abajo / desde la derecha); un lado enviado sustituye a su opuesto. offsets sin custom, o los dos lados de un par: 400 INVALID_PLACEMENT. Una esquina sustituye a una posición personalizada · bottom-center solo en mobile (400 PLACEMENT_NOT_AVAILABLE en desktop) |
POST /widget/appearance | { theme?: "light"|"dark", accent?, iconColor?|null, icon?: "bookmark"|"heart", productCircle?, satelliteColor?|null, satelliteIconColor?|null } (colores #rrggbb; null = volver al color automático) |
POST /widget/save-buttons | El botón de guardar sobre las fotos (§7): { position?: "top-right"|"top-left"|"bottom-right"|"bottom-left", product?: bool, list?: bool, header?: bool, productSize?, listSize?, productStrokeWidth?, listStrokeWidth?, design?: { idle?, saved? }|null }. Tamaños en px, 28–80; grosores 1–3, de 0,25 en 0,25. Cada estado del diseño: { background?: "#rrggbb"|"transparent", icon?: "#rrggbb", fill?: "outline"|"filled" }; un objeto sustituye el diseño entero y null vuelve a los colores del botón flotante |
POST /widget/library-selector | El elemento propio de la tienda que abre la lista del cliente (su propio icono en la cabecera…): { selector: "…" }, un selector CSS (máx. 200), en escritorio y móvil a la vez; "" lo quita. Además, cualquier enlace a #spaidoo-list abre la lista sin configurar nada (p. ej. un elemento del menú de la tienda) |
POST /widget/custom-css | Los estilos propios de la tienda, por pieza: { styles: { save?, saveSaved?, saveIcon?, header?, headerAction?, headerIcon?, launcher?, launcherList?, launcherIcon?, launcherProduct? } }, cada uno solo declaraciones (propiedad: valor;, máx. 1000, sin { }, @, < ni url()), siempre el conjunto entero; {} los quita. Ver §4.10.1 |
POST /widget/search | { search?: bool, showSearchButton?: bool, chatAI?: bool, header?: bool, selector?: "…" }. header: el buscador se abre desde la cabecera de la tienda (§7 SpaidooConfig.searchHeader); selector: el elemento propio de la tienda que lo abre, un selector CSS (máx. 200), en escritorio y móvil a la vez, y "" lo quita. Además, cualquier enlace a #spaidoo-search abre el buscador. search enciende o apaga el buscador de Spaidoo, en todos los planes y sin más pasos, y entonces showSearchButton es solo su botón en el flotante. Enviado sin search, showSearchButton hace las dos cosas, como hasta ahora. Si la tienda tiene otro buscador vinculado, ese se queda y solo se muestra u oculta su botón. 409 SURFACE_NOT_AVAILABLE si se pide chatAI: true sin un asistente vinculado |
POST /widget/hints | Los textos del widget: lo que dice cada botón al pasar el ratón y lo que leen los lectores de pantalla, en escritorio y móvil a la vez. { libraryHint?, addProductHint?, savedProductHint?, searchHint?, chatAIHint? } (savedProductHint: el del botón de guardar cuando el producto ya está en la lista), cada uno false (sin texto), { "es": "…", "en": "…" } (los de la tienda, por idioma de 2 letras, máx. 100; el conjunto entero de esa pieza) o {} (volver a los del widget). Un idioma que falta, o vacío, usa el texto del widget en ese idioma |
- Todas responden
200 { "success": true }(/widget/statedevuelve tambiénmode). Al menos un campo; si no,400 NOTHING_TO_CHANGE. themees la base del aspecto del widget:lightodark. El widget deriva el resto de la paleta dethemeyaccent.- El botón por encima de la barra propia del móvil (una barra fija de compra, un chat), colocado por píxeles:
{ "mobile": { "position": "custom", "offsets": { "bottom": 96, "right": 16 } } }. Después/statusdevuelveposition: "custom"con esosoffsets(§4.3). - Primero las condiciones: mientras la tienda no haya aceptado la versión vigente de las condiciones de Spaidoo (
store.termsAccepted: falseen §4.3), todas las escrituras de esta sección responden409 TERMS_NOT_ACCEPTED. Muestra la aceptación (§4.13) y vuelve a intentarlo. Las lecturas (/status) funcionan siempre.
4.10.1 Personalizar con CSS
La tienda no escribe selectores: escribe declaraciones (propiedad: valor;) para cada pieza de lo que configura aquí, y el loader de la tienda las envuelve en los selectores de Spaidoo y las pone en la página. Nunca llegan al panel de la lista.
| Pieza | Selector |
|---|---|
save · botón de guardar | [data-spaidoo-save]::part(button) |
saveSaved · botón de guardar, guardado | [data-spaidoo-save]::part(saved) |
saveIcon · símbolo del botón de guardar | [data-spaidoo-save]::part(icon) |
header · icono de la cabecera | [data-spaidoo-header] |
headerAction · botón del icono de la cabecera (el del widget, iconos fijos) | [data-spaidoo-header]::part(action) |
headerIcon · dibujo de ese icono: width, height, stroke-width (en una caja de 24) | [data-spaidoo-header]::part(icon) |
launcher · botón flotante (conjunto) | #spaidoo-widget-root::part(launcher) |
launcherList · botón de la lista | #spaidoo-widget-root::part(launcher-list) |
launcherIcon · icono del botón de la lista | #spaidoo-widget-root::part(launcher-icon) |
launcherProduct · círculo del producto | #spaidoo-widget-root::part(launcher-product) |
En el botón de guardar también sirven sus variables: --sp-save-size, --sp-save-radius, --sp-save-background, --sp-save-color, --sp-save-fill, --sp-save-shadow…
{ "styles": { "save": "border-radius: 8px; box-shadow: none;", "launcher": "bottom: 96px;" } }4.10.2 La vista previa del widget (opcional)
El panel de un conector puede enseñar el widget a medida que el comerciante lo configura, sin una página de la tienda: un iframe de la página de vista previa de Spaidoo, que se maneja con postMessage. Nada de lo que hay dentro es real: no llama a Spaidoo ni cuenta nada, y un clic solo le dice al panel qué se ha pulsado.
<iframe src="https://widget.spaidoo.com/preview/v1/index.html?origin=https%3A%2F%2Fpanel.platform.example"
sandbox="allow-scripts allow-same-origin" width="360" height="640"></iframe>origin(obligatorio): el origen de tu panel. La vista previa solo acepta mensajes de ese origen y de su ventana madre, y solo le escribe a él.- Todos los mensajes, en los dos sentidos:
{ "ns": "spaidoo-preview", "v": 1, "type": "…", …campos }. Ignora cualquier otronsov, y comprueba queevent.origineshttps://widget.spaidoo.comyevent.sourcela ventana del iframe. Un cambio que lo rompa irá a/preview/v2/.
type | Sentido | Campos | Cuándo |
|---|---|---|---|
ready | vista previa → panel | sizes: { mobile: [360, 640], desktop: [1024, 640] } | Una vez, cuando ya puede pintar. Si no llega en unos segundos, muestra la vista previa como no disponible |
render | panel → vista previa | rev (un número que sube con cada uno), config (abajo) | Después de ready y después de cada cambio, como mucho uno por fotograma. Solo se pinta el último |
rendered | vista previa → panel | rev | Ese render ya está en pantalla: muestra el iframe (tenlo oculto hasta el primero) |
error | vista previa → panel | rev, code: BAD_CONFIG (con field) o RENDER_FAILED | Se queda el último render bueno |
focus | vista previa → panel | target: launcher · save · panel · header | El comerciante ha pulsado esa pieza: llévalo a su ajuste |
config, un único objeto plano con los mismos valores que /status (§4.3) y las escrituras de §4.10:
| Clave | Qué es |
|---|---|
device | mobile o desktop (obligatoria) |
theme, accent, icon, productCircle | Obligatorias, como en POST /widget/appearance. iconColor, satelliteColor, satelliteIconColor: opcionales, #rrggbb o null |
placement | Obligatoria: { position, orientation, showButton, top?, right?, bottom?, left? } de ese dispositivo; los píxeles de una posición custom van aquí, no en offsets |
lang | El idioma en que habla el widget |
page | product (por defecto) o collection: el tipo de página que se pinta detrás |
panel | closed (por defecto) u open: el panel de la lista abierto |
saveAnchors, saveButton, header | Los botones de guardar sobre las fotos y su diseño, como en POST /widget/save-buttons; header: el icono de la cabecera |
hints, tip | Los textos del widget, como en POST /widget/hints; tip: una de sus claves, que se muestra como si se pasara el ratón por encima |
search, chatAI | Los botones del buscador y del asistente |
customCss | Los estilos propios de la tienda por pieza (§4.10.1) |
stage | { width }, de 240 a 1024: el ancho que enseña el panel; la vista previa pinta un escenario de ese ancho, en el lado del botón |
products | Hasta 8 productos de la tienda, { name, image (https), price? }, en lugar de los dibujos de muestra |
El iframe no informa nunca de su altura: dale un tamaño fijo y recórtalo (stage). Su fondo es el suyo (una página clara).
4.11 POST /sso — abrir el admin de Spaidoo con la sesión ya iniciada
{ "intent": "panel" } → { "url": "…" } (de un solo uso, 5 minutos). Intents: panel, widget-setup, spaidoo-search, providers, email, posts, carousels, push, automations, reports (los informes completos), billing (planes y facturas en Spaidoo; para una tienda que cobra su plataforma, el admin de Spaidoo envía al comerciante a urls.billing).
- Un intent desconocido cae en
panel(200, nunca400): un conector publicado en un marketplace sigue funcionando cuando Spaidoo renombra o retira una página. Aun así, unintentdebe ser un nombre corto (^[a-z0-9-]{1,40}$). - Pide la URL cuando el comerciante haga clic y ábrela en una pestaña nueva: una URL creada por adelantado puede caducar antes de usarse.
- La URL abre la página «continuar como
» de Spaidoo: el comerciante hace un clic más para entrar. Abrir el enlace no inicia ninguna sesión, así que un enlace enviado a otra persona nunca la pone a trabajar en tu tienda.
4.12 Plan cobrado por la plataforma — billing.platform
Algunas plataformas cobran ellas mismas sus apps (un marketplace de apps con facturación propia), y sus normas prohíben cobrar al comerciante en ningún otro sitio. Con billing.platform la plataforma cobra el plan de Spaidoo de la tienda y el conector le dice a Spaidoo qué plan tiene la tienda. Spaidoo lo toma entonces como la verdad sobre el plan de la tienda, no ofrece pago propio y envía al comerciante a urls.billing para cambiarlo.
El conector traduce los planes de su plataforma a los de Spaidoo: starter · growth · pro. Spaidoo no sabe nada de los nombres de plan de la plataforma.
PUT /billing — el plan de la tienda tal como lo tiene ahora la plataforma. Idempotente: envía siempre el estado completo.
{
"plan": "growth",
"interval": "monthly",
"status": "trialing",
"externalId": "sub_8f2a…",
"currentPeriodEnd": 1761955200,
"trialEndsAt": 1760572800,
"cancelAtPeriodEnd": false,
"pending": null,
"price": { "amount": "29.00", "currency": "USD" },
"test": false,
"occurredAt": 1759363200
}| Campo | |
|---|---|
plan | starter · growth · pro. Cualquier otro: 400 BILLING_PLAN_UNKNOWN |
interval | monthly · annual. No viene (o null) en un plan sin precio |
status | active · trialing · frozen (la plataforma ha suspendido los cobros: una factura de la plataforma impagada) · cancelled |
externalId | El id de la suscripción en la plataforma, o null. Se guarda para soporte y conciliación |
currentPeriodEnd | Cuándo acaba el periodo pagado (segundos Unix), o null. En una prueba sin ciclo de facturación todavía, el final de la prueba: con null, Spaidoo toma trialEndsAt |
trialEndsAt | Cuándo acaba la prueba gratuita, o null |
cancelAtPeriodEnd | El comerciante ha cancelado: el plan dura hasta currentPeriodEnd. Por defecto false |
pending | Un cambio que se aplica más tarde (una bajada al final del periodo): { plan, interval?, effectiveAt }, o null |
price | Lo que cobra la plataforma, { amount, currency } (§2), o null. Informativo: Spaidoo nunca calcula con él |
test | Un cobro de prueba (una tienda de desarrollo): se da el plan, no cuenta como ingreso. Por defecto false |
occurredAt | Cuándo era cierto el estado de la plataforma (la hora de su evento, o cuando el conector lo leyó), en segundos Unix |
Respuesta 200: el mismo objeto que GET /billing.
Qué hace Spaidoo con él:
| Informe | Efecto |
|---|---|
active / trialing | La tienda tiene plan desde ahora |
pending | No cambia nada hasta effectiveAt; vuelve a informar entonces |
cancelAtPeriodEnd: true | El plan dura hasta currentPeriodEnd |
frozen | La tienda usa starter (la comunicación se detiene, no se borra nada); un active posterior le devuelve el plan |
cancelled | La tienda pasa a starter |
- Orden: los informes pueden llegar desordenados (una redirección y una conciliación a la vez). Spaidoo aplica el de
occurredAtmás reciente. Un informe con exactamente eloccurredAtya aplicado es un reintento: se acepta,200. Uno estrictamente más antiguo responde409 BILLING_STALE, con ellastEventAtaplicado. Ante un409 BILLING_STALE, vuelve a leer la plataforma y envía el estado actual. - Informa después de cada cambio de la suscripción en la plataforma, y como mínimo una vez por periodo de facturación (se recomienda una conciliación diaria). Si
currentPeriodEndpasa 2 días sin ningún informe, se avisa al equipo de Spaidoo; a los 7 días la tienda pasa astarterhasta el siguiente informe. Spaidoo nunca baja un plan porque una llamada haya fallado: solo por un estado informado o pasados esos 7 días. 409 CONNECTOR_CAPABILITY_MISSINGsibilling.platformno se aceptó en el handshake (§4.1).409 BILLING_STRIPE_ACTIVEmientras la tienda siga pagando a Spaidoo directamente (un plan comprado en el admin de Spaidoo): no cambia nada. El comerciante lo cancela antes en Spaidoo; después, vuelve a informar. A ninguna tienda se le cobra dos veces.- Un conector que ha informado
cancelledy después se desinstala (POST /uninstall, §4.4) devuelve la facturación a Spaidoo: la tienda puede volver a comprar un plan en el admin de Spaidoo. - Mientras el plan de la tienda lo cobre la plataforma, el pago propio de Spaidoo (cambios de plan, método de pago, cancelación en el admin de Spaidoo) responde
409 BILLING_MANAGED_BY_PLATFORM.
GET /billing — lo que tiene Spaidoo, para la pantalla de planes del conector y para conciliar. Funciona con o sin la capacidad.
{
"provider": "platform",
"plan": "growth",
"interval": "monthly",
"status": "trialing",
"currentPeriodEnd": 1761955200,
"trialEndsAt": 1760572800,
"cancelAtPeriodEnd": false,
"pending": null,
"price": { "amount": "29.00", "currency": "USD" },
"test": false,
"externalId": "sub_8f2a…",
"lastEventAt": 1759363200,
"lastReportAt": 1759363260,
"manageUrl": "https://admin.platform.example/store/my-shop/apps/spaidoo/plans"
}provider: quién cobra el plan.platform(esta capacidad),stripe(lo cobra Spaidoo) ointernal(concedido por Spaidoo, no se cobra nada).- Con un
providerdistinto deplatform:externalId,price,lastEventAtylastReportAtsonnull, ymanageUrles la página del admin de Spaidoo (onullparainternal).statususa el vocabulario de arriba. lastEventAt: eloccurredAtdel informe aplicado;lastReportAt: cuándo llegó el último informe.
4.12.1 GET /plans — los planes de Spaidoo, para la pantalla de planes del conector
Qué incluye cada plan, de la misma tabla que aplica Spaidoo, para que un conector pinte su pantalla de planes sin copiarla. Solo claves e ids: las etiquetas son del conector, en sus propios idiomas. Sin capacidad.
{
"current": "growth",
"billing": "stripe",
"plans": [
{
"id": "growth",
"price": { "currency": "EUR", "monthlyCents": 2900, "annualCents": 27600, "taxIncluded": false },
"features": {
"postsPerMonth": 10, "postsGapDays": 1, "notificationsPerMonth": 4, "notificationsGapDays": 1,
"boardCards": 3, "dashboards": null, "carousels": false, "contactsExport": true, "customSlug": true, "peopleLists": true
},
"automations": ["first_product_saved", "product_saved", "products_threshold", "product_removed"],
"integrations": ["webhook", "klaviyo", "mailchimp", "ga4"],
"reports": ["widget_usage", "library_usage", "top_saved_products"]
}
]
}| Campo | Qué es |
|---|---|
current | El plan que usa ahora la tienda: starter · growth · pro (una prueba o una concesión de Spaidoo pueden ponerlo por encima del cobrado) |
billing | Quién lo cobra: stripe (Spaidoo) o platform (§4.12) |
plans | Todos los planes, del más bajo al más alto |
price | Los precios de Spaidoo en céntimos, sin impuestos (taxIncluded: false), al mes y al año. null cuando cobra la plataforma: cobra sus propios precios |
features | postsPerMonth, notificationsPerMonth, boardCards, dashboards: cuántos, null = sin límite, 0 = no incluido. postsGapDays, notificationsGapDays: días entre dos. carousels, customSlug (la dirección propia de la tienda en el portal de Spaidoo), peopleLists (quién es cada persona, en los informes): incluido o no. contactsExport: siempre true |
automations | Los tipos de aviso que incluye (§4.14) |
integrations | Las herramientas que puede conectar (el id del §4.19) |
reports | Los ids de los informes que incluye en el admin de Spaidoo |
Pueden aparecer claves, ids y funciones nuevas: muestra solo las que conozcas.
4.13 POST /terms/accept — aceptar las condiciones de Spaidoo desde el conector
Una tienda dada de alta por su conector (§3.4) no ha estado nunca en el admin de Spaidoo. El comerciante acepta las condiciones de Spaidoo en el panel del conector, y el conector se lo comunica a Spaidoo:
{ "version": "2026-09-10", "acceptedBy": "staff-88120345", "at": 1759560000 }version: lastore.termsVersionque se le mostró al comerciante (§4.3), con el texto destore.termsUrls.acceptedBy: quién ha aceptado: el id del miembro del equipo en la plataforma, nunca un email (400si lo parece). Se guarda, con la tienda, la versión y la hora, como prueba de la aceptación.at: cuándo aceptó, en segundos Unix. Se guarda junto a la hora en que la llamada llegó a Spaidoo; unaten el futuro se toma como ahora.
→ 200 { "termsAccepted": true, "termsVersion": "2026-09-10", "acceptedAt": 1759560003 }. Aceptar otra vez la misma versión no cambia nada.
409 TERMS_VERSION_OUTDATEDconcurrentVersioncuandoversionno es la vigente (al comerciante se le mostró un texto antiguo): muestra el nuevo y vuelve a pedirlo.- La aceptación es de la tienda, se haga donde se haga: aceptar en el admin de Spaidoo también pone
termsAcceptedatrue. - Hasta que la tienda acepte, las escrituras de §4.10 y las importaciones (§4.8, §4.8.1) responden
409 TERMS_NOT_ACCEPTED. Todo lo demás sigue funcionando: el catálogo, la identidad y el widget en la tienda.
4.14 Avisos automáticos — /automations
Los avisos automáticos de la tienda, los mismos que en el admin de Spaidoo (Avisos automáticos): Spaidoo avisa a cada persona cuando pasa algo con lo que ha guardado. El panel del conector puede verlos, crearlos, cambiarlos y quitarlos. Spaidoo escribe el título y el texto de cada aviso en el idioma de cada cliente; la tienda solo añade, si quiere, un texto final.
Solo los tipos que la propia tienda puede disparar: seguir la tienda (nuevo seguidor, deja de seguir) solo ocurre en el portal y las apps de Spaidoo, y esos dos se quedan en su admin.
GET /automations → 200:
{
"kinds": [
{ "type": "price_drop", "plan": "pro", "setting": { "key": "minDropPercent", "min": 1, "max": 90, "default": 5 }, "products": true, "link": false, "push": true, "multiple": true }
],
"automations": [
{
"id": "6702a1b2c3d4e5f6a7b8c9d0", "type": "price_drop", "name": "Bajada de precio", "status": "active",
"config": { "minDropPercent": 10 },
"note": { "es": "Usa el código VUELVE10 en tu compra.", "en": "Use the code VUELVE10 at checkout." },
"link": null, "reach": { "sent": 42, "seen": 31 }, "lastSentAt": 1759400000, "createdAt": 1759300000
}
]
}kinds: qué necesita cada tipo, como lo decide Spaidoo. Pinta el panel a partir de aquí, sin copiar las reglas en el conector:
| Campo | Qué es |
|---|---|
type | price_drop (baja de precio), back_in_stock (estaba agotado y vuelve a estar disponible), saved_reminder (lo guardó hace N días), visit_reminder (lleva N días sin volver), first_product_saved (su primer guardado), product_saved (guarda un producto), products_threshold (llega a N guardados), product_removed (quita un producto) |
plan | El plan que lo incluye: growth o pro. En starter no hay avisos |
setting | El número del tipo (key: minDropPercent, days o productsCount) con su mínimo, máximo y valor por defecto; null si no tiene |
products | Si puede limitarse a unos productos (config.productIds) |
link | Si el aviso lleva un enlace propio a la web de la tienda |
push | Si además del widget sale por notificación push (lo decide el tipo, no la tienda) |
multiple | Si la tienda puede tener varios de este tipo (por ejemplo, uno por colección). false en first_product_saved: es un solo momento por persona |
automations: los avisos de la tienda de esos tipos, del más antiguo al más nuevo. Puede haber varios del mismo tipo cuando su multiple es true. config.productIds son los ids de producto del feed del conector; sin él, el aviso vale para todos. reach: avisos creados y vistos desde que existe. Fechas en segundos Unix.
POST /automations { "type", "name", "status"?, "config"?, "note"?, "link"? } → 201 con el aviso. status por defecto active; sin el número de setting, el valor por defecto. note: el texto final, uno por idioma ({ "es": "…", "ca": "…" }, hasta 300 caracteres cada uno), en cualquiera de los idiomas de los avisos: es, en, ca, fr, de, it, pt, nl, cs, da, fi, ja, ko, nb, pl, sv, th, tr, vi, zh (los mismos 20 para los anuncios, notificaciones y carruseles de §4.15–§4.17). El de primaryLanguage es obligatorio: es el que recibe quien lee en un idioma sin texto. GET dice qué idiomas tiene la tienda (languages, los de su ficha y su catálogo) y cuál es el suyo (primaryLanguage): muéstralos como pestañas.
PUT /automations/:id con los campos que cambian → 200 con el aviso. config se sustituye entero. El tipo no cambia: otro tipo es otro aviso. DELETE /automations/:id → 204; los avisos que nadie ha visto se van con él.
400 PUSH_REQUIRES_PLAN: enstarter, al crear encendido o activar cualquier aviso. Creado con"status": "paused"no pide plan: espera, listo, a que la tienda cambie de plan.400 ALERT_REQUIRES_PRO: encender un tipoproen un plan inferior. Crearlo pausado, cambiarlo mientras está pausado y pausarlo se puede siempre.400 NOTE_LANGUAGE_MISSING: el texto final no trae el idioma de la tienda (primaryLanguage).400 CAMPAIGN_LINK_NOT_SHOP: el enlace no es de los dominios de la tienda.400 BAD_REQUEST: un campo que el tipo no admite o un número fuera de su rango.409 AUTOMATION_ALREADY_EXISTS: crear otro de un tipo conmultiple: false.404 NOT_FOUND: no es un aviso de la tienda de estos tipos.- Como las escrituras de §4.10, crear y cambiar esperan a las condiciones (
409 TERMS_NOT_ACCEPTED, §4.13). Leer y quitar, no.
4.15 Tablón de anuncios — /posts
Los anuncios de la tienda, los mismos que en el admin de Spaidoo (Tablón de anuncios): una imagen, un titular, un texto y un botón, por idioma, en el tablón del widget de la tienda y en el portal. Lo tienen growth (10 anuncios al mes, 1 día de espera entre uno y el siguiente) y pro (sin límite ni espera). En starter no hay anuncios: se pueden leer, guardar borradores y quitar, pero no publicar.
GET /posts ?status=published|draft&search=…&cursor=…&limit=1-50 (todo opcional) → 200:
{
"quota": { "plan": "growth", "used": 2, "quota": 10, "remaining": 8, "gapDays": 1, "nextAllowedAt": null },
"languages": ["es", "en"],
"primaryLanguage": "es",
"counts": { "all": 1, "published": 1, "draft": 0 },
"posts": [
{
"id": "6702b1b2c3d4e5f6a7b8c9e0", "status": "published",
"content": { "es": { "title": "Nueva colección de invierno", "text": "Ya están aquí los abrigos…", "ctaLabel": "Ver la colección", "ctaUrl": "https://shop.example.com/collections/invierno", "imageUrl": "https://cdn.spaidoo.com/posts/invierno.jpg" } },
"importance": "featured", "highlightDays": 7,
"publishedAt": 1759400000, "editedAt": null, "createdAt": 1759400000, "reach": { "views": 320, "clicks": 41 }
}
],
"nextCursor": null
}| Campo | Qué es |
|---|---|
quota | Los anuncios del mes: used, quota y remaining (null en los dos últimos: sin límite), gapDays entre uno y otro y nextAllowedAt, cuándo se puede publicar el siguiente (null: ya) |
counts | Todos los anuncios de la tienda, sea cual sea la página: en total, publicados y borradores |
posts | Una página (24 si no se pide otro limit): los borradores primero y luego los publicados, del más reciente al más antiguo. status filtra por estado y search por titular o texto, en cualquier idioma |
nextCursor | El cursor de la página siguiente, con los mismos filtros; null: no hay más |
status | published o draft. Un anuncio publicado no vuelve a borrador: se edita o se quita |
languages, primaryLanguage | Los idiomas en que la tienda escribe, el suyo primero y obligatorio. Quien lee en un idioma sin texto recibe el de la tienda |
content | Por idioma (cualquiera de los 20 de los avisos, §4.14), con el de la tienda obligatorio. text (hasta 300), y opcionales title (140), ctaLabel (80), ctaUrl (una URL, hasta 300) e imageUrl (hasta 1000) |
importance | Cuánto se hace notar: normal (solo en el tablón), featured (además marca el botón del widget), important (además se abre solo una vez al entrar) |
highlightDays | Durante cuántos días se hace notar un featured o important (1–30, por defecto 7) |
reach | Veces que se ha visto en el tablón y clics, desde que se publicó |
POST /posts { "content", "importance"?, "highlightDays"?, "status"? } → 201 con el anuncio. Por defecto se publica y gasta uno de los anuncios del mes; "status": "draft" lo guarda sin publicar ni gastar nada. POST /posts/:id/publish publica un borrador → 200.
PUT /posts/:id con los campos que cambian → 200. content se sustituye entero. Editar nunca vuelve a publicar ni cambia la posición del anuncio. DELETE /posts/:id → 204; no devuelve el anuncio del mes.
POST /posts/image { "image": "data:image/…;base64,…" } → 201 { "url" }: la imagen ya subida, para el imageUrl de un idioma. El cuerpo de la petición puede ocupar hasta 5 MB; como el base64 hace crecer una imagen un tercio, eso es una imagen de unos 3,7 MB.
400: falta el texto en el idioma de la tienda (content.<primaryLanguage>.text).400 POST_REQUIRES_PLAN: enstarter, al publicar (crear publicado o publicar un borrador).400 POST_QUOTA_REACHED: ya se han publicado los anuncios del mes.400 POST_GAP_TOO_SOON: aún no ha pasado la espera desde el último (nextAllowedAtdice cuándo).404 NOT_FOUND: no es un anuncio de la tienda.- Como las escrituras de §4.10, crear, cambiar, publicar y subir una imagen esperan a las condiciones (
409 TERMS_NOT_ACCEPTED, §4.13). Leer y quitar, no.
4.16 Notificaciones — /notifications
Un mensaje que la tienda escribe a un grupo de sus clientes, las mismas notificaciones que en el admin de Spaidoo (Notificaciones): llega como notificación push a quien la tiene activada y como tarjeta en la bandeja de avisos del widget. El panel del conector puede verlas, crearlas, enviarlas o programarlas, cambiarlas mientras no se han enviado y quitarlas.
GET /notifications ?status=sent|pending|draft&search=…&cursor=…&limit=1-50 (todo opcional) → 200:
{
"audiences": [
{ "id": "audience_total", "name": { "es": "Audiencia total", "en": "Total audience" }, "description": { "es": "…", "en": "…" }, "people": 212 }
],
"quota": { "plan": "growth", "quota": 4, "used": 1, "remaining": 3, "nextAllowedAt": null, "gapDays": 1 },
"languages": ["es", "en"],
"primaryLanguage": "es",
"counts": { "all": 1, "sent": 1, "pending": 0, "draft": 0 },
"notifications": [
{
"id": "6702b1b2c3d4e5f6a7b8c9e0", "name": "Rebajas de otoño", "status": "sent", "audience": "audience_total",
"content": { "es": { "title": "Rebajas de otoño", "message": "Lo que guardaste, hasta un 30 % menos.", "url": "https://shop.example.com/collections/rebajas" } },
"push": true, "sendAt": null, "sentAt": 1759410000, "validUntil": null, "reach": { "sent": 212, "seen": 143, "clicked": 37 }, "createdAt": 1759400000
}
],
"nextCursor": null
}| Campo | Qué es |
|---|---|
audiences | Los grupos a los que se puede enviar, con su nombre y descripción en es y en y cuántas personas tiene cada uno ahora (people). Los decide Spaidoo |
quota | Los envíos del plan este mes (quota, used, remaining) y la espera mínima entre dos (gapDays; nextAllowedAt, en segundos Unix: cuándo se puede enviar una ahora, si aún no se puede). Todo cuenta en el momento en que la notificación SALE: una programada gasta el envío del mes de su fecha, y entre dos (enviadas o programadas, en cualquier orden) tiene que haber gapDays. Borrar una programada que aún no ha salido, o volverla a borrador, devuelve su envío. En starter no se envían: se preparan y se guardan como borrador, y se envían al cambiar de plan |
counts | Todas las notificaciones de la tienda, sea cual sea la página: en total, enviadas, pendientes (scheduled, paused o sending) y borradores |
notifications (lista) | Una página (24 si no se pide otro limit), de la más reciente a la más antigua. status filtra por grupo y search por nombre, título o mensaje, en cualquier idioma. nextCursor: el cursor de la página siguiente, con los mismos filtros; null: no hay más |
validUntil | Hasta cuándo vale lo que dice (una oferta de fin de semana), en segundos Unix, o null: sin fin. Pasada esa fecha, la notificación sigue en la bandeja del widget marcada como terminada y sin su enlace, y ya no se abre sola ni marca el widget. Tiene que ser posterior a cuando sale. Se envía al crearla o cambiarla; null la quita |
languages, primaryLanguage | Los idiomas en que la tienda escribe, el suyo primero y obligatorio. Quien lee en un idioma sin texto recibe el de la tienda |
status | draft (borrador), scheduled (programada), paused, sending (enviándose) o sent |
content | Por idioma (cualquiera de los 20 de los avisos, §4.14): title (hasta 100), message (hasta 200) y url opcional, una página de la tienda (http(s), hasta 2048) |
push | Si además de la bandeja del widget sale como push. Por defecto true |
reach | Tarjetas creadas en la bandeja, vistas y con clic |
GET /notifications/:id/stats → 200: lo que ha conseguido una notificación, como en el admin de Spaidoo.
{
"totals": { "created": 212, "pushed": 96, "shown": 143, "read": 75, "clicked": 37 },
"period": "day",
"series": [{ "day": "2026-10-02", "created": 212, "pushed": 96, "shown": 118, "read": 65, "clicked": 29 }]
}| Campo | Qué es |
|---|---|
created | A cuántas personas les ha llegado: un aviso en la bandeja del widget de cada una |
pushed | De ellas, a cuántas les ha llegado además como push (móvil u ordenador) |
shown, read, clicked | Cuántas lo han visto en la bandeja, abierto, y cuántas han ido a su enlace |
period, series | Su vida: desde el día que salió hasta su último día con algo (no hasta hoy: una de hace un año se cuenta igual que una de ayer), del más antiguo al más reciente, con los días sin nada a 0. Por día (period: day) o, si pasa de 60 días, por semana (week, cada una con su primer día). day: YYYY-MM-DD, UTC |
POST /notifications { "name", "audience", "content", "push"?, "send", "sendAt"? } → 201 con la notificación. name (hasta 200) es el nombre interno de la tienda, nunca lo ven los clientes. send: draft (se guarda sin enviar), now (se envía ya) o schedule (se envía en sendAt, segundos Unix en el futuro). Enviar o programar gasta uno de los envíos del mes en ese momento; un borrador, no.
PUT /notifications/:id con los campos que cambian, mientras está en draft, scheduled o paused → 200. content se sustituye entero; send vuelve a decidir qué pasa. DELETE /notifications/:id → 204; no devuelve el envío del mes.
400 PUSH_REQUIRES_PLAN: enstarter, al enviar o programar. Guardar o editar un borrador no pide plan.400 PUSH_QUOTA_REACHED: ya se han usado los envíos del mes.400 PUSH_GAP_TOO_SOON: aún no ha pasado la espera desde el último.400 BAD_REQUEST: un grupo que no está enaudiences, sin el idioma de la tienda, o unsendAtpasado.409 NOTIFICATION_ALREADY_SENT: se está enviando o ya se envió; ya no cambia.404 NOT_FOUND: no es una notificación de la tienda.- Como las escrituras de §4.10, crear y cambiar esperan a las condiciones (
409 TERMS_NOT_ACCEPTED, §4.13). Leer y quitar, no.
4.17 Carruseles inteligentes — /carousels
Los carruseles de la tienda, los mismos que en el admin de Spaidoo: una fila (o una cuadrícula) de productos de la tienda que el widget coloca en sus páginas. Los productos los elige la tienda a mano, o Spaidoo: lo más visto, lo más guardado, lo de cada cliente (lo último que ha mirado, lo que ha guardado) o, en una ficha de producto, lo que también guardaron quienes guardaron ese producto. Son del plan Pro.
GET /carousels → 200:
{
"plan": "pro",
"kinds": [ { "kind": "manual", "products": true, "personal": false, "productPage": false }, { "kind": "saved_together", "products": false, "personal": false, "productPage": true } ],
"languages": ["es", "en"],
"primaryLanguage": "es",
"carousels": [
{
"id": "6702b1b2c3d4e5f6a7b8c9e0", "kind": "most_saved", "name": "Lo más guardado", "status": "active",
"productIds": [], "order": "fixed", "maxVisible": 10, "minProducts": 3,
"title": { "es": "Lo que más guardan", "en": "Most saved" },
"look": { "format": "slider", "template": "card", "showTitle": true },
"location": { "anchor": "product", "cssSelectors": ["main"], "position": "append", "urlPatterns": ["/products/*", "/*/products/*"], "device": "both" },
"reach": { "impressions": 1240, "clicks": 86 }, "createdAt": 1759300000
}
]
}| Campo | Qué es |
|---|---|
kind | manual (productos elegidos), most_visited (lo más visto), most_saved (lo más guardado), recently_viewed (lo último que ha mirado cada cliente), user_library (lo que ha guardado cada cliente), saved_together (en una ficha de producto: lo que también guardaron quienes lo guardaron). kinds dice cuáles eligen sus productos a mano (products), cuáles cambian con cada cliente (personal) y cuáles solo tienen sentido en una ficha de producto (productPage). recently_viewed, user_library y saved_together salen vacíos para algunos visitantes (un cliente nuevo, un producto que nadie ha guardado aún): entonces enseñan lo más guardado, y el widget lo titula como tal |
productIds | Solo manual: los ids de producto del feed del conector, en orden, hasta 50 (elígelos, y muestra sus nombres y fotos, con GET /catalog/products, §4.5.1). order: fixed o random (barajados para cada visitante) |
name | El nombre interno que le da la tienda (hasta 200), nunca lo ven los clientes |
maxVisible | Cuántos productos enseña, de 1 a 50 |
minProducts | Con menos productos que estos (agotados, un visitante sin nada todavía, también tras pasar a lo más guardado) no sale; de 1 a 50 y como mucho maxVisible (400 BAD_REQUEST si no). Por defecto 1 |
title | El título de la sección (hasta 200), uno por idioma de los avisos (§4.14); el de primaryLanguage es obligatorio si look.showTitle, y es el que recibe quien lee en un idioma sin título. null: sin título |
look | format slider (en fila, con flechas) o grid (cuadrícula); template card (foto, nombre y precio) o circle (solo la foto, redonda); showTitle |
location | Dónde lo pinta el widget: dentro del sitio propio del conector en la página, <div data-spaidoo-carousel="<anchor>"> (§7), si hay anchor y la página lo tiene; si no, el primer elemento de cssSelectors que exista en la página, before/after él o dentro (prepend al principio, append al final), en las páginas cuya ruta encaje con urlPatterns (* un tramo, ** cualquiera; sin él, en todas), y en desktop, mobile o both. anchor cumple ^[a-z0-9][a-z0-9_-]{0,39}$; cssSelectors (hasta 10) puede ir vacío si hay anchor, pero uno de los dos es obligatorio; urlPatterns hasta 20 |
reach | Veces que se ha visto y clics, desde que existe |
El conector traduce sus propias plantillas a location (por ejemplo, «al final de la ficha de producto» → main, append, /products/*): Spaidoo no conoce los temas de cada plataforma. Un conector que imprime anclajes (un bloque del tema, un hook) pone también anchor, y deja los selectores como sitio en las páginas cuyo tema no lo imprime.
POST /carousels { "kind", "name", "status"?, "productIds"?, "order"?, "maxVisible"?, "minProducts"?, "title"?, "look"?, "location" } → 201 con el carrusel (status por defecto active). PUT /carousels/:id con los campos que cambian → 200; title, look y location se sustituyen enteros; el tipo no cambia. DELETE /carousels/:id → 204.
400 SLIDERS_REQUIRE_PRO: crear encendido o encender un carrusel sin el plan Pro. Crearlo apagado ("status": "paused"), cambiar uno apagado, pausarlo y quitarlo se puede siempre: lo preparado espera a que la tienda cambie de plan.400 BAD_REQUEST: unmanualsin productos,productIdsen un tipo que los elige solo, un título visible sin el idioma de la tienda, o unalocationsinanchornicssSelectors.404 NOT_FOUND: no es un carrusel de la tienda de estos tipos.- Como las escrituras de §4.10, crear y cambiar esperan a las condiciones (
409 TERMS_NOT_ACCEPTED, §4.13). Leer y quitar, no.
4.18 Eventos de integraciones — GET /events
Lo que Spaidoo ha enviado a las herramientas propias de la tienda (§4.19), a medida que pasa: el mismo registro que los eventos en directo del admin de Spaidoo, para que lo muestre el panel del conector. Lo puede leer cualquier plan (lo que pide plan es enviar a una herramienta). Se guarda 30 días. Sin capacidad.
GET /events?event=…&provider=…&productId=…&from=…&to=…&before=…&limit=… (todo opcional) → 200:
{
"items": [
{
"eventId": "3b2f6c1e-8a4d-4f7b-9c2e-1d5a7e9b0c42", "event": "price_drop", "createdAt": "2026-10-14T09:12:05.000Z",
"identified": false, "recipients": 18, "test": false,
"properties": { "old_price": 39.9, "new_price": 29.9, "discount_pct": 25, "currency": "EUR" },
"productId": "7f3c2a10-5b1e-4c8a-9f0d-2e6b8a4c1d90-987",
"product": { "name": "Abrigo de lana", "image": "https://shop.example.com/media/987.jpg", "url": "https://shop.example.com/products/abrigo-de-lana" },
"deliveries": [
{ "provider": "klaviyo", "status": "partial", "counts": { "accepted": 15, "skipped": 3, "failed": 0, "retrying": 0 }, "reasons": { "no_identity": 3 }, "attempts": 1 }
]
}
],
"next": null,
"total": 1
}| Campo | Qué es |
|---|---|
items | Del más reciente al más antiguo, limit por página (1–100, por defecto 50) |
eventId | El id del evento, un UUID: el mismo event_id que recibieron las herramientas |
event | product_saved, product_removed, product_clicked (lo que hizo un visitante), price_drop, back_in_stock, saved_reminder (una fila para todos a quienes afecta), email_consent_granted, email_consent_revoked. Pueden aparecer nombres nuevos; un nombre publicado no cambia nunca |
createdAt | Cuándo pasó. Este registro usa fechas ISO 8601 (UTC), no segundos Unix: igual createdAt, next, before, from y to |
identified | En lo que hizo un visitante: si tenía la sesión iniciada |
recipients | En price_drop, back_in_stock y saved_reminder: a cuántas personas afecta; null en el resto |
properties | Lo que recibieron las herramientas además del producto, como surface (dónde se guardó un producto), origin (de dónde vino un clic: alert, post, carousel, email, push o spaidoo), old_price, new_price, discount_pct y currency (una bajada de precio). Informativo: pueden aparecer más |
test | true en la muestra que envía POST /integrations/:provider/test |
productId | El id de Spaidoo del producto, no el del feed: tómalo tal como viene, para filtrar por ese producto (?productId=). null en un evento sin producto (los consentimientos) |
product | { name, image, url } del catálogo de Spaidoo, en el idioma propio de la tienda (como GET /stats), o null si el producto ya no está |
deliveries | Una por herramienta a la que fue: { provider, status, counts, reasons, attempts }. status: accepted, partial (parte de las personas), failed, skipped (nada que enviar: nadie a quien la herramienta pueda conocer, por ejemplo) o retrying. counts: personas por resultado (una herramienta sin personas, como un webhook, cuenta 1). reasons: por qué no se aceptaron las que no, con cuántas. Vacío si no había ninguna herramienta conectada |
next | Si la página está llena, el before de la siguiente (el createdAt de su última fila); null: no hay más |
total | Cuántas filas encajan con los filtros, contando todas las páginas; solo en la primera página (null en las pedidas con before): quédate con el primero |
Filtros, todos opcionales y combinables: event (un nombre), provider (solo lo que fue a esa herramienta, su id del §4.19), productId (tal como lo devuelve una fila), from y to (fechas y horas ISO 8601, ambas incluidas); before pagina dentro de ellas. 400 VALIDATION_ERROR si una fecha no es ISO 8601 o limit está fuera de rango.
4.19 Las herramientas de la tienda — /integrations
La tienda conecta sus propias herramientas (email marketing como Klaviyo o Mailchimp, analítica como GA4, un webhook propio) y Spaidoo les envía lo que pasa con sus productos y sus clientes (§4.18): las mismas integraciones que en el admin de Spaidoo, desde el panel del conector. Una herramienta conectada recibe todos los eventos que admite; la tienda solo dice adónde (una lista, una URL). Sin capacidad.
GET /integrations → 200:
{
"tier": "growth",
"providers": [
{
"id": "webhook", "brand": { "color": "#303030", "logo": "https://cdn.spaidoo.com/integrations/webhook.svg" },
"auth": "secret", "layer": "server", "minTier": "growth",
"events": ["product_saved", "product_removed", "product_clicked", "price_drop", "back_in_stock", "saved_reminder", "email_consent_granted", "email_consent_revoked"],
"configFields": [{ "key": "url", "type": "url", "required": true }],
"integration": {
"status": "connected", "account": null, "config": { "url": "https://hooks.example.com/spaidoo" },
"health": { "lastSuccessAt": "2026-10-14T09:12:06.000Z", "consecutiveFailures": 0 }, "createdAt": "2026-10-10T16:00:00.000Z"
}
},
{
"id": "klaviyo", "brand": { "color": "#232426", "logo": "https://cdn.spaidoo.com/integrations/klaviyo.svg" },
"auth": "oauth2", "layer": "server", "minTier": "growth", "events": ["product_saved", "price_drop"],
"configFields": [{ "key": "listId", "type": "select", "required": false, "dynamic": true }],
"integration": null
}
],
"upcoming": []
}| Campo | Qué es |
|---|---|
tier | El plan que usa ahora la tienda |
providers | Las herramientas que la tienda puede conectar. Pinta el panel a partir de aquí: Spaidoo añade herramientas sin que el conector cambie |
id | Estable, ^[a-z0-9_-]+$: el :provider de las rutas de abajo |
brand | color (#rrggbb) y logo, un SVG pensado para ese color |
auth | oauth2 (el comerciante inicia sesión en la herramienta, en una ventana), secret (Spaidoo emite un secreto de firma, un webhook) o none |
layer | server (Spaidoo envía los eventos) o browser (el widget se los pasa a la herramienta que la tienda ya carga en sus páginas) |
minTier | El plan que necesita |
events | Los eventos que recibe, todos una vez conectada (§4.18) |
configFields | Lo que pide: { key, type: "string" | "number" | "url" | "select", required, options?, dynamic? }. dynamic: un select cuyas opciones vienen de la cuenta de la tienda en la herramienta, una vez conectada |
integration | La de la tienda, o null si nunca la conectó: { status, account, config, health, createdAt }. status: connected, error (sigue fallando; continúa conectada) o revoked (desconectada). account: { id?, name? } en la herramienta. config: los valores de configFields. health: { lastSuccessAt?, lastErrorAt?, lastError?, consecutiveFailures }. Fechas en ISO 8601 |
upcoming | Herramientas que están en camino, { id, layer, minTier, brand }: muéstralas en gris; todavía no se pueden conectar |
POST /integrations/:provider/connect { "config"?, "rotateSecret"? } → 200:
oauth2:{ "authorizeUrl": "…" }. Ábrela en una ventana nueva, desde el clic del comerciante, nunca en un iframe. La herramienta devuelve al comerciante al admin de Spaidoo, que envía{ "type": "spaidoo:integration-connected", "provider", "status": "ok" | "error", "reason"? }awindow.openery se cierra. Acéptalo solo sievent.origineshttps://admin.spaidoo.com; y como algunas herramientas cortanwindow.opener, vuelve a leer tambiénGET /integrationscada pocos segundos mientras la ventana esté abierta.reason:denied,invalid_state,provider_error,not_configured,token_exchange_failed,internal.secretynone: conectada en el acto,{ "integration": {…}, "secret"? }.secret(el secreto de firma de un webhook) llega solo la primera vez, o con"rotateSecret": true: muéstralo una vez, no vuelve a llegar. Conectar otra vez con otraconfiglo conserva.
PATCH /integrations/:provider { "config": {…} } → 200 { "integration" }: se combina con la actual y se comprueba entera.
DELETE /integrations/:provider → 200 { "integration" } con status: "revoked": se revoca el acceso en la herramienta si lo permite y Spaidoo olvida las credenciales. Ya no le llegan eventos.
POST /integrations/:provider/test → 200 { "queued": true }: Spaidoo envía un evento de muestra (test: true) por el camino real; aparece en GET /events en unos segundos.
GET /integrations/:provider/options/:field → 200 { "options": [ { "value", "label" } ] }: las opciones de un campo dynamic, leídas en ese momento de la cuenta de la tienda en la herramienta.
403 INTEGRATION_REQUIRES_PLANconrequiredTier: conectar, cambiar o probar una herramienta por encima del plan de la tienda. Es un error de plan, no una key muerta (§2): ofrece los planes (§4.12, oPOST /ssoconbilling). Leer y desconectar no piden plan nunca: una tienda que ha bajado de plan puede seguir viendo y apagando lo que tiene.404 INTEGRATION_PROVIDER_UNKNOWN: no hay ninguna herramienta con eseid.404 INTEGRATION_NOT_CONNECTED: cambiar, desconectar, probar o leer las opciones de una herramienta que no está conectada (o estárevoked).400 INTEGRATION_CONFIG_INVALID: laconfigno encaja conconfigFields(falta un campo obligatorio, una URL que no lleva a una dirección pública…), o un campo sin opciones que leer;messagedice cuál.409 INTEGRATION_TEST_UNSUPPORTED: una herramientabrowser: sus eventos pasan en las páginas de la tienda, no hay prueba que enviar.503 INTEGRATION_UNAVAILABLE: la herramienta no se puede conectar o no responde ahora; vuelve a intentarlo más tarde.- Como las escrituras de §4.10, conectar, cambiar y probar esperan a las condiciones (
409 TERMS_NOT_ACCEPTED, §4.13). Leer y desconectar, no.
4.20 Spaidoo Panel para conectores (opcional)
En lugar de construir sus propias pantallas para §4.3.1–§4.19, un conector puede incrustar Spaidoo Panel: las mismas pantallas que las apps propias de Spaidoo (inicio y estado, apariencia, analítica, comunicación, integraciones, importar y exportar, planes, términos), servidas por Spaidoo en https://panel.spaidoo.com y actualizadas sin una nueva versión del conector. El panel no guarda ningún secreto ni llama a nada por sí mismo: cada petición pasa por la página que lo incrusta, el host, por postMessage. El host es la página de admin del conector: un módulo instalado en la tienda, cuyo servidor guarda la API key, o el propio servidor de un conector alojado (el puente alojado queda reservado por ahora; esta sección describe el del módulo).
El panel habla el idioma de admin del comerciante (los mismos 20 que los avisos, §4.14; si no, en) y no decide nada por el nombre de la plataforma: lo que muestra sale de las respuestas de este contrato y del info y las acciones del host.
4.20.1 Incrustación
La página de admin del host pinta un iframe:
https://panel.spaidoo.com/?host=module&platform=<id>&lang=<bcp47>&origin=<urlencoded parent origin>| Parámetro | Qué es |
|---|---|
host | module: el panel habla con la página padre por postMessage. hosted queda reservado |
platform | Una etiqueta libre (el platform del §4.1). Solo se muestra como texto, nunca se decide por ella |
lang | El idioma del usuario de admin; si no, el panel usa en |
origin | El origen de la página padre. El panel solo habla con window.parent y solo acepta mensajes cuyo event.origin sea este |
- Atributos del iframe:
allow="clipboard-write", sinsandbox(el panel abre popups y descarga ficheros). - Para desarrollo, permite configurar la URL del panel en el host (por ejemplo
http://localhost:5180). - El host solo acepta mensajes cuyo
event.originsea el origen del panel que configuró y cuyoevent.sourcesea elcontentWindowdel iframe.
4.20.2 Mensajes y saludo
Cada mensaje es un objeto plano:
{ "source": "spaidoo-panel", "v": 1, "type": "request", "id": "6f1c2e8a-0b3d-4c5e-9a7f-2d4b6c8e0a1f", "nonce": "b3f9a1c7d2e4" }source es spaidoo-panel desde el panel y spaidoo-host desde el host; v es la versión del protocolo; id empareja una petición con su respuesta.
- Panel → host:
{ "type": "hello", "id" }, repetido cada 500 ms hasta que haya respuesta. Tras 20 s sin respuesta, el panel muestra que el host no responde. - Host → panel:
{ "type": "welcome", "id", "nonce", "info" }.noncees aleatorio en cada carga de la página; todos los mensajes posteriores del panel lo llevan.
{
"platform": { "id": "my-platform", "name": "My Platform", "version": "8.1.7" },
"connector": { "version": "3.0.0" },
"lang": "es",
"user": { "id": "12", "name": "Ana", "email": "ana@shop.example.com" },
"shop": { "name": "Mi tienda", "url": "https://shop.example.com", "currency": "EUR" },
"connected": true,
"capabilities": { "privacy": true, "importSources": true }
}langes un código de idioma (es,fr), con región solo donde el panel tiene locales separados:pt-BR/pt-PT,zh-CN/zh-TW.connected: false: la tienda aún no está emparejada; el panel solo muestra su pantalla de conexión (platform.connect, §4.20.4).capabilitiesdice qué acciones opcionales ofrece el host:privacy(la plataforma tiene sus propias herramientas de solicitudes de datos),importSources(wishlists legibles directamente en la plataforma). Las claves desconocidas se ignoran.- Los términos se aceptan con
<platform.id>:<shop url host>:user:<user.id>enacceptedBy(§4.13).
4.20.3 Peticiones a la API: el intermediario del host
Panel → host:
{ "type": "request", "id": "…", "nonce": "…", "method": "GET", "path": "/stats", "query": { "period": "30d" }, "body": null }Host → panel:
{ "type": "response", "id": "…", "status": 200, "body": { "period": "30d" } }pathes relativo a/connector/v1. El servidor del host envía la petición a Spaidoo conAuthorization: Bearer <apiKey>y responde el estado y el cuerpo que dio Spaidoo, errores incluidos.- Lista blanca. El host solo reenvía estos pares de método + ruta (
{id}, un segmento de la ruta) y responde a cualquier otra cosa{ "status": 403, "body": { "errorCode": "PANEL_PATH_NOT_ALLOWED" } }sin llamar a Spaidoo:
| Rutas | Métodos |
|---|---|
/status, /stats, /analytics, /search-analytics, /search-analytics/find, /events, /billing, /plans, /shop-data, /shop-data/export, /integrations, /integrations/{id}/options/{field}, /notifications/{id}/stats, /catalog/products (§4.5.1) | GET |
/widget/state, /widget/appearance, /widget/placement, /widget/save-buttons, /widget/custom-css, /widget/hints, /widget/library-selector | POST |
/automations, /posts, /notifications, /carousels | GET, POST |
/automations/{id}, /posts/{id}, /notifications/{id}, /carousels/{id} | PUT, DELETE |
/posts/image, /posts/{id}/publish, /integrations/{id}/connect, /integrations/{id}/test, /wishlists/import/file, /terms/accept, /sso, /catalog/feeds/read | POST |
/integrations/{id} | PATCH, DELETE |
- Nunca se reenvían, pida lo que pida el panel:
pairing/*,handshake,uninstall,identity-secret/*,customers/*,catalog/changes,PUT /catalog/feeds,shop-redact. Son del propio servidor del conector. - Una respuesta que no es JSON (
GET /shop-data/export) vuelve como{ "status", "headers": { "content-type", "content-disposition" }, "bodyBase64" }; el panel construye el fichero y lo descarga. POST /posts/imagelleva el mismo cuerpo JSON que la ruta (§4.15).GET /status: el host quitaidentitySecret(y cualquier otro campo secreto) del cuerpo antes de responder al panel, y lo guarda y confirma él mismo (§4.2).POST /wishlists/import/filecon clientes por email necesitacustomerLookup(§6.3) aceptada en el handshake; por id de cliente,customers(§4.8.2).- El usuario de admin no tiene el permiso de la plataforma para el panel:
{ "status": 403, "body": { "errorCode": "PANEL_HOST_FORBIDDEN" } }. Sin emparejar:{ "status": 409, "body": { "errorCode": "PANEL_NOT_CONNECTED" } }. Spaidoo inalcanzable o un error de transporte:{ "status": 502, "body": { "errorCode": "PANEL_HOST_UPSTREAM" } }. - El panel espera 60 s una respuesta (120 s para
/wishlists/import/file, un lote cada vez).
4.20.4 Acciones de plataforma
Lo que el panel no puede saber por sí mismo, se lo pregunta al host: panel → host { "type": "action", "id", "nonce", "name", "args" }; host → panel { "type": "result", "id", "ok": true, "data" } o { "type": "result", "id", "ok": false, "error": { "code", "message" } }. Una acción que el host no ofrece responde ok: false con ACTION_UNKNOWN.
name | args → data | Qué hace el host |
|---|---|---|
platform.connect | { mode: "signup" | "login" } → { connected: true } | Abre el popup de emparejamiento (§3.2) desde la página padre: el panel envía la acción desde el clic del comerciante y el host llama a window.open en el acto en su manejador de mensajes, para que el navegador conserve el gesto. Se resuelve cuando el popup responde |
platform.disconnect | – → { connected: false } | POST /uninstall (§4.4) y olvida la API key |
platform.storefront | – → { widgetInstalled, locked, lockReason? } | widgetInstalled: el loader se imprime en la tienda (el conector está activo y enganchado al tema). locked: la tienda está cerrada al público; lockReason maintenance o coming_soon |
platform.carouselZones | – → [ { id, kind, available } ] | Los sitios donde el conector imprime un ancla de carrusel (§7, data-spaidoo-carousel): id home, product, collection o uno propio del conector; kind fixed o custom; available si se imprime ahora |
platform.importSources | – → [ { id, label, customers, items } ] | Wishlists que el host puede leer directamente en la plataforma (un módulo de wishlist anterior, por ejemplo), con cuántos clientes y elementos. Vacío: solo la importación por fichero (§4.8.2) |
platform.importRun | { source, cursor? } → { done, cursor, customers, items, errors } | Un lote de una importación directa, enviado con POST /wishlists/import (§4.8). El panel la vuelve a llamar con cursor hasta done |
platform.open | { url, target: "_blank" | "_top" } → {} | Abre una URL desde la página padre (el enlace de POST /sso, el pago de Spaidoo, una página del admin de la plataforma): los bloqueadores de popups confían en el gesto del padre |
platform.verifyDomain | – → { verified, reason? } | Demuestra el dominio de la tienda cuando pasar a live responde 403 SHOP_NOT_VERIFIED (§4.10): POST /domain-verification, sirve el código en su ruta de verificación y luego POST /domain-verification/check (§4.9). Es una acción, no una ruta reenviada, porque el host tiene que servir el código él mismo |
platform.refresh | – → { info } | Repite el handshake (§4.1) si toca y responde un info nuevo (después de conectar, después de un cambio de plan) |
Códigos de error de las acciones (error.code): POPUP_BLOCKED (el navegador bloqueó el popup), CONNECT_CLOSED (el comerciante cerró el popup), CONNECT_CANCELLED (el comerciante canceló en Spaidoo), CONNECT_FAILED, VERIFY_FAILED, ACTION_UNKNOWN. Pueden aparecer códigos nuevos: trata uno desconocido como un fallo con su message.
4.20.5 Avisos
Sin respuesta. Panel → host:
{ "type": "resize", "height" }: el host fija la altura del iframe, para que la página tenga una sola barra de desplazamiento.{ "type": "title", "text" }: el host puede fijardocument.title.
Host → panel (opcional, con el nonce):
{ "type": "viewport", "top", "height" }: la franja del iframe que ve el usuario de admin, en píxeles del propio panel (enteros): por debajo de la cabecera fija del host (una cabecera de admin pegajosa) y dentro de la ventana. Se envía tras elwelcomey al desplazar, al cambiar el tamaño de la ventana y tras cadaresize, solo cuando cambia y nunca con altura0. El panel coloca su barra de guardar, sus diálogos y sus avisos en esa franja; sin él, mide el viewport de la ventana superior, que no conoce la cabecera fija del host.
4.20.6 Seguridad
- La API key nunca sale del servidor del host. El panel no guarda ningún secreto, y nada de lo que tiene vale la pena robarlo.
- El punto del intermediario del host está en el mismo origen que la página de admin del host (no intervienen cookies de terceros) y exige la sesión de admin, el permiso de la plataforma para gestionar los ajustes de la tienda (si no,
403 PANEL_HOST_FORBIDDEN) y un token CSRF. - Los orígenes se comprueban en los dos sentidos (§4.20.1). El nonce ata los mensajes a una carga de la página: un mensaje con un nonce erróneo o sin él se descarta en silencio.
- La lista blanca (§4.20.3) la aplica el host, no el panel: un panel comprometido solo puede llegar a las rutas del panel.
5 Identidad — identity
Objetivo: un cliente con sesión iniciada en la tienda ve los mismos productos guardados en todos sus dispositivos y puede vincularlos a una cuenta de Spaidoo. Mientras la tienda tiene un conector con identidad, manda la sesión de la tienda: Spaidoo nunca pide al cliente que inicie sesión en la tienda en nombre de Spaidoo.
5.1 La ruta de identidad (urls.identity)
El widget la llama desde la tienda, en el mismo origen, con las cookies de la tienda:
GET <urls.identity>?anon=<uuid>
| Respuesta | Cuándo |
|---|---|
200 { "assertion": "<assertion>" } | Hay un cliente con sesión iniciada |
200 { "anonymous": true } | No hay nadie con sesión iniciada (los invitados cuentan como nadie) |
410 | El conector está desconectado |
Cabeceras: Cache-Control: no-store, private y Vary: Cookie. NUNCA debe guardarla en caché una caché de páginas ni un CDN.
5.2 La aserción
payload = base64url( JSON ), no padding
signature = base64url( HMAC-SHA256( key = identity secret as UTF-8 text, data = payload ) )
assertion = payload + "." + signatureJSON:
{ "v": 1, "shopId": "7f3c…", "customerId": "123", "email": "", "anonId": "<the anon query param or null>", "iat": 1759219200, "exp": 1759219260, "jti": "<32 hex chars, random>" }exp - iat≤ 60 s. Spaidoo tolera 30 s de desfase de reloj.jties de un solo uso.anonIdrepite?anon=si es un UUID; si no,null.emailDEBE ser"": Spaidoo no guarda los emails de los clientes de la tienda (ver §6.2).
5.3 La pista de sesión (opcional, recomendada)
Para que el widget detecte un inicio o un cierre de sesión sin preguntar en cada página, el conector imprime en SpaidooConfig.shopSession (§7):
"" cuando no hay nadie con sesión iniciada; si no, los primeros 16 caracteres hex de HMAC-SHA256(identity secret, "session:" + customerId).
Es una pista, no una prueba: el widget solo la usa para decidir cuándo volver a llamar a la ruta de identidad.
5.4 Inicio de sesión
Cuando el cliente quiere conservar su lista y no tiene la sesión iniciada, el widget lo envía a urls.login con {back} sustituido por la página en la que estaba, codificada para URL. Después del inicio de sesión, la tienda DEBE redirigirlo de vuelta a ella (solo en el mismo dominio).
6 Spaidoo → tienda (llamadas firmadas)
6.1 Firma
Cada llamada que Spaidoo hace a una URL del conector (salvo las públicas verify y feed) lleva:
| Cabecera | Valor |
|---|---|
X-Spaidoo-Timestamp | Segundos Unix |
X-Spaidoo-Nonce | 32 caracteres hex aleatorios |
X-Spaidoo-Signature | base64url( HMAC-SHA256( identity secret, timestamp + "." + nonce + "." + rawBody ) ) |
El conector DEBE:
- rechazar un timestamp a más de 300 s de su reloj (
401); - comparar la firma en tiempo constante sobre el cuerpo en bruto (
401); - DEBERÍA recordar los nonces durante 600 s y rechazar uno repetido (
401).
6.2 POST <urls.customers> — customers
{ "customerIds": ["123", "124"] }Hasta 500 ids. Responde 200:
{ "customers": [ { "customerId": "123", "email": "ana@example.com", "marketingConsent": true, "marketingState": "subscribed", "marketingUpdatedAt": "2026-09-14T08:30:00Z" } ] }- Omite los clientes que ya no existen, los invitados y los borrados.
marketingConsent:trueel cliente está suscrito a los emails de marketing de la tienda (alta en la newsletter),falseno lo está,nullla plataforma no lo sabe. Estruejusto cuandomarketingStatees"subscribed".marketingState:"subscribed","not_subscribed","unsubscribed","pending"onull."unsubscribed": el cliente se dio de baja expresamente; la plataforma que no sepa distinguirlo de no haberse suscrito nunca responde"not_subscribed"."pending": falta que el cliente confirme un doble opt-in.null: la plataforma no lo sabe.marketingUpdatedAt: ISO-8601, cuándo cambió el estado por última vez, onullsi la plataforma no lo sabe.marketingStateymarketingUpdatedAtson opcionales, para que los conectores escritos antes sigan funcionando; si faltan, Spaidoo los toma comonull.- Spaidoo usa la respuesta en ese momento (una exportación, la audiencia de una campaña, una sincronización con la herramienta de email del comerciante) y no guarda los emails.
- Responde en menos de 5 s.
410si está desconectado.
Qué hace Spaidoo con marketingConsent cuando el comerciante sincroniza con una herramienta de email (Klaviyo, Mailchimp…): true → suscrito al email marketing; false/null → perfil sin suscripción de marketing (solo flujos transaccionales).
6.3 POST <urls.customers> por email — customerLookup
El comerciante sube en el panel de Spaidoo las listas exportadas de otra app de wishlist. Esos ficheros identifican al cliente por su email, así que Spaidoo pregunta a la tienda qué clientes suyos son:
{ "emails": ["ana@example.com", "joan@example.com"] }Hasta 500 emails, misma ruta y firma que §6.2. Responde 200:
{ "customers": [ { "customerId": "123", "email": "ana@example.com" } ] }- Compara los emails sin distinguir mayúsculas. Omite los emails sin cliente en la tienda y los invitados.
- Puede incluir
marketingConsent; aquí no se usa. - Solo los clientes de la respuesta reciben las listas. Spaidoo usa los emails para esta consulta y no los guarda.
- Responde en menos de 5 s.
410si está desconectado.
6.4 POST <urls.marketingConsent> — marketingConsent
Cuando un cliente con sesión iniciada en la tienda acepta, dentro del widget, recibir los emails de la tienda, Spaidoo pide a la tienda que active su consentimiento de email marketing. Spaidoo solo concede el consentimiento; nunca da de baja a nadie (eso lo hace el cliente en la tienda o desde cualquier email).
Spaidoo solo la llama para un cliente con sesión en la tienda (§5) cuyo estado (§6.2) sea "not_subscribed" o "unsubscribed", y solo después de que el cliente pulse que sí. Por iniciativa propia (al guardar un producto) Spaidoo solo pregunta a los "not_subscribed" y a los "unsubscribed" desde hace más de 30 días; el cliente que abre la ventana de avisos puede volver a activarlo cuando quiera.
Firmada exactamente como §6.1:
{ "customerId": "123", "textVersion": "shop-marketing-save-v1", "consentedAt": "2026-10-07T10:00:00Z" }textVersionidentifica el texto exacto que aceptó el cliente. Spaidoo guarda la prueba del consentimiento: quién, cuándo y qué versión del texto.consentedAt: ISO-8601, cuándo dijo que sí el cliente.
El conector pone en la plataforma el consentimiento de email marketing del cliente como suscrito (opt-in simple). Si ya estaba suscrito, no cambia nada y responde lo mismo (idempotente). Si la tienda exige doble opt-in, la plataforma puede dejarlo pendiente de confirmación y responder "pending".
Responde 200:
{ "customerId": "123", "marketingState": "subscribed" }marketingState es "subscribed" o "pending".
Errores: 400 cuerpo mal formado, 401 firma incorrecta, timestamp fuera de margen o nonce repetido, 404 cliente desconocido, 405 no es POST, 410 tienda desconectada, 503 ha fallado la plataforma.
7 Tienda
Lo que el conector imprime en las páginas de la tienda (en todas salvo las excluidas):
<script data-spaidoo-config='{"currency":"EUR","shopSession":"","priceFormat":{"currency":"EUR","sample":"€1.234.567,89"},"themeId":"148392011","push":{"swUrl":"https://shop.example.com/spaidoo/push-sw.js","swScope":"/spaidoo-push/"}}'>
(function (s) { window.SpaidooConfig = Object.assign(window.SpaidooConfig || {}, JSON.parse(s.getAttribute('data-spaidoo-config'))); })(document.currentScript);
</script>
<script src="{scriptUrl}" async></script>window.SpaidooConfig — todas las claves son opcionales:
| Clave | Valor |
|---|---|
currency | Código ISO de la moneda en la que navega el visitante. El widget muestra los precios en ella (desde spaidoo:price) |
shopSession | Pista de sesión (§5.3) |
priceFormat | { currency, sample }: cómo escribe la tienda los precios en la moneda del visitante. sample es el formato de la propia plataforma del importe 1234567.89 en currency, en texto plano (lo que escriba el formato de precios de la propia plataforma en sus plantillas), p. ej. "€1.234.567,89" o "1 234 567,89 €". Como conoce las cifras, el widget lee los separadores decimal y de miles, los decimales y el lado y el espacio del símbolo, y escribe sus precios igual, sea cual sea el idioma de la página. Se omite cuando la plataforma no lo sabe; entonces el widget los escribe a la manera estándar del idioma y la moneda |
themeId | El diseño actual de la tienda, como lo identifique la plataforma (el id del tema publicado, o su nombre). El widget lee de la página cómo escribe la tienda el nombre y el precio de un producto (el aspecto de las tarjetas de los carruseles, §4.17) y Spaidoo lo guarda para todos; cuando themeId cambia, el widget lo vuelve a leer en lugar de esperar a que caduque. Se omite si la plataforma no lo sabe |
preview | true solo para el personal de la tienda mientras el widget está en modo preview |
push | { swUrl, swScope } cuando se declara push |
- No imprimas nunca el script en el carrito, el checkout ni las páginas de pago, e inclúyelas en
storefront.excludePaths(§4.1): el widget no se ejecuta ahí, así que no aparece nada de Spaidoo (botón, iconos de guardar, carruseles). - Una caché de página completa debe guardar una copia por moneda (como ya hace con los precios).
Botones de guardar (opcional): donde el tema deba mostrar el icono de guardar de Spaidoo, imprime un anclaje vacío. El widget dibuja el icono y gestiona el clic y el estado.
<span data-spaidoo-save
data-sp-context="product" <!-- "product" (product page) or "list" (cards) -->
data-sp-id="123" <!-- product id of the feed -->
data-sp-url="https://shop.example.com/p/123"
data-sp-name="Blue shirt" <!-- optional -->
data-sp-image="https://…/123.jpg"></span> <!-- optional -->Su diseño y su tamaño vienen del panel de Spaidoo (§4.3); el widget no añade ningún layout propio. Si va sobre una foto, el anclaje se coloca en la esquina que indica saveAnchors.position.
Enlace a la biblioteca (opcional): cualquier elemento con data-spaidoo-library abre la lista del cliente (p. ej. una entrada del menú de la cuenta).
Sitios para carruseles (opcional): donde el tema tenga hueco para los carruseles inteligentes de Spaidoo (§4.17), imprime un anclaje vacío y con nombre. El widget monta dentro los carruseles activos cuya location.anchor sea uno de sus nombres, en su orden; un carrusel cuyo anclaje no está en la página va a sus cssSelectors. Un anclaje puede responder a varios nombres separados por espacios, y con un mismo nombre en varios anclajes vale el primero de la página: así una página puede tener varias zonas, cada una con su nombre, y además el nombre de la página para los carruseles puestos antes de que tuviera ninguna.
<div data-spaidoo-carousel="product"></div> <!-- debajo de la ficha de producto -->
<div data-spaidoo-carousel="home-banner home"></div> <!-- una zona de la portada -->- Nombres:
^[a-z0-9][a-z0-9_-]{0,39}$. Los convencionales sonhome,product(ficha de producto) ycollection(listados de productos); cualquier otro es un sitio propio de la tienda, que se nombra en el admin de Spaidoo. En el carrito y el checkout no hay carruseles: el widget no se carga nunca ahí (arriba), así que no imprimas anclajes en esas páginas. - Imprímelo vacío y sin altura: en la mayoría de páginas no hay carrusel para él. Cuando el widget ha mirado, marca el elemento con
data-spaidoo-filled(ha montado algo) odata-spaidoo-empty(nada para él en esta página). - Para que la página no salte cuando llega un carrusel, el tema puede reservar su altura con
--spaidoo-carousel-reserve(por ejemplostyle="--spaidoo-carousel-reserve: 380px"); la reserva la aplica el CSS del propio tema, porque tiene que estar antes de que llegue el widget, y el widget solo marca el anclaje condata-spaidoo-filledodata-spaidoo-empty. Por ejemplo:[data-spaidoo-carousel]:not([data-spaidoo-filled]):not([data-spaidoo-empty]) { min-height: var(--spaidoo-carousel-reserve, 0) }. Conviene que el tema la libere también al cabo de unos segundos por si el widget no llega a cargar.
7.1 Service worker de push — push
El web push se registra en el dominio de la tienda, así que el conector sirve el service worker de Spaidoo en urls.pushWorker:
Content-Type: application/javascript,Cache-Control: no-cache.Service-Worker-Allowed: <pushScope>cuando el alcance está fuera del directorio del propio worker. Un worker servido dentro de su alcance (/apps/spaidoo/push-sw.jsconpushScope/apps/spaidoo/, detrás del proxy de apps de una plataforma, por ejemplo) no necesita la cabecera.- Cuerpo: el worker de referencia publicado en
https://cdn.spaidoo.com/connector/v1/push-sw.js(cópialo tal cual; no lo cargues conimportScriptsdesde otro origen). - Recibe mensajes solo de datos
{ title, body, link, seen, icon, image, badge, shopId }.linkpasa por el seguimiento de Spaidoo, que cuenta el clic y la lectura y lleva a la tienda.seenlo llama el worker con un POST en cuanto muestra la notificación, para que cuente como vista.
7.2 Lo que el widget le dice a la página (opcional)
Un script propio del conector en la tienda (el que coloca los anclajes de guardado sobre las fotos, por ejemplo) puede leer lo que el loader y el widget de Spaidoo dejan en la página. Solo es estable lo siguiente:
| Qué es | |
|---|---|
SpaidooConfig.merchantId | El id de la tienda, que escribe el loader de Spaidoo en cuanto se ejecuta (no está mientras el widget está en off, ni en preview para un visitante sin el enlace de vista previa ni SpaidooConfig.preview). Dice que el loader se ha ejecutado, no que el widget vaya a arrancar: en una página excluida (§4.1) el loader se para justo después de escribirlo. Antes de colocar nada, espera a spaidoo:anchor-ready |
SpaidooConfig.saveAnchors | { position, product?, list?, header?, listPhoto?, productPhoto? }, lo mismo que store.pluginConfig.saveAnchors (§4.3), que el loader solo escribe cuando algo difiere de lo de por defecto: product, list y header solo aparecen como false. Si no está: todo activado, top-right |
SpaidooConfig.searchHeader | true si el buscador está encendido y el comerciante quiere abrirlo desde la cabecera; si no, no viene. El conector aprovecha el acceso de búsqueda que ya tenga el tema, o pone uno propio junto al carrito, y abre el buscador con spaidoo:show-section |
SpaidooConfig.icon | "heart" si el símbolo de la tienda es el corazón; si no está: el marcador. Para un icono de cabecera propio del conector que encaje con el del widget |
spaidoo:anchor-ready | Un CustomEvent en cada anclaje de guardado (data-spaidoo-save), que sube hasta document, cuando el widget lo ha pintado, o lo ha ocultado porque su tipo de página está desactivado. Sin detail |
spaidoo:panel-open / spaidoo:panel-close | En window, cada vez que se abre o se cierra el panel de la lista. Sin detail |
spaidoo:show-section | Lo envía la página a window con detail: { section: "library" }: el widget abre la lista del cliente. Con { section: "search" } abre el buscador, y la confirmación es spaidoo:search-open. Antes de que el widget arranque no lo atiende: vuelve a enviarlo hasta que llegue spaidoo:panel-open (unas cuantas veces, con unos cientos de ms entre una y otra) |
Ninguno de estos eventos se puede cancelar. Cualquier otra clave de SpaidooConfig u otro evento del widget es interno y puede cambiar.
8 Conformidad
Un conector es compatible con Spaidoo v1 cuando la comprobación de conformidad en línea pasa sin fallos en todas las capacidades que declara.
Conecta una instalación de prueba de tu plataforma con tu conector (cualquier tienda accesible desde internet: un dominio de staging, o un túnel como ngrok o Cloudflare Tunnel para una local) y lanza la comprobación desde la página de desarrolladores con la API key de esa tienda. Spaidoo ya tiene el handshake y el identity secret, así que ningún secreto se pega en ninguna parte.
La misma comprobación está disponible para tus propias herramientas:
POST /connector/v1/conformance{ "shop"?: "<product page>", "checkout"?: "<cart page>", "cookie"?: "<Cookie header of a signed-in test customer>", "customer"?: "<customer id>" }→202 { "runId": "…" }. Las páginas deben estar en los dominios de la tienda. Diez ejecuciones por hora y tienda (429+Retry-After).GET /connector/v1/conformance/{runId}→{ "status": "running" }y luego{ "status": "done", "conformant": true|false, "counts": {…}, "results": [ { "capability", "title", "status": "pass"|"fail"|"warn"|"skip", "detail"?, "spec"? } ] }. Se conserva una hora.
Comprueba el handshake (con la URL que necesita cada capacidad declarada: customerLookup la ruta de clientes, marketingConsent, push, billing.platform y panel.widget las suyas), los feeds y sus artículos, la ruta de identidad y sus aserciones, la ruta firmada customers (nonce, firma, cuerpo en bruto, antigüedad, límites, marketingState y marketingUpdatedAt si vienen y de acuerdo con marketingConsent, y la consulta por email con customerLookup), la ruta firmada marketingConsent sin conceder nada (un cliente que no tiene ninguna tienda debe responder 404; un nonce repetido, una firma incorrecta y una petición de hace más de 300 s, 401; un cuerpo sin customerId, 400; un GET, un 4xx), la ruta de verificación, el service worker de push y la tienda (loader, SpaidooConfig, anclajes de guardado, nada en el checkout). Las llamadas del conector a Spaidoo (catalog.changes, customerErase, wishlistImport, billing.platform) y el panel propio del conector (panel.widget) se listan con cómo comprobarlas a mano. Conceder el consentimiento de verdad se comprueba a mano: di que sí a los emails de la tienda en el widget con un cliente de prueba con sesión iniciada y busca el consentimiento en la plataforma.
Las lecturas y escrituras del panel que no tienen capacidad (/catalog/products, §4.5.1; /stats y /analytics, §4.3.1 y §4.3.2; /plans, §4.12.1; los avisos, anuncios, notificaciones y carruseles, §4.14–§4.17; los eventos de integraciones y las herramientas de la tienda, §4.18 y §4.19) no forman parte de la comprobación: un conector puede ofrecer cualquiera de ellas, y la comprobación no dice nada de ellas. Tampoco Spaidoo Panel (§4.20): comprueba a mano la lista blanca del host y sus acciones.
9 Cambios
| Fecha | Cambio |
|---|---|
| 2026-09-30 | Primer borrador |
| 2026-09-30 | Emparejamiento con OAuth 2 + PKCE y apps de conector registradas (§3); URL de servidor en los dominios de la app y storefront.domains (§4.1); worker de push dentro de su alcance (§7.1) |
| 2026-10-01 | Secreto de cliente para las apps alojadas y alta automática: el servidor del conector da de alta la tienda él mismo (§3.1, §3.4) |
| 2026-10-04 | Plan cobrado por la plataforma: capacidad billing.platform, urls.billing, adminDomains y billingPlatform de la app, PUT/GET /billing (§1, §3.1, §4.1, §4.12). Condiciones de Spaidoo aceptadas desde el conector, 409 TERMS_NOT_ACCEPTED en las escrituras (§4.10, §4.13). /status documentado campo a campo, con store.billing, store.termsAccepted, store.termsVersion, store.termsUrls, stats.alertsSent y stats.alertClicks (§4.3). Cifras por periodo, GET /stats (§4.3.1). Los datos de un cliente para su solicitud de acceso, POST /customers/export (§4.7.1). Lo que trajo un conector desinstalado, borrado con el secreto de la app, POST /shop-redact (§3.5). Importación por filas con simulación (§4.8.1). theme en la apariencia y los errores de cada escritura (§4.10). Intents reports y billing; un intent desconocido cae en panel (§4.11). Desconectar es POST /uninstall (§4.4). platform.name, panel.widget y urls.panel (§4.1); 409 BILLING_STRIPE_ACTIVE y la facturación de vuelta a Spaidoo tras cancelled y una desinstalación (§4.12); feeds en solo lectura en el admin de Spaidoo mientras los publique un conector, 409 FEEDS_MANAGED_BY_CONNECTOR (§4.5) |
| 2026-10-05 | Botón de guardar, selector propio del icono de la lista y CSS propio por pieza (§4.10, §4.10.1). topViewed en GET /stats, los tres periodos calculados a la vez (§4.3.1). La página de analítica, GET /analytics (§4.3.2) |
| 2026-10-06 | Avisos automáticos desde el panel del conector: GET/POST /automations, PUT/DELETE /automations/:id (§4.14). savedRevisits sustituye a saveToClick en GET /analytics (§4.3.2). El texto final de un aviso, en cualquier idioma de los avisos, con el de la tienda obligatorio: languages y primaryLanguage, 400 NOTE_LANGUAGE_MISSING (§4.14). Tablón de anuncios desde el panel del conector: GET/POST /posts, PUT/DELETE /posts/:id, POST /posts/:id/publish, POST /posts/image; el anuncio, en cualquier idioma de los avisos con el de la tienda obligatorio; la lista, por páginas con status, search y cursor, y counts (§4.15). Notificaciones desde el panel del conector: GET/POST /notifications, PUT/DELETE /notifications/:id, 409 NOTIFICATION_ALREADY_SENT; el texto de una notificación, en cualquier idioma de los avisos con el de la tienda obligatorio; la lista, por páginas con status, search y cursor, y counts; GET /notifications/:id/stats; validUntil, hasta cuándo vale (§4.16). Carruseles inteligentes desde el panel del conector: GET/POST /carousels, PUT/DELETE /carousels/:id, título por idioma (§4.17) |
| 2026-10-07 | El estado de email marketing del cliente en la respuesta de customers: marketingState y marketingUpdatedAt, opcionales (§6.2). El sí del cliente a los emails de la tienda desde el widget: capacidad marketingConsent, urls.marketingConsent, POST <urls.marketingConsent> (§1, §4.1, §6.4) |
| 2026-10-08 | Los clientes y contactos de la tienda para que el comerciante se los lleve, GET /shop-data y GET /shop-data/export; los contactos vienen con Growth o superior, contactsLocked (§4.7.2). Los textos del widget desde el conector, POST /widget/hints, y hints / hintLanguages en /status (§4.10, §4.3). seen en el mensaje de push, que el worker de referencia llama al mostrarla; link siempre presente (§7.1) |
| 2026-10-08 | minProducts en los carruseles (§4.17). Sitios para carruseles en la tienda, data-spaidoo-carousel (§7), y location.anchor en los carruseles, cssSelectors opcional si lo hay; el tipo saved_together y productPage en kinds; los tipos personales y saved_together pasan a lo más guardado cuando salen vacíos (§4.17) |
| 2026-10-08 | §7 SpaidooConfig.priceFormat: cómo escribe la tienda sus precios, una muestra del formato de la propia plataforma; y SpaidooConfig.themeId, el diseño actual de la tienda |
| 2026-10-09 | Cifras y analítica de cualquier rango de días: from/to en GET /stats y GET /analytics, period: "custom", 400 STATS_RANGE_INVALID (§4.3.1, §4.3.2) |
| 2026-10-09 | Aviso automático back_in_stock: un producto guardado que estaba agotado (ninguna variante con stock) vuelve a estar disponible; Pro, push, sin ajuste, con productos (§4.14). opportunities.unavailable separa agotados y retirados (§4.3.2) |
| 2026-10-13 | El botón flotante colocado por píxeles desde el conector: position: "custom" y offsets en POST /widget/placement y en /status, 400 INVALID_PLACEMENT; se retira 409 PLACEMENT_IS_CUSTOM (§4.10, §4.3). Alta automática: panel_url, y una tienda del directorio entregada en el acto a las apps propias de Spaidoo (§3.4) |
| 2026-10-15 | El widget no se carga nunca en el carrito, el checkout ni las páginas de pago: se incluyen todas en storefront.excludePaths, y cart deja de ser un sitio convencional de carrusel (§4.1, §7). Sin nombres de plataformas en el texto (§3.5, §4.7.2, §7) |
| 2026-10-15 | Eventos de integraciones, GET /events, y las herramientas de la tienda, /integrations (en la API desde el 2026-10-09; §4.18, §4.19). Solo 401 significa una key muerta; un 403 es de la llamada (§2). /status campo a campo: offsets, saveButton, searchProvider / aiProvider, spaidooSearch con su plan y sus cuotas, productAnchor / actionsAnchor, brand obsoleto (§4.3). lang, errores y el token del alta automática (§3.4); rotate devuelve también shopId, CONNECTOR_NOT_CONFIGURED (§4.2); reconectar pasa a preview, dominios de otra tienda fuera, pushScope por defecto (§4.1); CATALOG_CHANGE_CURRENCY_MISMATCH, CATALOG_CHANGES_RATE_LIMIT (§4.6); borrar un cliente no pide capacidad (§4.7); los errores del §4.9. Los 20 idiomas de los textos (§4.14–§4.17) y los límites de anuncios, notificaciones, carruseles y feeds (§4.5, §4.15–§4.17). La vista previa del widget (§4.10.2) y lo que el widget le dice a la página (§7.2). Las comprobaciones a mano y lo que la comprobación deja fuera (§8) |
| 2026-10-15 | Los productos de las cifras con nombre: product ({ name, image, url } o null) en cada entrada con productId de GET /stats y GET /analytics (§4.3.1, §4.3.2). Los planes de Spaidoo para la pantalla de planes del conector, GET /plans (§4.12.1). La importación desde un fichero con clientes por email, POST /wishlists/import/file (§4.8.2); CONNECTOR_CAPABILITY_MISSING nombra la capability y los errores de las importaciones van en orden (§4.8.1). El 401 de la key lleva API_KEY_MISSING / API_KEY_INVALID, y el 429 general, RATE_LIMITED (§2). lang acepta una etiqueta corta como pt-BR (§3.4). La comprobación prueba la ruta marketingConsent sin conceder nada, los campos de marketing de customers y la URL de cada capacidad (§8) |
| 2026-10-15 | Los productos de la tienda tal como los tiene Spaidoo, GET /catalog/products: por título (q, sin distinguir mayúsculas ni acentos), por ids o página a página, con título, foto, enlace, precio, precio rebajado y stock (§4.5.1) |
| 2026-10-15 | Spaidoo Panel para conectores: la incrustación, los mensajes del puente, el intermediario del host y su lista blanca, las acciones de plataforma y la seguridad (§4.20) |
| 2026-10-19 | Alta desde el servidor: una tienda nueva con el email de una cuenta que creó tu app ya no se añade sola: 409 SHOP_LINK_CONFIRMATION_REQUIRED hasta que el dueño de la cuenta lo confirma desde el enlace que envía Spaidoo, y resend_confirmation (§3.4) |
| 2026-10-19 | Seguridad: una tienda que ya está en la cuenta solo vuelve sola a la app que la conectó; límites de reenvío y diarios de SHOP_LINK_CONFIRMATION_REQUIRED, y un «no es mía» vale 30 días (§3.4). Una API key nueva cuando la tienda cambia de manos (§4.4). La verificación de dominio demuestra el dominio de la propia tienda, nunca el storeUrl del handshake (§4.9) |
| 2026-10-19 | Cada emparejamiento (§3, §3.4) entrega una API key nueva: Spaidoo solo guarda su hash, así que guarda la que recibas. La URL de SSO abre una página «continuar como |
| 2026-10-19 | 409 SHOP_LINK_UNAVAILABLE cuando no se puede enviar el email del enlace; /pairing/provision/complete acepta su token una sola vez (§3.4) |
| 2026-11-06 | Los contactos se descargan en todos los planes: contactsLocked siempre false y features.contactsExport siempre true (§4.7.2, §4.12.1) |
| 2026-11-06 | El buscador de Spaidoo está en todos los planes: POST /widget/search lo enciende con showSearchButton, sin suscripción. Se retira el complemento Spaidoo Search: fuera spaidooSearch de /status, y el intent spaidoo-search lleva a la página de proveedores (§4.3, §4.10) |
| 2026-11-07 | Abrir el buscador desde la cabecera: POST /widget/search acepta header y selector; nuevos store.pluginConfig.searchHeader y searchSelector, SpaidooConfig.searchHeader, spaidoo:show-section con { section: "search" } y los enlaces a #spaidoo-search |
| 2026-11-06 | El primer catálogo: una tienda sin productos no enseña el widget hasta que Spaidoo ha leído su catálogo, y el buscador se enciende solo con su primer paquete. Nuevo store.catalogSetup (§4.3, §4.5) |
| 2026-11-08 | Qué buscan los clientes: GET /search-analytics (§4.3.3), el informe entero en Growth y Pro y una muestra de los últimos 7 días en Starter |
| 2026-11-08 | /search-analytics: averagePosition por búsqueda y report.trending, las búsquedas que suben o son nuevas |
| 2026-11-08 | POST /widget/search acepta search: el buscador encendido o apagado, aparte de su botón en el flotante (§4.10) |
| 2026-11-09 | GET /search-analytics/find: una lista del informe con un texto, en Growth y Pro (§4.3.3) |