¿Qué es la API de Alva Digital Downloads?
La API de Alva Digital Downloads es una API REST con versiones — v1 — que permite a un sistema externo gestionar descargas digitales en una tienda Shopify sin abrir el panel de administración de Shopify. A través de ella, un desarrollador puede crear archivos, asignarlos a productos, buscar pedidos, emitir URL de descarga, reenviar emails de entrega y consultar el stock de claves de licencia, todo por HTTPS estándar.
La API convive con la interfaz de administración de la app en lugar de sustituirla. Cada recurso que toca — archivos, asignaciones de productos, categorías, pedidos, etiquetas de claves de licencia — son los mismos datos que tu equipo edita a mano en Alva, solo que accesibles desde código. Eso la convierte en el puente entre Alva Digital Downloads y todo lo demás que dirige tu negocio.
Qué puedes hacer con la API de Alva
La API de Alva cubre el flujo de entrega principal de principio a fin. Gestiona archivos, asignaciones de productos y categorías, busca pedidos y emite URL de descarga, reenvía emails de entrega con tu marca, e informa del stock de claves de licencia. Los archivos se pueden subir directamente o ingestar desde una URL remota que Alva transmite directamente al almacenamiento en tu nombre.
En términos prácticos, una integración puede:
- Gestionar archivos — sube un archivo directamente, o dale a Alva una URL y transmite el activo al almacenamiento por ti (ingesta desde URL remota), de modo que una biblioteca grande nunca tiene que pasar antes por tus propios servidores.
- Asignar productos y categorías — adjunta archivos, paquetes, enlaces o etiquetas de claves de licencia a productos de Shopify usando el mismo modelo de muchos a muchos que usa el panel de administración.
- Buscar pedidos y emitir URL de descarga — resuelve un pedido de Shopify y genera una URL de descarga nueva y con tiempo limitado para el comprador.
- Reenviar emails de entrega — vuelve a disparar el email de descarga de un pedido desde código, sin editar nada a mano.
- Consultar el stock de claves de licencia — lee cuántas claves quedan para una etiqueta antes de un gran lanzamiento, para que nunca te quedes sin existencias sin darte cuenta.
Las rutas de los endpoints, los cuerpos de las solicitudes y las formas de las respuestas están en la referencia de la API. Este artículo se queda en el nivel de para qué sirve la API; la referencia es donde conectas cada llamada concreta.
Cómo funcionan la autenticación y las claves de API
La autenticación usa claves de API por tienda. Cada solicitud lleva un token Bearer que empieza por adk_live_. Alva Digital Downloads almacena solo un hash sha256 del secreto — nunca el texto plano — lo compara en tiempo constante y falla de forma segura, de modo que una clave ausente, mal formada, desconocida o revocada devuelven todas la misma respuesta de no autorizado.
Creas una clave dentro del panel de administración de Alva, copias el token una vez y lo guardas en un gestor de secretos. Alva conserva solo el id público de la clave y el hash, así que el secreto en texto plano nunca es recuperable desde tu cuenta. Como cada modo de fallo devuelve una respuesta idéntica, un atacante no puede sondear tu tienda para distinguir una clave incorrecta de una revocada.
Emite una clave distinta por sistema, y revoca cualquiera de ellas en el momento en que una integración se retira. Una clave revocada deja de funcionar de inmediato en todos los endpoints, lo que convierte la rotación de credenciales en una acción de un clic en lugar de una migración coordinada.
Diseñada para la automatización a escala
La API de Alva está diseñada para ser dirigida por máquinas que reintentan. Las claves de idempotencia son obligatorias en cada escritura, con una ventana de repetición de 24 horas que convierte una solicitud duplicada en la respuesta original en lugar de en un segundo registro. Un limitador de velocidad de tipo token-bucket protege la tienda, y cada respuesta devuelve un request_id para el rastreo.
La idempotencia no es opcional en las escrituras. Cada solicitud que no sea GET debe enviar una cabecera Idempotency-Key; reutiliza la misma clave y el mismo cuerpo y Alva repite de forma segura el primer resultado en lugar de crear un archivo, una asignación o una asignación de clave duplicados. Un reintento tras una conexión caída es, por tanto, inofensivo:
curl https://.../api/v1/mappings \
-H "Authorization: Bearer adk_live_..." \
-H "Idempotency-Key: 2f9c-4b1e-...-e1" \
-H "Content-Type: application/json" \
-d '{ "product_id": "gid://shopify/Product/123", ... }'Más allá de la idempotencia, un limitador de velocidad de tipo token-bucket limita las ráfagas para que un script descontrolado no pueda saturar tu canal de entrega, los valores sensibles se ocultan de los registros, y la ingesta desde URL remota se ejecuta detrás de una protección SSRF que bloquea las solicitudes dirigidas a direcciones internas. El request_id de cada respuesta te da a ti y al soporte de Alva una única cadena para rastrear una llamada desde la solicitud hasta el resultado.
¿API o Shopify Flow: cuál es tu camino?
Alva Digital Downloads te ofrece dos maneras de automatizar. Shopify Flow es el camino sin código — disparadores y acciones visuales que montas en el editor de Shopify. La API es el camino de código, para equipos que necesitan control programático desde sus propios sistemas. La mayoría de las tiendas nunca necesitan la API; Flow cubre las automatizaciones habituales.
Si tu objetivo es etiquetar a un cliente marcado por fraude, revocar el acceso en un reembolso o recompensar a los compradores VIP, constrúyelo de forma visual — la guía de automatizaciones de Shopify Flow para descargas digitales recorre los disparadores y las acciones de Alva. Recurre a la API cuando la lógica vive fuera de Shopify: un ERP que gestiona tu catálogo, un LMS que aprovisiona el acceso a cursos, o un CRM que debe mantenerse sincronizado. Por debajo, ambos impulsan el mismo motor detrás de la entrega multicanal de descargas de Alva.
Para quién es la API de Alva
La API de Alva está dirigida a tres públicos: desarrolladores que quieren automatizar por script el trabajo masivo de archivos y asignaciones, agencias que construyen escaparates de Shopify personalizados o headless que entregan bienes digitales, y equipos de operaciones que sincronizan descargas con un ERP, LMS o CRM externo. Los comerciantes que llevan un escaparate estándar de Shopify rara vez la necesitan.
Un desarrollo headless puede mantener Shopify como fuente de la verdad para los pedidos mientras la API emite URL de descarga a un front end a medida. Un equipo de operaciones puede dejar que su ERP cree archivos y asignaciones en el momento en que un producto se publica, de modo que el escaparate y la trastienda nunca se desvíen. El hilo común es el control que tiene que originarse fuera del panel de administración de Shopify.
Nada de esto es un requisito para vender productos digitales en Shopify — el panel de administración de Alva ya se encarga de eso de principio a fin. La API es para la minoría de tiendas cuya escala o arquitectura ha superado el uso de una interfaz a base de clics.
Cómo obtener acceso a la API
El acceso a la API es opcional y está limitado. Un indicador de disponibilidad global más un interruptor por tienda hacen que la API se active para una tienda cada vez, bajo petición, en lugar de estar habilitada para todos por defecto. Contacta con el soporte de Alva para activarla en tu tienda. La API está disponible en los planes de pago y se está desplegando de forma gradual.
Pide al soporte de Alva que habilite el acceso a la API, luego crea una clave desde el panel de administración de Alva. La guía de ayuda para usar la API externa recorre las claves, la idempotencia, la ingesta remota y las asignaciones de pedidos, y el build incluye una referencia completa de la API, una especificación OpenAPI descargable y una colección de Postman. Consulta los planes para ver dónde se sitúa la API.
Preguntas frecuentes
La API de Alva Digital Downloads es una API REST con versiones, v1, que permite a un sistema externo gestionar descargas digitales en una tienda Shopify sin usar el panel de administración de Shopify. A través de ella, un desarrollador puede crear archivos, asignarlos a productos, buscar pedidos, emitir URL de descarga, reenviar emails de entrega y consultar el stock de claves de licencia por HTTPS estándar.
Solo para las escrituras. Cada solicitud que no sea GET debe incluir una cabecera Idempotency-Key, que tiene una ventana de repetición de 24 horas, de modo que una llamada reintentada devuelve la respuesta original en lugar de crear un archivo, una asignación o una asignación de clave duplicados. Las solicitudes de lectura no la necesitan. Esto mantiene seguras frente a cambios duplicados las automatizaciones que reintentan tras un error de red.
La API usa claves de API por tienda. Cada solicitud envía un token Bearer que empieza por adk_live_. La app almacena solo un hash sha256 del secreto, nunca el texto plano, lo compara en tiempo constante y falla de forma segura, de modo que una clave ausente, mal formada, desconocida o revocada devuelven todas la misma respuesta de no autorizado y no se pueden distinguir entre sí.
Shopify Flow es el camino de automatización sin código, construido a partir de disparadores y acciones visuales dentro de Shopify. La API es el camino de código, para equipos que necesitan control programático desde sus propios sistemas. Usa Flow para las automatizaciones que viven dentro de Shopify, y la API cuando la lógica vive en un ERP, LMS o CRM externo.
El acceso a la API es opcional y está limitado por tienda. Un indicador de disponibilidad global más un interruptor por tienda hacen que se active de forma individual bajo petición, en lugar de estar habilitado para todos por defecto. Contacta con el soporte de Alva para activarlo en tu tienda. La API está disponible en los planes de pago y se está desplegando de forma gradual.