Saltar al contenido

Guía · Connector API v1

Construye un conector, paso a paso

De un proyecto vacío a un conector que pasa la comprobación de conformidad. Cada paso tiene su objetivo, el código mínimo, cómo saber que funciona y enlaces a la especificación, y la mayoría un diagrama.

Paso 0 de 14

Qué vas a construir

Conocer las piezas de un conector, cuáles son obligatorias y cuáles opcionales, antes de escribir código.

Un conector vive dentro de una plataforma de tienda (un módulo, una app, un plugin, un backend headless…) y la conecta con Spaidoo. Declara las capacidades que implementa, y Spaidoo actúa según esa declaración, nunca según el nombre de la plataforma (§1).

La imagen completa: tu conector entre la tienda, el navegador del cliente y SpaidooNavegador del cliente. Plataforma de tienda + tu conector. Spaidoo. Página de la tienda con el widget. Notificaciones push desde el dominio de la tienda. Páginas de la tienda storefront.saveAnchors. Ruta de identidad identity. Service worker de push push. Feed de productos catalog.feed. Ruta customers customers. Ruta de verificación domainVerification. Llamadas a Spaidoo handshake · catalog.changes customerErase · wishlistImport. Loader del widget scriptUrl. Sync de Spaidoo. API de Spaidoo /connector/v1. la página carga el widget. script, SpaidooConfig, anclajes de guardado. ¿quién navega?. lo registra. lo lee cada día. llamada firmada. lee el código. Bearer <apiKey>Navegador del clientePlataforma de tienda + tu conectorSpaidooPágina de la tiendacon el widgetNotificaciones pushdesde el dominio de la tiendaPáginas de la tiendastorefront.saveAnchorsRuta de identidadidentityService worker de pushpushFeed de productoscatalog.feedRuta customerscustomersRuta de verificacióndomainVerificationLlamadas a Spaidoohandshake · catalog.changescustomerErase · wishlistImportLoader del widgetscriptUrlSync de SpaidooAPI de Spaidoo/connector/v1la página carga el widgetscript, SpaidooConfig,anclajes de guardado¿quién navega?lo registralo lee cada díallamada firmadalee el códigoBearer <apiKey>
Las flechas van de quien pregunta a quien responde. Las capacidades están donde viven: rutas que sirve la tienda, lo que imprime en sus páginas y las llamadas que el conector hace a Spaidoo.
CapacidadQué le da a la tienda¿Hace falta?
catalog.feedSpaidoo conoce los productos de la tienda: precio, stock, imágenes.Obligatoria
catalog.changesLos cambios de precio y de stock llegan a Spaidoo en segundos en lugar de en la siguiente lectura diaria.Opcional
identityUn cliente con sesión iniciada conserva sus productos guardados en todos sus dispositivos, sin cuenta de Spaidoo.Opcional
customersSpaidoo puede pedir el email y el consentimiento de marketing de un cliente identificado cuando el comerciante lo necesita.Opcional, con identity
customerLookupLa ruta de clientes también responde por email: el comerciante importa listas desde un fichero exportado de otra app de wishlist (§6.3).Opcional, con identity
marketingConsentUn cliente con sesión iniciada que dice que sí a los emails de la tienda en el widget queda suscrito en la plataforma (§6.4).Opcional, con identity
customerEraseBorrar un cliente en la tienda borra sus datos en Spaidoo para esa tienda.Opcional
wishlistImportLas listas de una extensión de wishlist anterior se traen a Spaidoo.Opcional, con identity
pushLas notificaciones web push se sirven desde el propio dominio de la tienda.Opcional
domainVerificationLa tienda demuestra que es dueña de su dominio sin cambios de DNS.Opcional
storefront.saveAnchorsTu tema imprime los botones de guardar; el widget los dibuja y gestiona el clic.Opcional
billing.platformLa plataforma cobra el plan de Spaidoo de la tienda y el conector lo comunica (§4.12).Opcional, para apps que Spaidoo habilita
panel.widgetTu panel en el admin de la plataforma configura el widget; el admin de Spaidoo enlaza a él en lugar de repetirlo.Opcional, para apps alojadas

Además de las capacidades, tu panel puede darle al comerciante lo mismo que el admin de Spaidoo: los términos, los ajustes del widget y una vista previa en directo, las cifras, los avisos, anuncios, notificaciones y carruseles, y las herramientas propias de la tienda (pasos 11 y 12). Esas rutas no necesitan capacidad.

Cuánto se tarda

Depende de tu plataforma, pero el trabajo se reparte bien. El mínimo son los pasos 2 a 5 (registro, emparejamiento, handshake, feed de productos) más el script del paso 8: con eso, el widget funciona en la tienda con su catálogo. Cada una de las demás capacidades es una pieza independiente: la construyes, la declaras en el handshake y la compruebas por separado.

Por el camino te ayudan tres cosas: la especificación, que es el contrato y siempre manda; la comprobación de conformidad en línea; y, para los partners de Spaidoo, el asistente.

Cómo sabes que funciona

  • Sabes qué capacidades vas a declarar, y que catalog.feed es la única obligatoria.

Paso 1 de 14

Antes de empezar

Tener una tienda de prueba a la que Spaidoo pueda llegar, y las cuentas que necesitas.

  • Una instalación de prueba de tu plataforma, accesible desde internet por https. Spaidoo llama a la tienda (lee el feed, llama a las rutas firmadas, consulta la ruta de verificación), y la comprobación de conformidad también: localhost no basta (§8).
  • Un dominio de staging, o un túnel hacia una tienda que corre en tu máquina: ngrok o Cloudflare Tunnel le dan un host https público.
  • Una cuenta de partner de Spaidoo con acceso al área de desarrolladores. Allí registras tu conector (paso 2), y te abre el asistente (paso 14).
  • Una cuenta de Spaidoo para la tienda de prueba. La creas al emparejar la tienda (paso 3), como lo haría un comerciante.
Una tienda local accesible desde internet a través de un túnelTu tienda, en local http://localhost:8080. Túnel ngrok · Cloudflare Tunnel. Host público https://<tu-host>. Spaidoo API · sync · comprobación. Configura la tienda con el host público como dominio: todas las URL declaradas tienen que ser https en él.. https. reenvíaTu tienda, en localhttp://localhost:8080Túnelngrok · Cloudflare TunnelHost públicohttps://<tu-host>SpaidooAPI · sync · comprobaciónConfigura la tienda con el host público como dominio: todas las URL declaradas tienen que ser https en él.httpsreenvía
Spaidoo y la comprobación de conformidad llaman al host https público de la tienda; el túnel reenvía esas peticiones a la tienda de tu máquina.
Shell
# Either one, pointing at the shop on your machine (port 8080 here)
ngrok http 8080
cloudflared tunnel --url http://localhost:8080

Configura la tienda para que use el host del túnel como su propio dominio. Todas las URL de escaparate que declara el conector tienen que ser https en uno de los dominios de la tienda (§4.1), y también la vuelta de un conector instalado en cada tienda (§3.1).

Ten presentes los dos secretos desde el principio: la API key y el identity secret son secretos de la tienda, se guardan en el servidor y nunca se imprimen en las páginas (§2.1).

Cómo sabes que funciona

  • La tienda se abre por su URL https pública desde otra red (tu móvil con datos, por ejemplo).

Paso 2 de 14

Registra tu conector

Tu conector tiene un client_id, con el que se conecta cada tienda.

Las tiendas se conectan con OAuth 2 y PKCE, como app registrada (§3). Registra tu conector una vez, en Mis conectores, y guarda su client_id: es público, va en la URL que empieza la conexión.

TipoCuándoVuelta
Instalado en cada tienda (shop)Tu conector funciona en el servidor de cada tienda: un módulo, un plugin.Una URL https en el dominio de la tienda que se conecta. No hay nada que registrar.
Alojado (fixed)Tu conector funciona en tus servidores o en los de la plataforma, y el admin del comerciante no está en el dominio de la tienda.Las URL exactas que registras.
  • Dominios de servidor: donde viven tus rutas de servidor (urls.customers), si no están en el dominio de la tienda. Las rutas de escaparate van siempre en los dominios de la tienda (§4.1).
  • La platform de la app (my-platform) es texto libre, solo informativo.

Cómo sabes que funciona

Paso 3 de 14

Empareja la tienda

El comerciante conecta la tienda desde tu admin y tu servidor recibe su API key.

El emparejamiento es un flujo OAuth 2 con PKCE, en un popup: tu admin abre Spaidoo en un popup, Spaidoo devuelve el popup a tu vuelta con un código de un solo uso y tu servidor lo canjea por la API key. El popup solo avisa a tu página de admin de que ya está, y se cierra. La key nunca pasa por el navegador (§3.2).

