Qu'est-ce que l'API Alva Digital Downloads ?
L'API Alva Digital Downloads est une API REST versionnée — v1 — qui permet à un système externe de gérer les téléchargements numériques d'une boutique Shopify sans ouvrir l'administration Shopify. Grâce à elle, un développeur peut créer des fichiers, les associer à des produits, rechercher des commandes, émettre des URL de téléchargement, renvoyer des e-mails de livraison et vérifier le stock de clés de licence, le tout via HTTPS standard.
L'API accompagne l'interface d'administration de l'application plutôt qu'elle ne la remplace. Chaque ressource qu'elle touche — fichiers, associations de produits, catégories, commandes, étiquettes de clés de licence — correspond aux mêmes données que votre équipe modifie à la main dans Alva, simplement accessibles depuis du code. Cela en fait le pont entre Alva Digital Downloads et tout ce qui fait tourner votre entreprise.
Ce que vous pouvez faire avec l'API Alva
L'API Alva couvre le flux de livraison principal de bout en bout. Elle gère les fichiers, les associations de produits et les catégories, recherche les commandes et émet des URL de téléchargement, renvoie des e-mails de livraison personnalisés, et rend compte du stock de clés de licence. Les fichiers peuvent être téléversés directement, ou ingérés depuis une URL distante qu'Alva diffuse directement dans le stockage en votre nom.
Concrètement, une intégration peut :
- Gérer les fichiers — téléverser un fichier directement, ou fournir une URL à Alva qui diffuse l'actif dans le stockage pour vous (ingestion depuis URL distante), de sorte qu'une vaste bibliothèque n'a jamais à transiter d'abord par vos propres serveurs.
- Associer des produits et des catégories — attacher des fichiers, des packs, des liens ou des étiquettes de clés de licence à des produits Shopify en utilisant le même modèle plusieurs-à-plusieurs que l'administration.
- Rechercher des commandes et émettre des URL de téléchargement — retrouver une commande Shopify et générer une URL de téléchargement neuve et à durée limitée pour l'acheteur.
- Renvoyer des e-mails de livraison — redéclencher l'e-mail de téléchargement d'une commande depuis du code, sans rien modifier à la main.
- Vérifier le stock de clés de licence — consulter combien de clés il reste pour une étiquette avant un grand lancement, afin de ne jamais être en rupture sans le savoir.
Les chemins des points de terminaison, les corps de requête et la structure des réponses figurent dans la référence de l'API. Cet article reste au niveau de ce à quoi sert l'API ; c'est dans la référence que vous branchez chaque appel individuel.
Comment fonctionnent l'authentification et les clés API
L'authentification utilise des clés API par boutique. Chaque requête porte un jeton Bearer qui commence par adk_live_. Alva Digital Downloads ne stocke qu'un hachage sha256 du secret — jamais le texte en clair — le compare en temps constant, et échoue en mode fermé, de sorte qu'une clé manquante, mal formée, inconnue ou révoquée renvoie toujours la même réponse « non autorisé ».
Vous créez une clé dans l'administration Alva, copiez le jeton une seule fois, et le stockez dans un gestionnaire de secrets. Alva ne conserve que l'identifiant public de la clé et le hachage, de sorte que le secret en clair n'est jamais récupérable depuis votre compte. Parce que chaque mode de défaillance renvoie une réponse identique, un attaquant ne peut pas sonder votre boutique pour distinguer une clé erronée d'une clé révoquée.
Émettez une clé distincte par système, et révoquez n'importe laquelle dès qu'une intégration est mise hors service. Une clé révoquée cesse de fonctionner immédiatement sur tous les points de terminaison, ce qui fait de la rotation des identifiants une action en un clic plutôt qu'une migration coordonnée.
Conçue pour l'automatisation à grande échelle
L'API Alva est conçue pour être pilotée par des machines qui réessaient. Des clés d'idempotence sont exigées sur chaque écriture, avec une fenêtre de rejeu de 24 heures qui transforme une requête dupliquée en la réponse d'origine plutôt qu'en un second enregistrement. Un limiteur de débit à seau de jetons protège la boutique, et chaque réponse renvoie un request_id à des fins de traçage.
L'idempotence n'est pas facultative sur les écritures. Chaque requête non-GET doit envoyer un en-tête Idempotency-Key ; réutilisez la même clé et le même corps, et Alva rejoue en toute sécurité le premier résultat au lieu de créer un fichier, une association ou une attribution en double. Une nouvelle tentative après une connexion interrompue est donc sans danger :
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", ... }'Au-delà de l'idempotence, un limiteur de débit à seau de jetons plafonne les rafales afin qu'un script emballé ne puisse pas submerger votre pipeline de livraison, les valeurs sensibles sont expurgées des journaux, et l'ingestion depuis URL distante s'exécute derrière une protection SSRF qui bloque les requêtes visant des adresses internes. Le request_id présent sur chaque réponse vous donne, à vous comme au support Alva, une chaîne unique pour tracer un appel de la requête au résultat.
API ou Shopify Flow : quelle voie est la vôtre ?
Alva Digital Downloads vous offre deux façons d'automatiser. Shopify Flow est la voie sans code — des déclencheurs et des actions visuels que vous assemblez dans l'éditeur de Shopify. L'API est la voie du code, pour les équipes qui ont besoin d'un contrôle par programmation depuis leurs propres systèmes. La plupart des boutiques n'ont jamais besoin de l'API ; Flow couvre les automatisations courantes.
Si votre objectif est d'étiqueter un client signalé pour fraude, de révoquer l'accès lors d'un remboursement, ou de récompenser les acheteurs VIP, construisez-le visuellement — le guide des automatisations Shopify Flow pour les téléchargements numériques détaille les déclencheurs et actions d'Alva. Optez pour l'API lorsque la logique réside en dehors de Shopify : un ERP qui détient votre catalogue, un LMS qui provisionne l'accès aux cours, ou un CRM qui doit rester synchronisé. En coulisses, les deux pilotent le même moteur derrière la livraison multi-canal des téléchargements d'Alva.
À qui s'adresse l'API Alva
L'API Alva vise trois publics : les développeurs qui souhaitent scripter des opérations en masse sur les fichiers et les associations, les agences qui construisent des boutiques Shopify personnalisées ou headless livrant des biens numériques, et les équipes opérationnelles qui synchronisent les téléchargements avec un ERP, un LMS ou un CRM externe. Les marchands exploitant une boutique Shopify standard en ont rarement besoin.
Une architecture headless peut conserver Shopify comme source de vérité pour les commandes tandis que l'API émet des URL de téléchargement vers une interface sur mesure. Une équipe opérationnelle peut laisser son ERP créer des fichiers et des associations dès qu'un produit est expédié, de sorte que la boutique et le back-office ne divergent jamais. Le fil conducteur est un contrôle qui doit prendre naissance en dehors de l'administration Shopify.
Rien de tout cela n'est requis pour vendre des produits numériques sur Shopify — l'administration Alva s'en charge déjà de bout en bout. L'API est destinée à la minorité de boutiques dont l'échelle ou l'architecture a dépassé le stade du clic dans une interface utilisateur.
Comment obtenir l'accès à l'API
L'accès à l'API se fait sur activation et est contrôlé. Un indicateur de disponibilité global associé à un interrupteur par boutique signifie que l'API est activée pour une boutique à la fois sur demande, et non activée pour tout le monde par défaut. Contactez le support Alva pour l'activer sur votre boutique. L'API est disponible sur les forfaits payants et est déployée progressivement.
Demandez au support Alva d'activer l'accès à l'API, puis créez une clé depuis l'administration Alva. Le guide d'aide sur l'utilisation de l'API externe détaille les clés, l'idempotence, l'ingestion à distance et les attributions de commandes, et la version fournie s'accompagne d'une référence d'API complète, d'une spécification OpenAPI téléchargeable et d'une collection Postman. Consultez les forfaits pour savoir où se situe l'API.
Questions fréquentes
L'API Alva Digital Downloads est une API REST versionnée, v1, qui permet à un système externe de gérer les téléchargements numériques d'une boutique Shopify sans utiliser l'administration Shopify. Grâce à elle, un développeur peut créer des fichiers, les associer à des produits, rechercher des commandes, émettre des URL de téléchargement, renvoyer des e-mails de livraison et vérifier le stock de clés de licence via HTTPS standard.
Uniquement pour les écritures. Chaque requête non-GET doit inclure un en-tête Idempotency-Key, doté d'une fenêtre de rejeu de 24 heures, de sorte qu'un appel réessayé renvoie la réponse d'origine au lieu de créer un fichier, une association ou une attribution en double. Les requêtes de lecture n'en ont pas besoin. Cela évite aux automatisations qui réessaient après une erreur réseau d'effectuer des modifications en double.
L'API utilise des clés API par boutique. Chaque requête envoie un jeton Bearer qui commence par adk_live_. L'application ne stocke qu'un hachage sha256 du secret, jamais le texte en clair, le compare en temps constant, et échoue en mode fermé, de sorte qu'une clé manquante, mal formée, inconnue ou révoquée renvoie toujours la même réponse « non autorisé » et ne peut être distinguée des autres.
Shopify Flow est la voie d'automatisation sans code, construite à partir de déclencheurs et d'actions visuels au sein de Shopify. L'API est la voie du code, pour les équipes qui ont besoin d'un contrôle par programmation depuis leurs propres systèmes. Utilisez Flow pour les automatisations qui résident au sein de Shopify, et l'API lorsque la logique réside dans un ERP, un LMS ou un CRM externe.
L'accès à l'API se fait sur activation et est contrôlé par boutique. Un indicateur de disponibilité global associé à un interrupteur par boutique signifie qu'il est activé individuellement sur demande, et non activé pour tout le monde par défaut. Contactez le support Alva pour l'activer sur votre boutique. L'API est disponible sur les forfaits payants et est déployée progressivement.