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).
| Capacidad | Qué le da a la tienda | ¿Hace falta? |
|---|---|---|
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. | Opcional |
identity | Un cliente con sesión iniciada conserva sus productos guardados en todos sus dispositivos, sin cuenta de Spaidoo. | Opcional |
customers | Spaidoo puede pedir el email y el consentimiento de marketing de un cliente identificado cuando el comerciante lo necesita. | Opcional, con identity |
customerLookup | La 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 |
marketingConsent | Un 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 |
customerErase | Borrar un cliente en la tienda borra sus datos en Spaidoo para esa tienda. | Opcional |
wishlistImport | Las listas de una extensión de wishlist anterior se traen a Spaidoo. | Opcional, con identity |
push | Las notificaciones web push se sirven desde el propio dominio de la tienda. | Opcional |
domainVerification | La tienda demuestra que es dueña de su dominio sin cambios de DNS. | Opcional |
storefront.saveAnchors | Tu tema imprime los botones de guardar; el widget los dibuja y gestiona el clic. | Opcional |
billing.platform | La plataforma cobra el plan de Spaidoo de la tienda y el conector lo comunica (§4.12). | Opcional, para apps que Spaidoo habilita |
panel.widget | Tu 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.feedes 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:
localhostno 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.
# Either one, pointing at the shop on your machine (port 8080 here)
ngrok http 8080
cloudflared tunnel --url http://localhost:8080Configura 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.
| Tipo | Cuándo | Vuelta |
|---|---|---|
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
platformde la app (my-platform) es texto libre, solo informativo.
Cómo sabes que funciona
- Mis conectores muestra tu app con su
client_id.
Referencia
Especificación
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).
- Tu servidor genera un
statealeatorio y uncode_verifier, guarda los dos (ligados a la sesión del comerciante) y calculacode_challenge = base64url(SHA-256(code_verifier)). - Tu página de admin abre un popup (
window.open, con el clic del comerciante) enhttps://admin.spaidoo.com/connectconclient_id,redirect_uri,state,code_challenge,code_challenge_method=S256, eldomainde la tienda y, si quieres,name,email,modeyverify(tuurls.verify, solo condomainVerification). - El comerciante se registra o inicia sesión en Spaidoo y acepta los términos.
- Spaidoo envía el popup a tu
redirect_uriconcodeystate(oerror=access_deniedsi el comerciante cancela). Comprueba elstate. - Tu servidor llama a
POST /pairing/tokenconclient_id,code,code_verifiery la mismaredirect_uri, en menos de 60 segundos, y recibe{ apiKey, shopId }. - Guarda la key y llama a
POST /handshake(siguiente paso). La página de vuelta avisa a tu admin conpostMessage(solo a tu propio origen y nunca con la key) y cierra el popup.
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 ahttps://api-plugin.spaidoo.com/connector/v1(§2, §2.1). - Solo un
401de Spaidoo significa que la key ya no es válida: muestra la tienda como desconectada. Un403es de esa llamada (un plan que la tienda no tiene, un dominio aún sin demostrar): suerrorCodedice por qué, y la tienda sigue conectada. Un5xxo 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 /statuscon ella responde200con elstorede 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).
Empieza por poco. Este cuerpo declara solo la capacidad obligatoria; activa las demás a medida que las construyas:
{
"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.domainsañade otros dominios en los que se sirve el escaparate (§4.1). logintiene 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, onullsi no guardas ninguno. Así un conector reinstalado consigue un secreto nuevo por su cuenta.testShop:truecuando la plataforma dice que es una tienda de desarrollo o de pruebas: queda fuera de las cifras de Spaidoo.platform.namees el nombre de tu plataforma tal como lo conocen los comerciantes, para los textos de Spaidoo.storeNamees 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:
{
"shopId": "7f3c…",
"contractVersion": 1,
"capabilities": { "catalog.feed": true },
"identitySecret": "b64url…"
}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,marketingConsentywishlistImportse rechazan sinidentity;billing.platformypanel.widgetse rechazan si Spaidoo no ha preparado tu app para ellas (paso 10). - Confirma cada secreto que recibas, después de guardarlo:
POST /identity-secret/ackcon su huella. Hasta entonces, Spaidoo lo sigue devolviendo en/handshakey/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 /handshakeresponde200con tus capacidades encapabilities.GET /statusmuestra tu declaración enconnectory deja de traeridentitySecretcuando 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).
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 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_ides el id de producto para Spaidoo (una fila por producto); sin él, lo esg: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:priceen la moneda base de la tienda yg:availability(in_stock·out_of_stock·preorder·backorder). - Los precios en otras monedas van en
spaidoo:price currency="USD"(namespacehttps://spaidoo.com/ns/feed/1).
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/1.1 202 Accepted
Retry-After: 120POST /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).
{
"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.updatedlleva soloprice,salePrice(null= sin oferta),pricesen otras monedas,availabilityy lasvariantsque han cambiado, porsku. Todos los campos son opcionales; uno presente sustituye el valor guardado.product.deleted: el producto ya no se vende (borrado o desactivado).ates 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:
// 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 /statuslista tus feeds enstore.feedsy las últimas lecturas, con sus resultados, enstore.feedHistory.- La comprobación de conformidad lee tus feeds y sus ítems.
POST /catalog/changesresponde202conunknownvacío para productos que Spaidoo conoce. Es una llamada a Spaidoo: la comprobación la lista con cómo comprobarla a mano (§8).
Referencia
Especificación
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).
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):
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 - iates 60 s como máximo; Spaidoo tolera 30 s de desfase de reloj.jties de un solo uso.anonIdrepite?anon=cuando es un UUID; si no,null.emailes 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).
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
curla la ruta de identidad sin cookies:{"anonymous": true}y las dos cabeceras de caché. - Con la cabecera
Cookiede un cliente de prueba con sesión iniciada: una aserción cuyo payload (decodifica en base64url la parte anterior al punto) lleva tushopId, elcustomerIdy"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).
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).
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
{ "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:trueel cliente aceptó los emails de marketing de la tienda,falseno los aceptó,nullla plataforma no lo sabe.- Responde en menos de 5 s;
410si el conector está desconectado. - Opcional, y mejor:
marketingState(subscribed·not_subscribed·unsubscribed·pending) ymarketingUpdatedAt, el estado exacto;marketingConsentse mantiene,truesolo sisubscribed(§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).
// 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:
404cliente desconocido,410desconectado,503la plataforma ha fallado.
Cómo sabes que funciona
- Un
POSTsin firmar a la ruta responde401. - 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 responde404, las comprobaciones de firma401); 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.
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).
<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 (despaidoo:price).shopSession: la pista de sesión del paso 6.preview:truesolo para el personal de la tienda mientras el widget está en modopreview.push:{ swUrl, swScope }cuando se declarapush.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.
<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).
<!-- 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):
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 conimportScriptsdesde otro origen. - Recibe mensajes solo de datos
{ title, body, link, seen, icon, image, badge, shopId }; él mismo avisa aseencuando muestra uno. Service-Worker-Allowedsolo hace falta cuandopushScopeestá 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.jsconpushScope/apps/spaidoo/) va sin ella.
Cómo sabes que funciona
- El código fuente de una página de producto muestra
data-spaidoo-configy 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).
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.verifytiene que estar en el dominio que se demuestra (o en suwww.) 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).
POST /connector/v1/customers/erase
{ "customerId": "123" }
→ 204Importació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).
{
"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/checkresponde{ "verified": true }, y la comprobación de conformidad prueba la ruta de verificación.POST /customers/eraseresponde204. El borrado y la importación son llamadas a Spaidoo: la comprobación las lista con cómo comprobarlas a mano (§8).
Referencia
Especificación
- §4.7 POST /customers/erase — borrar un cliente (customerErase)
- §4.8 POST /wishlists/import — wishlistImport
- §4.8.1 POST /wishlists/import/rows — wishlistImport, fila a fila
- §4.8.2 POST /wishlists/import/file — wishlistImport, desde un fichero que sube el comerciante
- §4.9 Verificación de dominio — domainVerification
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):
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: sirveverificationCodeenverify, paso 9, antes de completar) oready(una cuenta que tu app ya dio de alta vuelve tal como estaba).langhace 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_REGISTEREDo409 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).
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).
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
occurredAtmás reciente. Con409 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 /billingdice lo que tiene Spaidoo, yGET /plansqué 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/provisiony después/pairing/provision/completete dan una key, yPOST /handshakecon ella responde200.PUT /billingresponde200yGET /billingmuestraprovider: "platform"con tu plan; un informe con unoccurredAtmás antiguo responde409 BILLING_STALE.- Después de
POST /uninstall,POST /shop-redactresponde200con lo que ha borrado; antes,409 SHOP_STILL_CONNECTED.
Referencia
Especificación
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):
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 }acceptedByes el id del miembro del personal en la plataforma, nunca un email.409 TERMS_VERSION_OUTDATEDconcurrentVersion: el comerciante vio un texto antiguo; enséñale el nuevo y vuelve a preguntar. Una versión nueva de los términos vuelve a ponertermsAcceptedafalse.- 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).
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.
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).
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 clickCómo sabes que funciona
- Aceptar los términos pone
store.termsAcceptedatrue, y las escrituras del widget dejan de responder409 TERMS_NOT_ACCEPTED. - Un cambio hecho desde tu panel se ve en
GET /statusy en la siguiente página de la tienda. - La vista previa responde
readyy, después de cadarender,renderedcon el mismorev.
Referencia
Especificación
- §4.13 POST /terms/accept — aceptar las condiciones de Spaidoo desde el conector
- §4.10 Ajustes del widget desde el panel del conector (opcional)
- §4.10.2 La vista previa del widget (opcional)
- §4.3 GET /status — latido y estado
- §4.3.1 GET /stats — las cifras del panel por periodo
- §4.3.2 GET /analytics — la página de analítica
- §4.3.3 GET /search-analytics — qué buscan los clientes de la tienda
- §4.11 POST /sso — abrir el admin de Spaidoo con la sesión ya iniciada
- §4.20 Spaidoo Panel para conectores (opcional)
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).
| Rutas | Qué 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) yproviders(integraciones) dicen qué se puede hacer ahora. GET /catalog/productsbusca 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, oPOST /ssoconbilling). Solo un401desconecta (§2). - Crear y cambiar esperan a los términos (
409 TERMS_NOT_ACCEPTED); leer y quitar, nunca. GET /eventsusa fechas ISO 8601, no segundos Unix, y suproductIdes 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).
// 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,/carouselsy/integrationsresponden200con lo que el admin de Spaidoo muestra para la misma tienda.- Un evento de prueba aparece en
GET /eventscontest: truey susdeliveries. - La comprobación de conformidad no cubre estas rutas (§8).
Referencia
Especificación
- §4.14 Avisos automáticos — /automations
- §4.15 Tablón de anuncios — /posts
- §4.16 Notificaciones — /notifications
- §4.17 Carruseles inteligentes — /carousels
- §4.18 Eventos de integraciones — GET /events
- §4.19 Las herramientas de la tienda — /integrations
- §4.5.1 GET /catalog/products — los productos de la tienda, tal como los tiene Spaidoo
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).
- Abre la comprobación de conformidad y pega la API key de la tienda de prueba.
- 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 cabeceraCookiede un cliente de prueba con sesión iniciada (identidad) y un id de cliente (ruta customers). - Ejecútala: tarda un par de minutos.
- Lee el informe, arregla lo que falla y vuelve a ejecutarla. Hay diez ejecuciones por hora y tienda.

Cómo leer el informe
| Marca | Qué significa |
|---|---|
| Correcta | La comprobación ha pasado. |
| Fallo | El 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. |
| Aviso | No es un fallo: la conformidad no depende de él, pero léelo. |
| Omitida | No 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.
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.

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.