Emparejamiento: OAuth 2 con PKCE, la key nunca en el navegador1. Servidor de la tienda: state + code_verifier, guardados en el servidor 2. Servidor de la tienda → Spaidoo admin.spaidoo.com/connect: popup a /connect ?client_id&redirect_uri&state &code_challenge&domain 3. Spaidoo admin.spaidoo.com/connect: El comerciante se registra o inicia sesión y acepta los términos (versiones nuevas: en tu panel) 4. Spaidoo admin.spaidoo.com/connect → Servidor de la tienda: redirect_uri?code&state 5. Servidor de la tienda → API de Spaidoo: POST /pairing/token client_id, code, code_verifier 6. API de Spaidoo → Servidor de la tienda: { apiKey, shopId } 7. Servidor de la tienda: Guarda la API key, en el servidor 8. Servidor de la tienda → API de Spaidoo: POST /handshake (siguiente paso)Servidor de la tiendaSpaidooadmin.spaidoo.com/connectAPI de Spaidoo1state + code_verifier,guardados en el servidorpopup a /connect?client_id&redirect_uri&state&code_challenge&domain23El comerciante se registra oinicia sesión y acepta los términos(versiones nuevas: en tu panel)redirect_uri?code&state4POST /pairing/tokenclient_id, code, code_verifier5{ apiKey, shopId }67Guarda la API key,en el servidorPOST /handshake(siguiente paso)8
El código sirve para un solo canje, durante 60 segundos, y solo con el code_verifier que empezó el flujo.
  1. Tu servidor genera un state aleatorio y un code_verifier, guarda los dos (ligados a la sesión del comerciante) y calcula code_challenge = base64url(SHA-256(code_verifier)).
  2. Tu página de admin abre un popup (window.open, con el clic del comerciante) en https://admin.spaidoo.com/connect con client_id, redirect_uri, state, code_challenge, code_challenge_method=S256, el domain de la tienda y, si quieres, name, email, mode y verify (tu urls.verify, solo con domainVerification).
  3. El comerciante se registra o inicia sesión en Spaidoo y acepta los términos.
  4. Spaidoo envía el popup a tu redirect_uri con code y state (o error=access_denied si el comerciante cancela). Comprueba el state.
  5. Tu servidor llama a POST /pairing/token con client_id, code, code_verifier y la misma redirect_uri, en menos de 60 segundos, y recibe { apiKey, shopId }.
  6. Guarda la key y llama a POST /handshake (siguiente paso). La página de vuelta avisa a tu admin con postMessage (solo a tu propio origen y nunca con la key) y cierra el popup.
JavaScript
import { createHash, randomBytes } from "node:crypto";

const CLIENT_ID = "sc_…"; // from My connectors
const REDIRECT_URI = "https://shop.example.com/admin/spaidoo/callback";

// In your admin page: the merchant's click opens the popup.
//   const popup = window.open("/admin/spaidoo/connect", "spaidoo", "width=460,height=780");
//   window.addEventListener("message", (e) => {
//     if (e.origin !== location.origin || e.source !== popup) return;
//     if (e.data?.type === "spaidoo-connected" && e.data.connected) location.reload();
//   });

// 1. The popup starts here and goes on to Spaidoo.
app.get("/admin/spaidoo/connect", (req, res) => {
  const state = randomBytes(16).toString("hex");
  const verifier = randomBytes(48).toString("base64url");
  req.session.spaidoo = { state, verifier };
  const challenge = createHash("sha256").update(verifier).digest("base64url");
  res.redirect(
    "https://admin.spaidoo.com/connect?" +
      new URLSearchParams({
        client_id: CLIENT_ID,
        redirect_uri: REDIRECT_URI,
        state,
        code_challenge: challenge,
        code_challenge_method: "S256",
        domain: "shop.example.com",
        name: "My shop",
        email: "merchant@example.com",
        verify: "https://shop.example.com/spaidoo/verify", // only with domainVerification
      }),
  );
});

// 2. The popup comes back from Spaidoo.
app.get("/admin/spaidoo/callback", async (req, res) => {
  const pending = req.session.spaidoo;
  if (!pending || req.query.state !== pending.state) return res.status(400).send("Start again");

  // A shop of Spaidoo's directory proves its domain first (§3.3).
  if (req.query.verification_code) {
    store.set("verificationCode", req.query.verification_code); // served at urls.verify
    return res.redirect(req.query.resume); // back to Spaidoo, same state
  }

  delete req.session.spaidoo;
  let connected = false;
  if (!req.query.error) {
    const answer = await fetch("https://api-plugin.spaidoo.com/connector/v1/pairing/token", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        client_id: CLIENT_ID,
        code: req.query.code,
        code_verifier: pending.verifier,
        redirect_uri: REDIRECT_URI,
      }),
    }).then((r) => r.json());
    store.set("apiKey", answer.apiKey); // server-side, never in a page
    await handshake(); // next step
    connected = true;
  }

  // 3. Tell the admin page (same origin, never the key) and close the popup.
  res.send(`<script>
    window.opener?.postMessage({ type: "spaidoo-connected", connected: ${connected} }, location.origin);
    window.close();
  </script>`);
});

Una tienda que ya está en el directorio de Spaidoo

Si el dominio ya pertenece a una tienda del directorio de Spaidoo, solo se entrega cuando se demuestra el dominio. Cuando pasas verify, Spaidoo vuelve primero a tu vuelta con verification_code y resume: guarda el código para que urls.verify lo sirva (paso 9), conserva el code_verifier y envía el popup a resume. El código llega después, con el mismo state (§3.3).

Qué guardar, y dónde

  • La API key, en el servidor (la configuración o la base de datos de tu plataforma), nunca en una página. Va como Authorization: Bearer <apiKey> en cada llamada a https://api-plugin.spaidoo.com/connector/v1 (§2, §2.1).
  • Solo un 401 de Spaidoo significa que la key ya no es válida: muestra la tienda como desconectada. Un 403 es de esa llamada (un plan que la tienda no tiene, un dominio aún sin demostrar): su errorCode dice por qué, y la tienda sigue conectada. Un 5xx o un fallo de red solo significa «prueba más tarde»: la tienda tiene que seguir funcionando cuando Spaidoo no responde (§2).

Una app alojada puede saltarse el popup

Un conector alojado en tus servidores o en los de la plataforma puede dar de alta la tienda desde su servidor con su client secret, sin mandar al comerciante a ningún sitio: mira el paso 10 (§3.4).

Cómo sabes que funciona

  • Tu servidor tiene una key y GET /status con ella responde 200 con el store de la tienda (§4.3).

Paso 4 de 14

El handshake

Decirle a Spaidoo qué puede hacer tu conector y dónde, y quedarte con lo que acepta.

POST /handshake declara tus capacidades, las URL de tus rutas y los ajustes de la tienda. Es idempotente (§4.1).

El handshake: declarar, quedarse con lo aceptado, confirmar el secreto1. Servidor de la tienda → API de Spaidoo: POST /handshake capabilities, urls, storefront 2. API de Spaidoo → Servidor de la tienda: 200 shopId, capacidades aceptadas, identitySecret (cuando toca) 3. Servidor de la tienda: Guarda el id de tienda, las capacidades aceptadas y el secreto 4. Servidor de la tienda → API de Spaidoo: POST /identity-secret/ack { fingerprint } 5. API de Spaidoo → Servidor de la tienda: { acknowledged: true } 6. Servidor de la tienda → API de Spaidoo: GET /status 7. API de Spaidoo → Servidor de la tienda: connector: tu declaración, sin identitySecret si confirmadoServidor de la tiendaAPI de SpaidooPOST /handshakecapabilities, urls, storefront1200 shopId, capacidades aceptadas,identitySecret (cuando toca)23Guarda el id de tienda,las capacidades aceptadasy el secretoPOST /identity-secret/ack{ fingerprint }4{ acknowledged: true }5GET /status6connector: tu declaración,sin identitySecret si confirmado7
Spaidoo responde con las capacidades que ha aceptado y, cuando toca, el identity secret, que sigue devolviendo hasta que lo confirmas.

Empieza por poco. Este cuerpo declara solo la capacidad obligatoria; activa las demás a medida que las construyas:

