Conectar Sitio web

Antes de empezar

• Una tienda web propia que pueda llamar una API REST desde su servidor (nunca desde el navegador).
• Que cada producto de tu tienda tenga el mismo SKU que en Canalpulse.
• La API de tienda habilitada en tu cuenta: escríbenos y la activamos.

Paso a paso

1. 1

   En Canalpulse ve a Configuración → Llaves de API → Nueva llave, con el permiso «Tienda web» y en «Vence» elige «1 año» o «No vence» (si la llave vence, tu tienda deja de vender). Copia la llave (qsk_…): se muestra una sola vez.

2. 2

   Conecta tu tienda: lee catálogo y existencias de la API, aparta las unidades al cerrar el carrito y confirma o libera el apartado según el pago (abajo, la receta para Medusa y para cualquier otra plataforma).

3. 3

   Con tu tienda ya lista para recibirlos, ve a Configuración → Webhook de inventario, pega la URL donde tu tienda recibe los avisos de stock y haz clic en «Activar». Copia el secreto (whsec_…) a tu tienda y luego «Probar».

4. 4

   Cada venta confirmada aparece en Ventas como canal «Sitio web», descuenta el stock y actualiza tus marketplaces al momento.

Qué vas a ingresar en Canalpulse

URL del webhook de inventario

Dirección https pública de tu tienda que recibe los avisos de «cambió el stock de estos SKU». Opcional, pero sin ella tu tienda sólo se entera al volver a consultar.

Medusa

Si tu tienda corre en Medusa v2 (2.19 o superior), usa nuestro plugin: aparta al cerrar el carrito, registra la venta al crearse el pedido (también los draft orders) y mantiene el stock de Medusa al día. No cambias tu checkout ni tu storefront.

1. 1

   Instala el paquete @canalpulse/medusa que te enviamos al activar tu cuenta; revisa su huella SHA-256.

2. 2

   Agrégalo a medusa-config.ts con tu llave.

3. 3

   Corre la migración y reinicia Medusa: crea una tabla para saber qué apartado respalda cada carrito.

4. 4

   En el Webhook de inventario la URL es https://<tu-backend-medusa>/hooks/canalpulse. Pon el secreto en CANALPULSE_WEBHOOK_SECRET, reinicia y haz clic en «Probar».

5. 5

   Haz la primera sincronización con POST /admin/canalpulse/sync: te dice qué SKU faltan en cada lado.

shasum -a 256 canalpulse-medusa-0.1.0.tgz
npm install ./canalpulse-medusa-0.1.0.tgz

plugins: [
  {
    resolve: "@canalpulse/medusa",
    options: {
      apiKey: process.env.CANALPULSE_API_KEY,              // qsk_…
      webhookSecret: process.env.CANALPULSE_WEBHOOK_SECRET, // whsec_…
    },
  },
],

npx medusa db:migrate

Otra plataforma (API)

Para una tienda a la medida o cualquier plataforma headless. Autenticación: Authorization: Bearer qsk_…. Precios en centavos de MXN.

1. 1

   GET /api/v1/products: catálogo con precio del sitio, stock disponible, fotos, peso y medidas. Guárdalo en caché y refréscalo cada pocos minutos.

2. 2

   GET /api/v1/stock?skus=A,B: existencias rápidas de unos SKU.

3. 3

   POST /api/v1/reservations al iniciar el pago: aparta todo o nada (409 si algún SKU no alcanza; máximo 50 SKU distintos). Es idempotente por idempotency_key; el apartado dura 30 min por omisión y 2 h como máximo.

4. 4

   POST /api/v1/reservations/{id}/confirm cuando el pago se aprueba: descuenta el stock y crea la venta. Envía el folio de tu pedido, el comprador, el envío cobrado y, si quieres, lo cobrado por SKU (line_prices) y los renglones sin stock (extra_lines).

5. 5

   POST /api/v1/reservations/{id}/release si el pago falla o el carrito se abandona. Si no lo llamas, el apartado vence solo.

6. 6

   Webhook de inventario: verifica X-Canalpulse-Signature-V2 (t=<ts>,v1=<hex>): HMAC-SHA256 con el secreto completo (whsec_…, como texto UTF-8) sobre «<ts>.» + el cuerpo crudo, y rechaza marcas de tiempo de más de 5 min. Luego vuelve a leer el stock de los SKU que llegan.

curl -X POST https://api.canalpulse.com/api/v1/reservations \
  -H "Authorization: Bearer qsk_…" -H "Content-Type: application/json" \
  -d '{"channel":"website","idempotency_key":"pedido-1042",
       "lines":[{"sku":"PLAYERA-NEGRA-M","quantity":2}]}'

POST https://tutienda.com/hooks/canalpulse
X-Canalpulse-Signature-V2: t=1760000000,v1=<hex>

{"generated_at":"2026-10-08T17:00:00Z","skus":["PLAYERA-NEGRA-M"]}