Usar la API

La API permite que tus propios sistemas lean y cambien suscripciones sin que nadie abra la aplicación, y te avisa cada vez que cambia una suscripción para que no tengas que estar preguntando.

Es útil si tienes una tienda headless, sincronizas las suscripciones con un ERP o un sistema de almacén, o quieres un mensaje en Slack cuando alguien cancela.

Mientras la API es nueva, la activamos tienda por tienda. Si Configuración > Integraciones > API dice "Contacta con soporte para que activen la API en esta tienda", escríbenos por el chat en vivo y la activaremos en la tuya.

Obtener un token

Ve a Supr Bundles & Subscriptions > Configuración > Integraciones > API. En la tarjeta Tokens de API:

Ponle al token un Nombre que describa qué lo va a usar, para poder rastrear uno filtrado, y elige qué puede hacer:

• Leer suscripciones, para un sistema que solo genera informes.
• Cambiar suscripciones, para uno que pausa, cancela o reprograma.
• Leer endpoints de webhook y Administrar endpoints de webhook, para configurar las notificaciones de eventos desde tu propio código en lugar de desde esta página.

Después haz clic en Crear token.

Da a cada sistema su propio token, para poder desactivar uno sin tocar los demás.

El token se muestra una sola vez. Cópialo de inmediato. No lo guardamos, así que si lo pierdes tendrás que crear uno nuevo. Revocar detiene al instante todo lo que use ese token.

Llamar a la API

Envía el token como token de portador (bearer):

curl https://subscriptions.super-simple.co/api/v1/subscriptions \
  -H "Authorization: Bearer sss_live_..."

Puedes listar suscripciones, obtener una y después pausar, reanudar, cancelar, omitir o dejar de omitir un pedido, cambiar la próxima fecha de cobro o el plan, y añadir, cambiar o quitar sus productos. Cada cambio responde con la suscripción tal como queda, así que nunca tienes que volver a preguntar justo después.

La API es para que la llamen tus propios servidores. No pongas un token en un navegador, en una aplicación móvil ni en nada que pueda ver un cliente, porque cualquiera que lo encuentre puede cambiar tus suscripciones.

Reintentar de forma segura

Si una llamada agota el tiempo de espera, no puedes saber si se realizó. Envía una cabecera Idempotency-Key con un valor propio en todo lo que cambie una suscripción, y si reintentas con la misma clave te devolvemos la primera respuesta en lugar de hacerlo dos veces:

curl -X POST https://subscriptions.super-simple.co/api/v1/subscriptions/123/pause \
  -H "Authorization: Bearer sss_live_..." \
  -H "Idempotency-Key: 9f1c2a7e-4b0d-4f2a-9c3e-8a1b2c3d4e5f"

Las claves duran un día. Reutilizar una con una solicitud distinta se rechaza en lugar de responderse, así que no puedes recibir por error la respuesta equivocada.

Cuántas llamadas puedes hacer

Todas las tiendas empiezan con el límite estándar, que se muestra en la lista Límite de solicitudes al crear un token. Si tu integración necesita más, pídenoslo y lo aumentaremos, y las opciones más altas aparecerán entonces en esa lista.

Cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Si te pasas, recibes un 429 con un Retry-After que indica cuántos segundos esperar.

También hay un límite para todos los tokens de tu tienda en conjunto, porque cada llamada también consume el límite de Shopify de tu tienda. Si una integración falla, ese límite es lo que evita que ralentice tu panel de administración y tu tienda.

Notificaciones de eventos

En lugar de preguntarnos por los cambios, deja que te avisemos. En Supr Bundles & Subscriptions > Configuración > Integraciones > API, en la tarjeta Notificaciones de eventos, introduce una URL, marca los eventos que quieras y haz clic en Agregar endpoint. Le enviamos un POST cada vez que ocurre uno, y el cuerpo contiene la suscripción exactamente como la devolvería la API.

Entre los eventos disponibles están la creación, pausa, reanudación, cancelación, renovación o fallo de una suscripción, el cambio de su próxima fecha de cobro, la omisión de un pedido o la anulación de esa omisión, el cambio de sus productos o de su plan, y la actualización de su método de pago o de su dirección de envío.

Tu URL debe usar https y ser accesible desde internet.

Comprobar que una notificación viene realmente de nosotros

Cuando añades un endpoint te mostramos un secreto de firma, una sola vez. Cada envío lleva estas cabeceras:

X-SSS-Topic: subscription.paused
X-SSS-Shop-Domain: your-store.myshopify.com
X-SSS-Timestamp: 1758300000
X-SSS-Hmac-SHA256: <signature>

La firma es el HMAC SHA256 en base64 de la marca de tiempo, un punto y el cuerpo exacto que enviamos, usando tu secreto. Compruébala antes de confiar en nada:

const crypto = require("crypto");

const expected = crypto
  .createHmac("sha256", YOUR_SECRET)
  .update(`${req.headers["x-sss-timestamp"]}.${rawBody}`)
  .digest("base64");

const ok = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(req.headers["x-sss-hmac-sha256"])
);

YOUR_SECRET es la cadena completa que te mostramos, que empieza por sss_whsec_. Úsala tal cual, incluido ese prefijo.

Usa el cuerpo sin procesar exactamente como llegó, no una versión recodificada del JSON analizado, o la firma no coincidirá.

Rechaza también todo aquello cuya marca de tiempo tenga más de cinco minutos. La marca de tiempo forma parte de lo que se firma, así que esto es lo que impide que alguien reenvíe una entrega que capturó antes.

Puedes rotar el secreto de un endpoint en cualquier momento con Nuevo secreto en la misma página. Eso solo cambia ese endpoint. Desactivar pausa los envíos a un endpoint y Quitar lo elimina.

Cuando tu endpoint no responde

Un envío que falla se reintenta con intervalos cada vez mayores durante aproximadamente un día antes de que lo demos por perdido. Si un endpoint rechaza 20 veces seguidas, lo desactivamos y te mostramos el motivo, para que una URL que ya no usas no se siga reintentando para siempre. Al hacer clic en Activar se borra ese estado.

Obtener ayuda

Si algo no funciona como debe, cada respuesta incluye un X-Request-Id. Indícaselo a soporte y podremos encontrar esa llamada exacta.

Preguntas frecuentes

• ¿Hay una API para las suscripciones?

Sí, esta. Se activa tienda por tienda mientras es nueva, así que contacta con soporte para activarla.

• ¿Necesito la API para cambiar muchas suscripciones a la vez, por ejemplo mover sus fechas de renovación?

No para un cambio puntual. En Suscripciones, filtra la lista, marca las suscripciones y usa la acción masiva Reprogramar. La API es para los cambios que tus propios sistemas hacen con regularidad.

• ¿Puede otra aplicación (por ejemplo, una de afiliados o un ERP) leer los datos de las suscripciones?

Shopify solo permite leer una suscripción a la aplicación que la creó, así que otras aplicaciones no pueden ver directamente nuestras suscripciones. Conecta tu sistema a esta API, o haz que la otra aplicación lea las etiquetas de pedido y de cliente que puede añadir la aplicación; consulta Configuración de etiquetas.

• He perdido mi token.

No podemos volver a mostrarlo. Revoca el antiguo y crea un token nuevo.

• ¿Puedo poner el token en el tema de mi tienda o en una aplicación móvil?

No. Cualquiera que pudiera verlo podría cambiar tus suscripciones. Llama a la API solo desde tu propio servidor.

Actualizado el: 24/10/2026