JSON
{
  "contractVersion": 1,
  "platform": { "id": "my-platform", "version": "3.2.0", "name": "My Platform" },
  "connector": { "version": "1.0.0" },
  "storeUrl": "https://shop.example.com",
  "storeName": "My Shop",
  "testShop": true,
  "capabilities": {
    "catalog.feed": true,
    "catalog.changes": false,
    "identity": false,
    "customers": false,
    "customerLookup": false,
    "marketingConsent": false,
    "customerErase": false,
    "wishlistImport": false,
    "push": false,
    "domainVerification": false,
    "storefront.saveAnchors": false,
    "billing.platform": false,
    "panel.widget": false
  },
  "urls": {},
  "storefront": { "excludePaths": ["^/checkout", "^/cart"] },
  "identitySecretFingerprint": null
}
  • Declara solo lo que implementas. Una URL solo es obligatoria para una capacidad declarada que la necesite. Todas tienen que ser https: las de escaparate en uno de los dominios de la tienda, las de servidor (customers) allí o en los dominios de servidor de tu app. storefront.domains añade otros dominios en los que se sirve el escaparate (§4.1).
  • login tiene que contener la marca literal {back}, sin codificar (paso 6).
  • storefront.excludePaths: expresiones regulares (sin distinguir mayúsculas) sobre la ruta + query donde el widget no debe ejecutarse nunca: el carrito, el checkout y las páginas de pago.
  • identitySecretFingerprint: el SHA-256 (hex) del identity secret que guardas, o null si no guardas ninguno. Así un conector reinstalado consigue un secreto nuevo por su cuenta.
  • testShop: true cuando la plataforma dice que es una tienda de desarrollo o de pruebas: queda fuera de las cifras de Spaidoo. platform.name es el nombre de tu plataforma tal como lo conocen los comerciantes, para los textos de Spaidoo. storeName es el nombre de la tienda tal como lo ven sus clientes: envíalo en cada handshake y vuelve a hacer el handshake cuando la tienda cambie de nombre, para que los textos del widget lo sigan.
  • Una tienda que se conecta por primera vez empieza con el widget en preview: conectar no es publicar (paso 11).

Spaidoo responde con el id de la tienda, las capacidades que ha aceptado y, cuando tienes que guardar uno nuevo, el identity secret:

JSON
{
  "shopId": "7f3c…",
  "contractVersion": 1,
  "capabilities": { "catalog.feed": true },
  "identitySecret": "b64url…"
}
JavaScript
import { createHash } from "node:crypto";

const API = "https://api-plugin.spaidoo.com/connector/v1";

async function spaidoo(method, path, body) {
  const res = await fetch(API + path, {
    method,
    headers: { Authorization: `Bearer ${store.get("apiKey")}`, "Content-Type": "application/json" },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  if (res.status === 401) store.set("connected", false); // only a 401 means the key is dead: show "disconnected"
  if (!res.ok) throw new Error(`Spaidoo ${res.status}`); // 5xx, network: try later, never break the shop
  return res.status === 204 ? null : res.json();
}

const answer = await spaidoo("POST", "/handshake", handshakeBody());
store.set("shopId", answer.shopId);
// Act on what Spaidoo accepted, not on what you declared.
store.set("capabilities", answer.capabilities);

if (answer.identitySecret) {
  store.set("identitySecret", answer.identitySecret); // server-side only, never printed
  const fingerprint = createHash("sha256").update(answer.identitySecret).digest("hex");
  await spaidoo("POST", "/identity-secret/ack", { fingerprint });
}
  • Compórtate según la lista aceptada. Una capacidad se rechaza (se omite, no es un error) cuando Spaidoo la tiene desactivada; customers, customerLookup, marketingConsent y wishlistImport se rechazan sin identity; billing.platform y panel.widget se rechazan si Spaidoo no ha preparado tu app para ellas (paso 10).
  • Confirma cada secreto que recibas, después de guardarlo: POST /identity-secret/ack con su huella. Hasta entonces, Spaidoo lo sigue devolviendo en /handshake y /status (§4.2).
  • Tras una rotación, Spaidoo sigue aceptando el secreto anterior hasta que se confirma el nuevo, y 10 minutos más: una respuesta perdida no rompe la tienda.

Cuándo repetir el handshake

  • Después del emparejamiento.
  • Después de cada actualización de tu conector.
  • Cada vez que cambie una URL o una capacidad.

Errores que hay que tratar: 400 CONNECTOR_CATALOG_REQUIRED (sin catalog.feed), 400 CONNECTOR_URL_INVALID con el field que falla, y 400 CONNECTOR_EXCLUDE_PATH_INVALID.

Cómo sabes que funciona

  • POST /handshake responde 200 con tus capacidades en capabilities.
  • GET /status muestra tu declaración en connector y deja de traer identitySecret cuando lo has confirmado.
  • La comprobación de conformidad (paso 13) comprueba el handshake.

Paso 5 de 14

El catálogo

Spaidoo conoce los productos de la tienda: por un feed que lee cada día, y después por los cambios que le envías.

El feed: catalog.feed (obligatoria)

Un feed de productos de Google Merchant (RSS 2.0 o Atom) con un ítem por variante. Sirve uno por idioma y registra la lista completa: un idioma que no esté en ella se elimina (§4.5).

HTTP
PUT /connector/v1/catalog/feeds
Authorization: Bearer <apiKey>
Content-Type: application/json

{ "feeds": [ { "language": "en", "url": "https://shop.example.com/spaidoo/feed?lang=en" } ] }
XML
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:g="http://base.google.com/ns/1.0">
  <channel>
    <title>My shop</title>
    <link>https://shop.example.com</link>
    <description>My shop's products</description>
    <item>
      <g:id>123-1</g:id>
      <g:item_group_id>123</g:item_group_id>
      <g:title>Blue shirt</g:title>
      <g:link>https://shop.example.com/p/123</g:link>
      <g:price>24.90 EUR</g:price>
      <g:sale_price>19.90 EUR</g:sale_price>
      <g:availability>in_stock</g:availability>
      <g:image_link>https://shop.example.com/img/123.jpg</g:image_link>
    </item>
  </channel>
</rss>
  • g:item_group_id es el id de producto para Spaidoo (una fila por producto); sin él, lo es g:id. Ese id de producto es el que se usa en todo lo demás: data-sp-id, catalog.changes, importación de wishlists.
  • Obligatorios: g:id, g:title, g:link (la URL canónica del producto), g:price en la moneda base de la tienda y g:availability (in_stock · out_of_stock · preorder · backorder).
  • Los precios en otras monedas van en spaidoo:price currency="USD" (namespace https://spaidoo.com/ns/feed/1).
El feed: se registra una vez y se lee más o menos una vez al día1. Servidor de la tienda → API de Spaidoo: PUT /catalog/feeds una URL de feed por idioma 2. Sync de Spaidoo → Servidor de la tienda: GET <url del feed> una vez al día, más o menos 3. Servidor de la tienda → Sync de Spaidoo: 202 + Retry-After todavía se genera 4. Sync de Spaidoo: Vuelve tras el Retry-After; conserva el catálogo 5. Sync de Spaidoo → Servidor de la tienda: GET <url del feed> 6. Servidor de la tienda → Sync de Spaidoo: 200 RSS / Atom, un ítem por varianteServidor de la tiendaAPI de SpaidooSync de SpaidooPUT /catalog/feedsuna URL de feed por idioma1GET <url del feed>una vez al día, más o menos2202 + Retry-Aftertodavía se genera34Vuelve tras elRetry-After; conservael catálogoGET <url del feed>5200 RSS / Atom,un ítem por variante6
Mientras se genera un feed grande, un 202 con Retry-After le dice a Spaidoo que vuelva más tarde en lugar de leer un catálogo vacío.

Un feed grande tarda en generarse. Mientras se genera, responde 202 (o 503/429) con Retry-After: Spaidoo vuelve entonces y no lo toma como un catálogo vacío. Cualquier otro error conserva el catálogo anterior.

HTTP
HTTP/1.1 202 Accepted
Retry-After: 120

POST /catalog/feeds/read pide una lectura ya (un botón en tu panel, por ejemplo). Si se vuelve a pedir en menos de 3 minutos, responde 429 con Retry-After.

Cambios de catálogo: catalog.changes

Cuando cambia un precio o el stock en la tienda, díselo a Spaidoo en el momento: los avisos de bajada de precio salen en minutos en lugar de en la siguiente lectura diaria, que se queda como conciliación (§4.6).

Cambios de catálogo: se anotan durante la petición y se envían al final1. Back-office de la tienda → Servidor de la tienda: El comerciante guarda precios o stock 2. Servidor de la tienda: Anota los ids de producto, responde al comerciante 3. Servidor de la tienda → API de Spaidoo: al final de la petición POST /catalog/changes 4. API de Spaidoo → Servidor de la tienda: 202 { accepted, unknown } 5. API de Spaidoo: Ids desconocidos: programa una lecturaBack-office de la tiendaServidor de la tiendaAPI de SpaidooEl comerciante guardaprecios o stock12Anota los ids de producto,responde al comercianteal final de la peticiónPOST /catalog/changes3202 { accepted, unknown }45Ids desconocidos:programa una lectura
El comerciante nunca espera a Spaidoo. La lectura diaria del feed se queda como conciliación.
JSON
{
  "changes": [
    {
      "type": "product.updated",
      "id": "123",
      "at": 1759219200,
      "price": { "amount": "24.90", "currency": "EUR" },
      "salePrice": { "amount": "19.90", "currency": "EUR" },
      "availability": "in_stock"
    },
    { "type": "product.deleted", "id": "456", "at": 1759219230 }
  ]
}
  • product.updated lleva solo price, salePrice (null = sin oferta), prices en otras monedas, availability y las variants que han cambiado, por sku. Todos los campos son opcionales; uno presente sustituye el valor guardado.
  • product.deleted: el producto ya no se vende (borrado o desactivado).
  • at es cuándo ocurrió el cambio. Spaidoo ignora un cambio más antiguo que el que ya aplicó, así que los reintentos y la entrega desordenada son seguros.
  • Hasta 100 cambios por petición y 60 peticiones por minuto. Agrupa las ráfagas: una edición masiva de 2 000 productos son 20 peticiones, no 2 000.
  • Los productos nuevos, y los cambios de título, enlace, imágenes o categorías, llegan con la siguiente lectura del feed.

Anota los ids de producto mientras corre la petición del comerciante y envíalos al final, cuando la respuesta ya ha salido, así el comerciante nunca espera a Spaidoo:

JavaScript
// While the merchant's request runs: only note which products changed.
const pending = new Map(); // product id → unix time of the change

onProductSaved((product) => pending.set(String(product.id), Math.floor(Date.now() / 1000)));

// Once the response has gone out: up to 100 changes per call.
onRequestEnd(async () => {
  if (!store.get("capabilities")["catalog.changes"]) return;
  const changes = [...pending].map(([id, at]) => changeOf(id, at)); // product.updated or product.deleted
  for (let i = 0; i < changes.length; i += 100) {
    await spaidoo("POST", "/catalog/changes", { changes: changes.slice(i, i + 100) });
  }
});

Spaidoo responde 202 { accepted, unknown }: unknown lista los ids que todavía no tiene, y programa una lectura del feed. Si falla, reintenta con espera creciente durante 1 hora como máximo y luego descártalo: la lectura diaria del feed lo corrige todo.

Cómo sabes que funciona

  • GET /status lista tus feeds en store.feeds y las últimas lecturas, con sus resultados, en store.feedHistory.
  • La comprobación de conformidad lee tus feeds y sus ítems.
  • POST /catalog/changes responde 202 con unknown vacío para productos que Spaidoo conoce. Es una llamada a Spaidoo: la comprobación la lista con cómo comprobarla a mano (§8).

Paso 6 de 14

Identidad del cliente

Un cliente con sesión iniciada en la tienda conserva sus productos guardados en todos sus dispositivos, sin cuenta de Spaidoo.

Mientras la tienda tiene un conector con identity, manda la sesión de la tienda: Spaidoo nunca le pide al cliente que inicie sesión en la tienda en su nombre (§5).

Identidad: la tienda dice quién navega, firmado con el identity secret1. Navegador del cliente → Servidor de la tienda: GET <urls.identity>?anon=<uuid> mismo origen, cookies de la tienda 2. Servidor de la tienda → Navegador del cliente: 200 { assertion } con sesión 200 { anonymous: true } nadie 3. Navegador del cliente → API de Spaidoo: El widget entrega la aserción a Spaidoo 4. API de Spaidoo: Comprueba la firma, exp y jti 5. Navegador del cliente: Nadie con sesión, y el cliente quiere conservar la lista 6. Navegador del cliente → Servidor de la tienda: GET <urls.login> {back} = la página actual 7. Servidor de la tienda → Navegador del cliente: Tras iniciar sesión: vuelve a esa páginaNavegador del clienteServidor de la tiendaAPI de SpaidooGET <urls.identity>?anon=<uuid>mismo origen, cookies de la tienda1200 { assertion } con sesión200 { anonymous: true } nadie2El widget entrega laaserción a Spaidoo34Comprueba la firma,exp y jti5Nadie con sesión, yel cliente quiereconservar la listaGET <urls.login>{back} = la página actual6Tras iniciar sesión:vuelve a esa página7
La ruta de identidad se llama desde la tienda con sus propias cookies. Cuando no hay nadie con sesión y el cliente quiere conservar su lista, el widget lo manda al inicio de sesión de la tienda.

La ruta de identidad

El widget llama a GET <urls.identity>?anon=<uuid> desde la tienda: mismo origen, con las cookies de la tienda. Responde 200 { "assertion": "…" } cuando hay un cliente con sesión iniciada, 200 { "anonymous": true } cuando no hay nadie (los invitados cuentan como nadie), y 410 cuando el conector está desconectado (§5.1).

Envía Cache-Control: no-store, private y Vary: Cookie. La ruta no debe guardarla nunca una caché de página ni un CDN.

La aserción

Un payload JSON y su HMAC-SHA256 con el identity secret (como texto UTF-8), los dos en base64url sin relleno, unidos por un punto (§5.2):

JavaScript
import { createHmac, randomBytes } from "node:crypto";

const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
const b64url = (text) => Buffer.from(text).toString("base64url"); // no padding

function assertion(secret, shopId, customerId, anon) {
  const iat = Math.floor(Date.now() / 1000);
  const payload = b64url(JSON.stringify({
    v: 1,
    shopId,
    customerId: String(customerId),
    email: "", // always empty: Spaidoo asks the customers route when it needs one
    anonId: UUID.test(anon ?? "") ? anon : null,
    iat,
    exp: iat + 60,
    jti: randomBytes(16).toString("hex"),
  }));
  const signature = createHmac("sha256", secret).update(payload).digest("base64url");
  return `${payload}.${signature}`;
}

// GET <urls.identity>?anon=<uuid> — same origin, with the shop's cookies.
app.get("/spaidoo/identity", (req, res) => {
  res.set({ "Cache-Control": "no-store, private", Vary: "Cookie" });
  if (!store.get("connected")) return res.sendStatus(410);
  const customer = signedInCustomer(req); // a guest counts as nobody
  if (!customer) return res.json({ anonymous: true });
  res.json({ assertion: assertion(store.get("identitySecret"), store.get("shopId"), customer.id, req.query.anon) });
});
  • exp - iat es 60 s como máximo; Spaidoo tolera 30 s de desfase de reloj. jti es de un solo uso.
  • anonId repite ?anon= cuando es un UUID; si no, null.
  • email es siempre "": Spaidoo no guarda los emails de los clientes de la tienda (paso 7).

La pista de sesión (opcional, recomendada)

Para que el widget note un inicio o un cierre de sesión sin preguntar en cada página, imprime SpaidooConfig.shopSession (paso 8): "" 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 (§5.3).

JavaScript
const shopSession = customer
  ? createHmac("sha256", secret).update("session:" + customer.id).digest("hex").slice(0, 16)
  : "";

La URL de inicio de sesión

Declara urls.login con la marca literal {back}. Cuando un cliente sin sesión quiere conservar su lista, el widget lo manda allí con {back} sustituido por la página donde estaba, codificada como URL. Después del inicio de sesión, la tienda tiene que redirigir de vuelta a ella, solo en el mismo dominio (§5.4).

Cómo sabes que funciona

  • Haz curl a la ruta de identidad sin cookies: {"anonymous": true} y las dos cabeceras de caché.
  • Con la cabecera Cookie de un cliente de prueba con sesión iniciada: una aserción cuyo payload (decodifica en base64url la parte anterior al punto) lleva tu shopId, el customerId y "email": "".
  • La comprobación de conformidad prueba la ruta y sus aserciones cuando le das esa cabecera Cookie.

Paso 7 de 14

La ruta customers

Spaidoo puede pedirle a la tienda el email y el consentimiento de marketing de clientes identificados, y nadie más puede.

Spaidoo no guarda los emails de los clientes de la tienda. Cuando el comerciante los necesita (una exportación, la audiencia de una campaña, una sincronización con su herramienta de email), Spaidoo pregunta a tu urls.customers, usa la respuesta en ese momento y no la guarda (§6.2).

La ruta customers: Spaidoo pregunta, firmado, cuando el comerciante necesita emails1. API de Spaidoo: El comerciante necesita emails: exportación, audiencia, sync 2. API de Spaidoo → Servidor de la tienda: POST <urls.customers> X-Spaidoo-Timestamp · Nonce · Signature { customerIds: [...] } 3. Servidor de la tienda: Timestamp, firma (cuerpo en bruto), nonce 4. Servidor de la tienda → API de Spaidoo: 200 { customers: [...] } en menos de 5 s 5. API de Spaidoo: Los usa en el momento, no los guardaAPI de SpaidooServidor de la tienda1El comerciante necesita emails:exportación, audiencia, syncPOST <urls.customers>X-Spaidoo-Timestamp · Nonce · Signature{ customerIds: [...] }23Timestamp, firma(cuerpo en bruto), nonce200 { customers: [...] }en menos de 5 s45Los usa en el momento,no los guarda
Spaidoo usa la respuesta en ese momento y no guarda los emails.

Verifica cada llamada

Cada llamada de Spaidoo a una URL del conector (salvo las públicas verify y feed) lleva X-Spaidoo-Timestamp, X-Spaidoo-Nonce y X-Spaidoo-Signature: el HMAC-SHA256 en base64url de timestamp + "." + nonce + "." + rawBody con el identity secret (§6.1).

Verificar una llamada firmada de SpaidooLlega una llamada firmada. ¿Timestamp a menos de 300 s de nuestro reloj?. ¿Firma del cuerpo en bruto igual, en tiempo constante?. ¿Nonce no visto en los últimos 600 s?. Responde { customers }. 401. sí. no. sí. no. sí. noLlega unallamada firmada¿Timestamp a menosde 300 s denuestro reloj?¿Firma del cuerpoen bruto igual, entiempo constante?¿Nonce no vistoen los últimos600 s?Responde{ customers }401sínosínosíno
Cualquier comprobación que falla responde 401 antes siquiera de leer el cuerpo como JSON.
JavaScript
import { createHmac, timingSafeEqual } from "node:crypto";

// The RAW body: the signature covers the bytes Spaidoo sent, not re-serialised JSON.
app.post("/spaidoo/customers", express.raw({ type: "*/*" }), async (req, res) => {
  const secret = store.get("identitySecret");
  if (!store.get("connected") || !secret) return res.sendStatus(410);

  const timestamp = req.get("X-Spaidoo-Timestamp") ?? "";
  const nonce = req.get("X-Spaidoo-Nonce") ?? "";
  const signature = Buffer.from(req.get("X-Spaidoo-Signature") ?? "");

  // 1. A timestamp more than 300 s away from our clock.
  const now = Math.floor(Date.now() / 1000);
  if (!/^\d+$/.test(timestamp) || Math.abs(now - Number(timestamp)) > 300) return res.sendStatus(401);

  // 2. The signature, compared in constant time.
  const expected = Buffer.from(
    createHmac("sha256", secret).update(`${timestamp}.${nonce}.`).update(req.body).digest("base64url"),
  );
  if (signature.length !== expected.length || !timingSafeEqual(signature, expected)) return res.sendStatus(401);

  // 3. A nonce seen in the last 600 s is a replay.
  if (!(await nonces.addIfNew(nonce, 600))) return res.sendStatus(401);

  const { customerIds } = JSON.parse(req.body.toString("utf8"));
  const customers = await findAccounts(customerIds); // no guests, no deleted ones
  res.json({
    customers: customers.map((c) => ({
      customerId: String(c.id),
      email: c.email,
      marketingConsent: c.newsletter ?? null, // null: the platform does not know
    })),
  });
});
  • Firma sobre el cuerpo en bruto, tal como llega: parsear y volver a serializar el JSON cambia los bytes.
  • Compara las firmas en tiempo constante.
  • Recuerda los nonces 600 s y rechaza uno repetido, para que una petición capturada no se pueda reenviar.

La respuesta

JSON
{ "customers": [ { "customerId": "123", "email": "ana@example.com", "marketingConsent": true } ] }
  • Hasta 500 ids por llamada. Omite los clientes que ya no existen, los invitados y los borrados.
  • marketingConsent: true el cliente aceptó los emails de marketing de la tienda, false no los aceptó, null la plataforma no lo sabe.
  • Responde en menos de 5 s; 410 si el conector está desconectado.
  • Opcional, y mejor: marketingState (subscribed · not_subscribed · unsubscribed · pending) y marketingUpdatedAt, el estado exacto; marketingConsent se mantiene, true solo si subscribed (§6.2).

Consentimiento de marketing: marketingConsent

Cuando un cliente con sesión iniciada en la tienda dice que sí, en el widget, a los emails de la tienda, Spaidoo llama a tu urls.marketingConsent, firmado como la ruta customers: activa su consentimiento de email marketing en la plataforma y responde el estado. Spaidoo solo concede el consentimiento, nunca da de baja a nadie. Es una URL de servidor, como urls.customers, y la capacidad necesita identity (§6.4).

JavaScript
// Signed exactly as the customers route: the same three checks come first.
app.post("/spaidoo/marketing-consent", express.raw({ type: "*/*" }), async (req, res) => {
  if (!store.get("connected")) return res.sendStatus(410);
  if (!(await verifySignature(req))) return res.sendStatus(401); // timestamp, raw-body signature, nonce

  const { customerId, textVersion, consentedAt } = JSON.parse(req.body.toString("utf8"));
  const customer = await findAccount(customerId);
  if (!customer) return res.sendStatus(404);

  // Grant only, single opt-in. Already subscribed: nothing changes, same answer.
  const state = await subscribeToEmails(customer, { textVersion, consentedAt }); // the platform's own consent
  res.json({ customerId: String(customer.id), marketingState: state === "pending" ? "pending" : "subscribed" });
});
  • El cuerpo es { customerId, textVersion, consentedAt }: la prueba de qué texto aceptó el cliente, y cuándo.
  • Opt-in simple; con doble opt-in la plataforma puede dejarlo pendiente: responde "pending". Si ya estaba suscrito: la misma respuesta.
  • Errores: 404 cliente desconocido, 410 desconectado, 503 la plataforma ha fallado.

Cómo sabes que funciona

  • Un POST sin firmar a la ruta responde 401.
  • Con un id de cliente de la tienda de prueba, la comprobación de conformidad prueba el nonce, la firma, el cuerpo en bruto, la antigüedad del timestamp y los límites.
  • Con marketingConsent, un sí en el widget de un cliente de prueba con sesión iniciada lo suscribe en la plataforma. La comprobación de conformidad prueba la ruta sin conceder nada (un cliente desconocido responde 404, las comprobaciones de firma 401); la concesión en sí, pruébala a mano (§8).

Paso 8 de 14

La tienda

Imprimir el widget en las páginas de la tienda, nunca en el carrito ni en el checkout, y servir el service worker de push.

La tienda: lo que imprime y sirve al navegador del cliente1. Navegador del cliente → Servidor de la tienda: GET una página de producto 2. Servidor de la tienda: ¿Carrito o checkout? Ahí no se imprime nada 3. Servidor de la tienda → Navegador del cliente: HTML con SpaidooConfig, el loader, anclajes 4. Navegador del cliente → Widget de Spaidoo: carga el widget scriptUrl 5. Navegador del cliente: Dibuja los iconos de guardar en los anclajes 6. Navegador del cliente → Servidor de la tienda: GET <urls.pushWorker> registra el worker de push 7. Servidor de la tienda → Navegador del cliente: Service-Worker-Allowed: <pushScope>Navegador del clienteServidor de la tiendaWidget de SpaidooGET una página de producto12¿Carrito o checkout?Ahí no se imprime nadaHTML con SpaidooConfig,el loader, anclajes3carga el widgetscriptUrl45Dibuja los iconos deguardar en los anclajesGET <urls.pushWorker>registra el worker de push6Service-Worker-Allowed:<pushScope>7
El carrito, el checkout y las páginas de pago no reciben nada de Spaidoo; excludePaths es la red de seguridad.

En todas las páginas salvo las excluidas, imprime la configuración y el loader. scriptUrl viene de GET /status y puede cambiar: usa siempre el último (§4.3, §7).

HTML
<script data-spaidoo-config='{"currency":"EUR","shopSession":"","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>
  • currency: el código ISO de la moneda en la que navega el visitante; el widget muestra los precios en ella (de spaidoo:price).
  • shopSession: la pista de sesión del paso 6.
  • preview: true solo para el personal de la tienda mientras el widget está en modo preview.
  • push: { swUrl, swScope } cuando se declara push.
  • priceFormat (opcional): { currency, sample }, el formato de la propia plataforma de 1234567.89 en esa moneda, para que el widget escriba los precios como la tienda. themeId (opcional): el diseño actual de la tienda, para que el widget vuelva a leer el aspecto de las tarjetas cuando cambie.
  • Una caché de página completa tiene que guardar una copia por moneda, como ya hace con los precios.

No imprimas nunca el script en el carrito, el checkout ni las páginas de pago. El widget no se carga nunca ahí, así que tampoco aparece ningún botón, icono de guardar ni carrusel. Inclúyelas también en storefront.excludePaths en el handshake: es la red de seguridad si se escapa alguna página.

Botones de guardar (opcional)

Donde el tema deba mostrar el icono de guardar de Spaidoo, imprime un ancla vacía con el id de producto del feed: el widget dibuja el icono y gestiona el clic y el estado. Dale estilo con las propiedades CSS --sp-save-* y declara storefront.saveAnchors. Cualquier elemento con data-spaidoo-library abre la lista del cliente.

HTML
<span data-spaidoo-save
      data-sp-context="product"
      data-sp-id="123"
      data-sp-url="https://shop.example.com/p/123"
      data-sp-name="Blue shirt"
      data-sp-image="https://shop.example.com/img/123.jpg"></span>

data-sp-context es "product" en la página de producto y "list" en las fichas de producto; data-sp-name y data-sp-image son opcionales.

Sitios para carruseles (opcional)

Donde el tema tenga sitio para los carruseles inteligentes de Spaidoo (paso 12), imprime un sitio vacío y con nombre: el widget monta ahí los carruseles cuyo location.anchor es ese nombre, y lo marca con data-spaidoo-filled o data-spaidoo-empty. Los nombres convencionales son home, product y collection; nunca en el carrito ni en el checkout (§7).

HTML
<!-- At the end of the product page: the carousels whose location.anchor is "product" -->
<div data-spaidoo-carousel="product" style="--spaidoo-carousel-reserve: 380px"></div>

Un script propio en la tienda puede seguir al widget: SpaidooConfig.saveAnchors y SpaidooConfig.icon, los eventos spaidoo:anchor-ready, spaidoo:panel-open y spaidoo:panel-close, y spaidoo:show-section para abrir la lista del cliente (§7.2).

El service worker de push: push

El web push se registra en el propio dominio de la tienda, así que el conector sirve el service worker de Spaidoo en urls.pushWorker (§7.1):

HTTP
GET /spaidoo/push-sw.js

HTTP/1.1 200 OK
Content-Type: application/javascript
Service-Worker-Allowed: /spaidoo-push/
Cache-Control: no-cache

<the reference worker, copied verbatim from https://cdn.spaidoo.com/connector/v1/push-sw.js>
  • El cuerpo es el worker de referencia publicado en https://cdn.spaidoo.com/connector/v1/push-sw.js: cópialo tal cual; no lo cargues con importScripts desde otro origen.
  • Recibe mensajes solo de datos { title, body, link, seen, icon, image, badge, shopId }; él mismo avisa a seen cuando muestra uno.
  • Service-Worker-Allowed solo hace falta cuando pushScope está fuera del directorio del propio worker. Un worker servido dentro de su alcance (detrás del proxy de apps de una plataforma, por ejemplo: /apps/spaidoo/push-sw.js con pushScope /apps/spaidoo/) va sin ella.

Cómo sabes que funciona

  • El código fuente de una página de producto muestra data-spaidoo-config y el loader; el del carrito y el checkout, ninguno de los dos.
  • curl -I <urls.pushWorker> muestra las cabeceras.
  • Con una página de producto y la URL del carrito o del checkout, la comprobación de conformidad prueba el loader, SpaidooConfig, los anclajes de guardado, que no se imprime nada en el checkout, y el service worker de push.

Paso 9 de 14

Verificación de dominio, borrado e importación de wishlists

Tres capacidades cortas: demostrar el dominio, trasladar los borrados, traer las wishlists antiguas.

Verificación de dominio: domainVerification

La tienda demuestra que es dueña de su dominio sin cambios de DNS. Pide un código a Spaidoo, sírvelo en urls.verify como text/plain sin nada más en el cuerpo, y pide a Spaidoo que lo compruebe (§4.9).

Verificación de dominio: Spaidoo lee el código en la tienda1. Servidor de la tienda → API de Spaidoo: POST /domain-verification 2. API de Spaidoo → Servidor de la tienda: { verificationCode, domain } 3. Servidor de la tienda: Guarda el código y sírvelo en urls.verify como text/plain 4. Servidor de la tienda → API de Spaidoo: POST /domain-verification/check 5. API de Spaidoo → Servidor de la tienda: GET <urls.verify> 6. Servidor de la tienda → API de Spaidoo: spaidoo-verify-… 7. API de Spaidoo → Servidor de la tienda: { verified: true }Servidor de la tiendaAPI de SpaidooPOST /domain-verification1{ verificationCode, domain }23Guarda el código ysírvelo en urls.verifycomo text/plainPOST /domain-verification/check4GET <urls.verify>5spaidoo-verify-…6{ verified: true }7
La ruta de verificación responde el código como texto plano y nada más; Spaidoo no sigue redirecciones.
HTTP
POST /connector/v1/domain-verification
→ { "verified": false, "verificationCode": "spaidoo-verify-…", "domain": "shop.example.com" }

GET https://shop.example.com/spaidoo/verify
→ 200, Content-Type: text/plain
spaidoo-verify-…

POST /connector/v1/domain-verification/check
→ { "verified": true }
  • urls.verify tiene que estar en el dominio que se demuestra (o en su www.) y no puede contener el código. Spaidoo no sigue redirecciones.
  • Para un dominio que ya está en el directorio de Spaidoo, la prueba va antes que la key (paso 3): la ruta tiene que responder mientras se empareja la tienda (§3.3).
  • Sin la capacidad, el comerciante puede subir igualmente el código como https://<domain>/spaidoo-verify.txt.

Borrado de clientes: customerErase

Cuando la tienda borra un cliente (o recibe una solicitud de supresión RGPD), llama a POST /customers/erase. Spaidoo borra la lista del cliente anclada a esta tienda y desvincula de ella cualquier cuenta de Spaidoo. Los invitados no hace falta enviarlos (§4.7).

HTTP
POST /connector/v1/customers/erase
{ "customerId": "123" }
→ 204

Importación de wishlists: wishlistImport

POST /wishlists/import trae las listas de una extensión de wishlist anterior: hasta 50 clientes por llamada, 100 listas por cliente y 1 000 productos por lista, con los ids de producto del feed. Importar la misma lista dos veces no la duplica. Necesita identity (§4.8).

JSON
{
  "customers": [
    { "customerId": "123", "lists": [
      { "id": "1", "name": "My wishlist", "isDefault": true, "products": ["123", "789"] }
    ] }
  ]
}

Cuando las listas llegan en un fichero exportado de otra app de wishlist, envía sus filas: POST /wishlists/import/rows con tus propios ids de cliente (§4.8.1), o POST /wishlists/import/file con los clientes tal como vienen, por email o por id, y Spaidoo le pregunta a tu tienda quiénes son con customerLookup y customers (§4.8.2). Las dos aceptan primero un dryRun, para la vista previa. Sin la capacidad, una llamada responde 409 CONNECTOR_CAPABILITY_MISSING, con la capability que necesita.

Cómo sabes que funciona

  • POST /domain-verification/check responde { "verified": true }, y la comprobación de conformidad prueba la ruta de verificación.
  • POST /customers/erase responde 204. El borrado y la importación son llamadas a Spaidoo: la comprobación las lista con cómo comprobarlas a mano (§8).

Paso 10 de 14

Apps alojadas: alta, cobro y borrado

Un conector alojado en tus servidores da de alta las tiendas él mismo, deja que la plataforma cobre el plan y borra lo que trajo cuando la plataforma lo pide.

Este paso es para las apps fixed (§3.1), alojadas por ti o por la plataforma. Tienen un client secret (scs_…), que se muestra una sola vez al crear la app en Mis conectores y se rota allí: guárdalo en tu servidor, como la API key.

Da de alta la tienda desde tu servidor

Cuando el admin de la plataforma no debe mandar al comerciante a iniciar sesión en otro sitio, tu servidor da de alta la tienda con los datos que la plataforma ya garantiza, y consigue la key en dos llamadas, sin popup (§3.4):

HTTP
POST /connector/v1/pairing/provision
{ "client_id": "sc_my_platform_app", "client_secret": "scs_…", "domain": "shop.example.com",
  "name": "My shop", "email": "merchant@example.com",
  "verify": "https://shop.example.com/spaidoo/verify", "lang": "en" }
→ 201 { "provisionToken": "…", "state": "new", "verificationCode": null }

POST /connector/v1/pairing/provision/complete
{ "client_id": "sc_my_platform_app", "client_secret": "scs_…", "provision_token": "…" }
→ 200 { "apiKey": "…", "shopId": "7f3c…" }
  • state: new (una tienda nueva), claim (el dominio es de una tienda del directorio de Spaidoo: sirve verificationCode en verify, paso 9, antes de completar) o ready (una cuenta que tu app ya dio de alta vuelve tal como estaba).
  • lang hace que una tienda nueva hable el idioma del comerciante: el de sus propios textos y el de los emails que Spaidoo le envía.
  • 409 EMAIL_ALREADY_REGISTERED o 409 SHOP_HAS_OWNER: no se crea nada; manda al comerciante por el popup del paso 3 para que inicie sesión.
  • La cuenta no tiene contraseña: el comerciante entra en el admin de Spaidoo con POST /sso (§4.11) y acepta los términos de Spaidoo en tu panel (paso 11) antes de cambiar nada.

Borra lo que trajo una tienda desinstalada

Algunas plataformas piden a sus apps, un tiempo después de una desinstalación, que borren los datos de clientes de esa tienda. Para entonces puede que ya no tengas su key, así que POST /shop-redact se identifica con tu client secret. Solo para una tienda que conectó tu app y que está desinstalada (POST /uninstall, §4.4). Spaidoo borra el catálogo, las cifras y todos los clientes de la tienda, nunca las listas de una cuenta de Spaidoo, y una llamada repetida no borra nada más (§3.5).

HTTP
POST /connector/v1/shop-redact
{ "client_id": "sc_my_platform_app", "client_secret": "scs_…", "shopId": "7f3c…" }
→ 200 { "customersErased": 42, "contactsErased": 7, "pushDevicesErased": 12,
        "productsErased": 398, "productsKept": 14, "eventsErased": 9120 }

El plan cobrado por la plataforma: billing.platform

Si la plataforma cobra ella misma sus apps y prohíbe cobrar en otro sitio, pide a Spaidoo que active billingPlatform y tus adminDomains en la app. Después declara billing.platform con urls.billing, tu página de planes en el admin de la plataforma: la plataforma cobra el plan, tu conector lo comunica y Spaidoo manda al comerciante a urls.billing en lugar de ofrecer su propio pago (§4.12).

HTTP
PUT /connector/v1/billing
{ "plan": "growth", "interval": "monthly", "status": "active", "externalId": "sub_8f2a",
  "currentPeriodEnd": 1761955200, "cancelAtPeriodEnd": false, "pending": null,
  "price": { "amount": "29.00", "currency": "USD" }, "occurredAt": 1759363200 }
→ 200 { "provider": "platform", "plan": "growth", "status": "active", … }

The same, with an older occurredAt
→ 409 { "errorCode": "BILLING_STALE", "lastEventAt": 1759363200, … }
  • Traduce los planes de la plataforma a los de Spaidoo, starter · growth · pro, y envía el estado completo cada vez: la llamada es idempotente.
  • Comunícalo después de cada cambio de la suscripción, y como mínimo una vez por periodo (una conciliación diaria). Los informes pueden cruzarse: gana el occurredAt más reciente. Con 409 BILLING_STALE, vuelve a leer la plataforma y envía lo que diga ahora.
  • 409 BILLING_STRIPE_ACTIVE: la tienda todavía paga directamente a Spaidoo; no cambia nada hasta que el comerciante cancele ese plan en Spaidoo.
  • GET /billing dice lo que tiene Spaidoo, y GET /plans qué incluye cada plan (cuotas, avisos, herramientas, informes; precios solo mientras cobra Spaidoo): pinta tu pantalla de planes a partir de ellos, con tus propias etiquetas (§4.12.1).

Cómo sabes que funciona

  • POST /pairing/provision y después /pairing/provision/complete te dan una key, y POST /handshake con ella responde 200.
  • PUT /billing responde 200 y GET /billing muestra provider: "platform" con tu plan; un informe con un occurredAt más antiguo responde 409 BILLING_STALE.
  • Después de POST /uninstall, POST /shop-redact responde 200 con lo que ha borrado; antes, 409 SHOP_STILL_CONNECTED.

Paso 11 de 14

Tu panel: términos, widget y cifras

El comerciante lleva Spaidoo desde tu panel en el admin de la plataforma: acepta los términos, configura el widget y ve lo que le aporta.

Nada de esto necesita una capacidad: cualquier conector con panel puede ofrecerlo. Declara panel.widget con urls.panel cuando tu panel cubra la configuración del widget: el admin de Spaidoo oculta entonces las pantallas que la repetirían y enlaza a las tuyas. Como urls.billing, urls.panel vive en los adminDomains de tu app (§4.1).

O incrusta Spaidoo Panel en lugar de construir estas pantallas: las mismas pantallas que las apps propias de Spaidoo, en un iframe de tu página de admin, servidas y actualizadas por Spaidoo. Tu página responde a sus mensajes, reenvía sus peticiones a la API con la key a través de un intermediario en tu servidor que solo permite las rutas del panel, y ejecuta unas pocas acciones de plataforma (conectar, si el widget está en la tienda, sitios de carrusel, fuentes de importación) (§4.20).

Los términos de Spaidoo

Una tienda dada de alta desde tu servidor (paso 10) nunca ha pasado por el admin de Spaidoo. GET /status dice si ha aceptado los términos vigentes (store.termsAccepted), qué versión (store.termsVersion) y dónde leerlos (store.termsUrls). Muestra el texto y, cuando el comerciante acepte, dile a Spaidoo quién ha aceptado y cuándo (§4.13):

HTTP
GET /connector/v1/status
→ { "store": { "termsAccepted": false, "termsVersion": "2026-09-10",
               "termsUrls": { "es": "https://…/es/", "en": "https://…/en/" }, … }, … }

POST /connector/v1/terms/accept
{ "version": "2026-09-10", "acceptedBy": "staff-88120345", "at": 1759560000 }
→ 200 { "termsAccepted": true, "termsVersion": "2026-09-10", "acceptedAt": 1759560003 }
  • acceptedBy es el id del miembro del personal en la plataforma, nunca un email.
  • 409 TERMS_VERSION_OUTDATED con currentVersion: el comerciante vio un texto antiguo; enséñale el nuevo y vuelve a preguntar. Una versión nueva de los términos vuelve a poner termsAccepted a false.
  • Hasta entonces, los ajustes del widget, las importaciones y las escrituras de comunicación responden 409 TERMS_NOT_ACCEPTED. El catálogo, la identidad y el widget en la tienda siguen funcionando.

El widget desde tu panel

Lee los ajustes en store.pluginConfig de GET /status y cámbialos con las escrituras /widget/*: estado (off · preview · live), posición (una esquina, o por píxeles con custom), aspecto, botones de guardar, el selector propio de la lista, CSS propio, buscador y los textos del widget (§4.10). Conectar no es publicar: una tienda empieza en preview y pasa a live cuando su dominio está demostrado (paso 9).

HTTP
POST /connector/v1/widget/placement
{ "mobile": { "position": "custom", "offsets": { "bottom": 96, "right": 16 } } }
→ 200 { "success": true }

POST /connector/v1/widget/state
{ "mode": "live" }
→ 200 { "success": true, "mode": "live", "enabled": true }
  (403 SHOP_NOT_VERIFIED while the domain is not proven)

Para enseñar el widget mientras el comerciante lo configura, incrusta la vista previa de Spaidoo en un iframe y manéjala con postMessage (§4.10.2): espera a ready, envía render con los ajustes después de cada cambio, muestra el iframe con rendered y lleva al comerciante a un ajuste con focus. Nada de lo que hay dentro es real: no llama a Spaidoo.

JavaScript
const PREVIEW = "https://widget.spaidoo.com";
const frame = document.querySelector("#spaidoo-preview"); // <iframe sandbox="allow-scripts allow-same-origin" hidden>
frame.src = `${PREVIEW}/preview/v1/index.html?origin=${encodeURIComponent(location.origin)}`;

let rev = 0;
const render = (config) =>
  frame.contentWindow.postMessage({ ns: "spaidoo-preview", v: 1, type: "render", rev: ++rev, config }, PREVIEW);

window.addEventListener("message", (e) => {
  if (e.origin !== PREVIEW || e.source !== frame.contentWindow) return;
  const m = e.data;
  if (m?.ns !== "spaidoo-preview" || m.v !== 1) return;
  if (m.type === "ready") render(previewConfig()); // device, theme, accent, icon, productCircle, placement…
  if (m.type === "rendered" && m.rev === rev) frame.hidden = false;
  if (m.type === "focus") openSetting(m.target); // launcher · save · panel · header
});
// And render(previewConfig()) again after every change of the form.

Cifras, y lo demás en el admin de Spaidoo

GET /stats da las cifras de la pantalla de inicio por periodo (7d · 30d · 90d, o cualquier rango de días UTC con from y to), comparadas con el periodo anterior (§4.3.1); GET /analytics da el resto: oportunidades, el alcance de avisos y anuncios, los mejores clientes (§4.3.2). GET /search-analytics dice qué buscan los clientes en la tienda y en qué hacen clic (§4.3.3): el informe entero en Growth y Pro, una muestra en Starter. Cada producto llega con su ficha product (nombre, imagen, enlace), así que no hace falta buscarlo en tu plataforma. Para todo lo demás, abre el admin de Spaidoo con la sesión ya iniciada: POST /sso con una intención (reports, billing…), que se pide cuando el comerciante hace clic y se abre en una pestaña nueva (§4.11).

HTTP
GET /connector/v1/stats?period=30d
GET /connector/v1/stats?from=2026-09-01&to=2026-09-30
GET /connector/v1/analytics?period=90d

POST /connector/v1/sso
{ "intent": "reports" }
→ 200 { "url": "https://admin.spaidoo.com/…" }   single use, 5 minutes: ask on the click

Paso 12 de 14

Comunicación e integraciones

Desde tu panel, el comerciante habla con los clientes que guardaron sus productos y envía lo que pasa a sus propias herramientas.

Lo mismo que en el admin de Spaidoo, sin capacidad y con las mismas reglas de plan. Spaidoo decide qué incluye cada plan, y tu panel lo pinta a partir de las respuestas. Los textos se escriben por idioma (cualquiera de los 20 del §4.14), con el de la tienda obligatorio (primaryLanguage).

RutasQué hace el comerciante
/automations (§4.14)Avisos automáticos: bajada de precio, vuelta al stock, recordatorios… Spaidoo escribe cada uno en el idioma del cliente; la tienda añade un texto final. kinds dice qué necesita cada tipo.
/posts (§4.15)El tablón: anuncios con imagen, texto y botón, en el widget y en el portal de Spaidoo. POST /posts/image sube la imagen.
/notifications (§4.16)Un mensaje a un grupo de clientes, como push y en la bandeja de avisos del widget, enviado ya o programado.
/carousels (§4.17)Carruseles inteligentes de productos de la tienda en sus páginas, elegidos a mano o por Spaidoo. Imprime sitios con nombre para ellos en el tema (paso 8).
/integrations (§4.19)Las herramientas propias de la tienda (email marketing, analítica, un webhook) reciben todos los eventos que Spaidoo les envía.
GET /events (§4.18)Lo que ha ido a esas herramientas, a medida que pasa, con lo que ha hecho cada una.
  • Pinta a partir de las respuestas y no copies ninguna regla en tu conector: kinds (avisos), quota (anuncios, notificaciones) y providers (integraciones) dicen qué se puede hacer ahora.
  • GET /catalog/products busca los productos de la tienda en el catálogo de Spaidoo (por título, o por los ids que ya tienes) para los selectores de productos de avisos y carruseles, con sus nombres y fotos: sin preguntar a tu plataforma (§4.5.1).
  • Un error de plan (PUSH_REQUIRES_PLAN, POST_REQUIRES_PLAN, SLIDERS_REQUIRE_PRO, INTEGRATION_REQUIRES_PLAN…) no es una key muerta: ofrece los planes (paso 10, o POST /sso con billing). Solo un 401 desconecta (§2).
  • Crear y cambiar esperan a los términos (409 TERMS_NOT_ACCEPTED); leer y quitar, nunca.
  • GET /events usa fechas ISO 8601, no segundos Unix, y su productId es el de Spaidoo: tómalo tal como viene para filtrar por producto.

Conectar una herramienta

Una herramienta oauth2 responde { authorizeUrl }: ábrela en una ventana nueva, desde el clic del comerciante. El admin de Spaidoo avisa a tu página cuando ha terminado con postMessage; vuelve a leer también GET /integrations, porque algunas herramientas cortan el opener (§4.19).

JavaScript
// The merchant clicks «Connect» on a tool of GET /integrations.
async function connect(provider) {
  const popup = window.open("", "spaidoo-integration", "width=600,height=760"); // on the click
  const answer = await panelApi("POST", `/integrations/${provider}/connect`, {}); // your server, with the key
  if (!answer.authorizeUrl) return popup.close(), showConnected(answer); // secret · none: connected at once
  popup.location = answer.authorizeUrl;

  const finish = () => (clearInterval(poll), window.removeEventListener("message", onMessage), reloadTools());
  const onMessage = (e) => {
    if (e.origin !== "https://admin.spaidoo.com" || e.data?.type !== "spaidoo:integration-connected") return;
    finish(); // e.data.status: "ok" | "error", e.data.reason
  };
  window.addEventListener("message", onMessage);
  // Some tools cut window.opener: read the state again while the window is open.
  const poll = setInterval(async () => {
    const { providers } = await panelApi("GET", "/integrations");
    const status = providers.find((p) => p.id === provider)?.integration?.status;
    if (status === "connected" || popup.closed) finish();
  }, 2000);
}

Una herramienta secret (el webhook) se conecta en el acto, y su secreto de firma llega solo esa vez: enséñaselo al comerciante entonces. POST /integrations/:provider/test envía un evento de muestra, que aparece en GET /events en unos segundos.

Cómo sabes que funciona

  • GET /automations, /posts, /notifications, /carousels y /integrations responden 200 con lo que el admin de Spaidoo muestra para la misma tienda.
  • Un evento de prueba aparece en GET /events con test: true y sus deliveries.
  • La comprobación de conformidad no cubre estas rutas (§8).

Paso 13 de 14

Compruébalo

Pasar la comprobación de conformidad en línea hasta que no haya fallos en ninguna capacidad que declares.

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. Spaidoo ya tiene tu handshake y tu identity secret: solo pegas la API key de la tienda de prueba, nunca un secreto (§8).

El ciclo de la conformidadTienda de prueba emparejada con tu conector. Ejecuta la comprobación con su API key. Lee el informe correcta · fallo · aviso · omitida. Sin fallos: compatible con Spaidoo v1. Arregla lo que falla (cada línea enlaza la spec). ninguno. fallos. otra vezTienda de pruebaemparejada con tu conectorEjecuta la comprobacióncon su API keyLee el informecorrecta · fallo · aviso · omitidaSin fallos: compatiblecon Spaidoo v1Arregla lo que falla(cada línea enlaza la spec)ningunofallosotra vez
Ejecuta, lee, arregla y vuelve a ejecutar, hasta que ninguna capacidad que declaras tenga fallos.
  1. Abre la comprobación de conformidad y pega la API key de la tienda de prueba.
  2. Rellena los campos opcionales para probar más: la URL de una página de producto (loader, SpaidooConfig, anclajes de guardado), la URL del carrito o del checkout (ahí no se imprime nada), la cabecera Cookie de un cliente de prueba con sesión iniciada (identidad) y un id de cliente (ruta customers).
  3. Ejecútala: tarda un par de minutos.
  4. Lee el informe, arregla lo que falla y vuelve a ejecutarla. Hay diez ejecuciones por hora y tienda.
Captura de un informe de conformidad real de una tienda de prueba local: no conforme, con los totales de comprobaciones correctas, fallos, avisos y omitidas, y las primeras comprobaciones del grupo del handshake, cada una enlazada a su sección de la especificación.
El principio de un informe real de la comprobación de conformidad, ejecutada contra una tienda de prueba local. Cada línea enlaza su sección de la especificación.

Cómo leer el informe

MarcaQué significa
CorrectaLa comprobación ha pasado.
FalloEl conector no hace lo que pide la especificación. La línea enlaza su sección: arréglalo y vuelve a ejecutarla. Basta un fallo para no ser conforme.
AvisoNo es un fallo: la conformidad no depende de él, pero léelo.
OmitidaNo se ha comprobado en esta ejecución. Rellena los campos opcionales para que se compruebe todo lo que declaras.

Las llamadas que tu conector hace a Spaidoo (catalog.changes, customerErase, wishlistImport, billing.platform) y tu propio panel (panel.widget) no se pueden probar desde fuera: el informe las lista con cómo comprobarlas a mano. La ruta marketingConsent se prueba sin conceder nada; la concesión en sí se comprueba a mano.

Las rutas del panel sin capacidad (pasos 11 y 12) no forman parte de la comprobación: ofrece cualquiera de ellas, y el informe no dice nada de ellas.

La misma comprobación está abierta a tus propias herramientas: POST /connector/v1/conformance inicia una ejecución (202 { runId }) y GET /connector/v1/conformance/{runId} devuelve el informe, que se guarda una hora.

Cómo sabes que funciona

  • El informe dice Conforme con la Connector API v1.

Referencia

Especificación

Paso 14 de 14

¿Atascado?

Pregunta al asistente: responde a partir de la especificación.

Los partners de Spaidoo con acceso al área de desarrolladores pueden hablar con el asistente de la Connector API. Inicia sesión con tu cuenta de partner de Spaidoo: el acceso lo concede Spaidoo. Sus respuestas enlazan las secciones de la especificación, y tus conversaciones se guardan.

Captura del asistente de la Connector API: la lista de conversaciones a la izquierda y una conversación con un informe de conformidad adjunto y una respuesta que enlaza secciones de la especificación.
El asistente, con un informe de conformidad adjunto a la pregunta (conversación de ejemplo).

Desde un informe de la comprobación de conformidad, Pregunta al asistente por este informe abre una conversación nueva con el informe adjunto y una pregunta preparada: ¿por qué fallan estas comprobaciones y cómo lo arreglo?

¿Todavía sin acceso? Todo lo que sabe el asistente está en la especificación, que el recuadro Referencia de cada paso enlaza.

Cómo sabes que funciona

  • Las respuestas del asistente citan las secciones de la especificación como enlaces §x.y.

Referencia

Especificación