🧠Connecter Big Digital Downloads à un CRM, ERP ou une application (API publique/Webhooks)
Avertissement
Ces fonctionnalités sont disponibles à partir du**** Plan de Croissance ****et au-delà.
Si vous vendez des produits numériques sur Shopify, vos données de commande, clés de licence et analyses de téléchargement doivent probablement vivre à plusieurs endroits. Votre CRM doit savoir quand quelqu'un achète un ebook. Votre serveur de licences doit valider les clés lorsque les clients activent votre logiciel. Votre équipe de support doit pouvoir renvoyer des e-mails de téléchargement ou réinitialiser les limites de téléchargement sans ouvrir l'admin à chaque fois.
L'API Publique et les Webhooks de Big Digital Downloads rendent tout cela possible. L'API vous offre 21 points de terminaison pour lire les commandes et les produits, gérer les clés de licence de la création à l'attribution, télécharger et supprimer des fichiers, créer des liens de téléchargement sécurisés, activer ou désactiver l'accès au téléchargement, renvoyer des e-mails de livraison et extraire des statistiques de téléchargement. Les Webhooks envoient des notifications en temps réel à votre serveur chaque fois qu'une commande est achetée, qu'un e-mail de livraison est envoyé ou qu'un fichier est téléchargé.
Les deux fonctionnalités sont actuellement en Beta.
La référence API interactive complète avec tous les schémas et exemples de réponse est disponible sur https://islandcloud.co/public-api/docs
Que pouvez-vous construire avec l'API Big Digital Downloads ?
Voici des scénarios d'intégration réels que les commerçants construisent en ce moment :
Construisez un serveur de validation de licence pour votre logiciel. Lorsqu'un client achète votre application de bureau ou votre plugin, Big DD attribue une clé de licence. Votre logiciel appelle le point de terminaison Validate au lancement pour vérifier si la clé est valide et attribuée. Aucun service de licence tiers n'est nécessaire.
Importez en masse des clés de licence depuis votre générateur de clés. Utilisez le point de terminaison par lot pour pousser jusqu'à 5 000 clés par demande, étiquetées par produit ou nom de lot, avec dé-duplication automatique. Votre pipeline de génération de clés fonctionne selon son propre calendrier, et l'inventaire de Big DD reste synchronisé.
Synchronisez chaque commande avec HubSpot, Salesforce ou tout CRM. Lorsqu'un client achète un produit numérique, un webhook se déclenche instantanément avec toutes les données de commande (nom du client, e-mail, produits, prix, statut financier). Votre CRM crée ou met à jour le contact automatiquement sans saisie manuelle des données.
Automatisez les flux de travail avec Zapier ou Make sans code. Dirigez un webhook Big DD vers votre URL de webhook Zapier ou Make. Chaque commande ou événement de téléchargement devient un déclencheur. Envoyez une notification Slack lorsqu'une personne achète, ajoutez une ligne à Google Sheets, déclenchez une séquence de goutte à goutte dans Klaviyo, ou créez une tâche dans Asana.
Construisez un portail de téléchargement personnalisé. Utilisez l'API pour lister les commandes d'un client et son historique de téléchargements, générez des liens de téléchargement sécurisés avec des limites optionnelles et un filigrane PDF, et gérez l'accès de manière programmatique. Votre frontend appelle votre backend, qui appelle l'API Big DD.
Renvoyez des e-mails de livraison ou réinitialisez les limites de téléchargement depuis votre tableau de bord de support. Au lieu d'ouvrir l'admin Big DD pour chaque ticket de support, appelez l'API depuis votre outil de helpdesk. Un point de terminaison renvoie l'e-mail (optionnellement à une nouvelle adresse), un autre réinitialise le compteur de téléchargements.
Alimentez les analyses de téléchargement dans votre outil BI. Extrayez les comptes de téléchargements agrégés, l'utilisation de la bande passante et les fichiers les plus téléchargés pour n'importe quelle fenêtre temporelle. Exportez vers votre entrepôt de données ou Google Sheets pour des tableaux de bord personnalisés.
Protégez vos PDF avec un filigrane automatique. Lors de la création de liens de téléchargement via l'API, activez le tampon PDF pour filigraner chaque PDF avec un texte personnalisé comme le nom du client ou le numéro de commande. Cela fonctionne automatiquement pour tous les PDF dans le lien.
Authentification
Chaque requête API nécessite un jeton Bearer généré depuis votre admin Big Digital Downloads. Les jetons ont un accès complet en lecture et écriture aux commandes, produits, clés de licence et fichiers de votre boutique. Traitez-les comme des mots de passe : ne les engagez pas dans le contrôle de version et ne les partagez pas dans des canaux publics.
Comment générer votre jeton API
Dans votre admin Shopify, ouvrez l'application Big Digital Downloads.
Allez dans Paramètres > API Publique.
Cliquez sur Générer un jeton.
Donnez à votre jeton un nom descriptif afin que vous puissiez l'identifier plus tard, par exemple "synchronisation CRM", "serveur de licence" ou "Zapier".
Cliquez sur Générer.
Big Digital Downloads vous montre le jeton complet une seule fois. Copiez-le immédiatement et conservez-le dans un endroit sûr comme un gestionnaire de mots de passe ou les variables d'environnement de votre serveur.
Vous pouvez révoquer n'importe quel jeton à tout moment depuis la même page. Révoquer un jeton arrête immédiatement toutes les requêtes API l'utilisant.
Utilisation de votre jeton
Incluez le jeton dans l'en-tête Authorization de chaque requête API :
Authorization: Bearer YOUR_TOKEN_HERE
Exemple avec curl :
curl https://islandcloud.co/public-api/v1/digital-products \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
Si le jeton est manquant ou invalide, l'API renvoie 401.
Points de terminaison API
URL de base : https://islandcloud.co
L'API est organisée en 7 domaines : produits numériques, commandes, clés de licence, fichiers, liens de téléchargement, statistiques de téléchargement et téléchargements clients.
Produits numériques
Lister les produits numériques
GET /public-api/v1/digital-products
Renvoie tous les produits numériques de votre boutique. Utilisez ceci pour découvrir les ID de produit, les types de livraison, les modes d'accès, les limites de téléchargement et les fichiers liés avant de faire d'autres appels API.
Paramètres de requête :
limit (optionnel, 1-100) : nombre de résultats par page.
cursor (optionnel) : curseur de pagination d'une réponse précédente.
include_archived (optionnel, true ou false) : inclure les produits archivés. Par défaut, c'est faux.
q (optionnel, max 120 caractères) : rechercher par nom de produit.
include (optionnel) : passez product pour attacher le titre et l'image du produit Shopify. Cela coûte un appel GraphQL supplémentaire par produit, donc utilisez-le uniquement lorsque vous en avez besoin.
sort (optionnel) : -id (par défaut, le plus récent en premier), id (le plus ancien en premier), created_at, -created_at.
Exemple de requête :
curl "https://islandcloud.co/public-api/v1/digital-products?limit=10&include=product" \
-H "Authorization: Bearer VOTRE_TOKEN_ICI"
Exemple de réponse (abrégé) :
{
"data": [
{
"id": "6789abcdef0123456789abcd",
"name": "Pack de Préréglages de Photographie",
"delivering_type": "REGULAR",
"access": "FILE",
"download_mode": "redirect",
"download_type": "single_file",
"product_gid": "gid://shopify/Product/123456789",
"variant_gids": [],
"use_all_variants": true,
"license_key_tag": null,
"license_key_mode": null,
"download_in": 30,
"max_downloads": 5,
"notify_when_updated": false,
"scheduled_delivery_date": null,
"scheduled_delivery_timezone": null,
"is_archived": false,
"files": [
{
"id": "aaa111bbb222ccc333ddd444",
"name": "presets-v2.zip",
"size": 15728640,
"type": "application/zip",
"is_encrypted": true,
"uploaded": true
}
],
"links": [],
"product": {
"title": "Pack de Préréglages de Photographie",
"image": "https://cdn.shopify.com/..."
},
"created_at": "2025-11-01T10:00:00.000Z",
"updated_at": "2026-05-10T08:30:00.000Z"
}
],
"pagination": {
"has_more": false,
"next_cursor": null
}
}
Comprendre les champs clés des produits numériques
delivering_type détermine comment les fichiers atteignent le client :
REGULAR signifie que tous les clients reçoivent les mêmes fichiers. C'est le mode le plus courant pour les ebooks, modèles, préréglages, musique et tout produit où chaque acheteur obtient le même téléchargement.
UNIQUE signifie que chaque client reçoit des fichiers différents. Vous assignez des fichiers spécifiques à chaque ligne de commande via l'API ou l'admin. Utile pour du contenu personnalisé, des œuvres d'art sur mesure ou des actifs uniques.
SCHEDULED signifie que les fichiers sont livrés à une date future spécifique. Utilisez ceci pour les précommandes ou les sorties chronométrées où tous les acheteurs reçoivent les fichiers simultanément à une date fixée.
access détermine ce que le client reçoit :
FILE signifie que le client obtient uniquement des fichiers téléchargeables.
LICENSE_KEY signifie que le client reçoit uniquement une clé de licence, sans fichiers.
FILE_WITH_LICENCE_KEY signifie que le client obtient à la fois des fichiers et une clé de licence.
max_downloads est le nombre maximum de fois que chaque client peut télécharger les fichiers. 0 ou null signifie illimité.
download_in est le nombre de jours pendant lesquels le lien de téléchargement reste valide après l'achat. 0 ou null signifie pas d'expiration.
files est la liste des fichiers attachés à ce produit. Chaque fichier inclut son ID, son nom, sa taille, son type MIME et son statut de cryptage.
Obtenir un produit numérique unique
GET /public-api/v1/digital-products/{id}
Renvoie les détails complets d'un produit, y compris les mêmes champs que l'endpoint de liste.
Mettre à jour les limites de téléchargement
PUT /public-api/v1/digital-products/{id}/limits
Change la limite de téléchargement et l'expiration du lien pour un produit. C'est la seule opération d'écriture sur les produits numériques. Toute autre configuration de produit (nom, fichiers, type de livraison) est gérée depuis l'admin.
Corps :
{
"max_downloads": 10,
"download_in": 60
}
Définissez max_downloads à 0 ou null pour illimité. Définissez download_in à 0 ou null pour pas d'expiration. Valeurs maximales : 1 000 000 téléchargements, 100 000 jours.
Exemple : donner aux clients plus de téléchargements après une mise à jour de produit :
curl -X PUT "https://islandcloud.co/public-api/v1/digital-products/6789abcdef0123456789abcd/limits" \
-H "Authorization: Bearer VOTRE_TOKEN_ICI" \
-H "Content-Type: application/json" \
-d '{"max_downloads": 10, "download_in": 90}'
Commandes
Lister les commandes
GET /public-api/v1/orders
Renvoie les commandes numériques pour votre boutique. C'est l'endpoint que vous utilisez pour les synchronisations CRM, les exports de rapports et les tableaux de bord de commandes personnalisés.
Paramètres de requête :
limit (optionnel, 1-100) : résultats par page.
cursor (optionnel) : curseur de pagination.
created_after (optionnel, ISO 8601) : uniquement les commandes créées à partir de cette date (inclus).
created_before (optionnel, ISO 8601) : uniquement les commandes créées avant cette date (exclus).
financial_status (optionnel, tableau) : AUTHORIZED, EXPIRED, PAID, PARTIALLY_PAID, PARTIALLY_REFUNDED, PENDING, REFUNDED, VOIDED.
digital_product_id (optionnel, tableau d'IDs) : filtrer par un ou plusieurs produits numériques.
customer_email (optionnel) : filtrer par email client exact.
q (optionnel, max 120 caractères) : rechercher par nom de commande (ex. #1001).
include (optionnel, tableau) : product attache le titre et l'image du produit Shopify à chaque ligne. downloads attache les événements de téléchargement enregistrés pour chaque ligne.
sort (optionnel) : -id (par défaut, le plus récent en premier), id, created_at, -created_at.
Exemple : obtenir toutes les commandes payées du mois dernier :
curl "https://islandcloud.co/public-api/v1/orders?financial_status=PAID&created_after=2026-05-01T00:00:00Z&created_before=2026-06-01T00:00:00Z&sort=-created_at" \
-H "Authorization: Bearer VOTRE_TOKEN_ICI"
Exemple : trouver toutes les commandes pour un client spécifique :
curl "https://islandcloud.co/public-api/v1/[email protected]&include=downloads" \
-H "Authorization: Bearer VOTRE_TOKEN_ICI"
Exemple de réponse (abrégé) :
Comprendre les champs clés de la commande
dl_access est soit enabled soit disabled. Lorsqu'il est désactivé, le client ne peut pas accéder à sa page de téléchargement. Vous pouvez basculer cela via l'API.
is_imported est true lorsque la commande a été importée d'un autre système plutôt que créée via le processus de paiement Shopify.
lines est le tableau des articles de ligne. Chaque ligne représente un produit numérique dans la commande. Elle inclut la quantité, le prix en cents, le produit numérique associé, les clés de licence attribuées, et éventuellement les événements de téléchargement si vous avez utilisé include=downloads.
price_cents est le prix dans la plus petite unité monétaire (cents pour USD/EUR, pence pour GBP). Divisez par 100 pour obtenir le prix affiché.
Obtenir une seule commande
GET /public-api/v1/orders/{id}
Renvoie tous les détails d'une commande, y compris les lignes, les clés de licence, et éventuellement les événements de téléchargement.
Activer ou désactiver l'accès au téléchargement
POST /public-api/v1/orders/{id}/access
Bascule si le client peut accéder à sa page de téléchargement pour cette commande. Utile pour révoquer l'accès après un remboursement ou le réactiver après avoir résolu un litige.
curl -X POST "https://islandcloud.co/public-api/v1/orders/abc123def456ghi789jkl012/access" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{"access": "disabled"}'
Réinitialiser le compteur de téléchargements
POST /public-api/v1/orders/{id}/reset-downloads
Réinitialise le compteur de téléchargements pour un article de ligne spécifique à zéro. Utilisez ceci lorsqu'un client a atteint sa limite de téléchargement et a besoin d'un nouvel accès, par exemple après une mise à jour de fichier ou une demande de support.
curl -X POST "https://islandcloud.co/public-api/v1/orders/abc123def456ghi789jkl012/reset-downloads" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{"line_id": "line_001"}'
Renvoyer l'email de livraison
POST /public-api/v1/orders/{id}/resend-email
Renvoyer l'email de téléchargement au client. Vous pouvez éventuellement passer une nouvelle adresse email pour mettre à jour l'email du client sur la commande avant l'envoi.
Exemple : renvoyer à l'email d'origine :
curl -X POST "https://islandcloud.co/public-api/v1/orders/abc123def456ghi789jkl012/resend-email" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{}'
Exemple : renvoyer à une adresse email différente (met à jour la commande) :
curl -X POST "https://islandcloud.co/public-api/v1/orders/abc123def456ghi789jkl012/resend-email" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{"customer_email": "[email protected]"}'
Associer des fichiers à une ligne de commande (livraison UNIQUE)
PUT /public-api/v1/orders/{id}/lines/{lineId}/files
Définit quels fichiers sont livrés pour une ligne de commande spécifique. Cela ne s'applique qu'aux produits avec delivering_type: "UNIQUE", où chaque client reçoit des fichiers différents.
Passez un tableau d'IDs de fichiers (des points de terminaison Fichiers) et éventuellement déclenchez l'email de livraison :
curl -X PUT "https://islandcloud.co/public-api/v1/orders/abc123def456ghi789jkl012/lines/line_001/files" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{"file_ids": ["file_aaa111", "file_bbb222"], "send_email": true}'
Définir send_email sur true envoie l'email de livraison au client après avoir associé les fichiers. Passez un tableau file_ids vide pour supprimer toutes les associations de fichiers de la ligne.
Clés de licence
La gestion des clés de licence est la partie la plus puissante de l'API. Vous pouvez construire un système complet de validation et de distribution de licences externes sans aucun service tiers.
Lister les clés de licence
GET /public-api/v1/license-keys
Renvoie toutes les clés de licence dans votre inventaire.
Paramètres de requête :
limit (facultatif, 1-100) : résultats par page.
cursor (facultatif) : curseur de pagination.
status (facultatif) : available (non encore attribué) ou assigned (consommé par une commande).
tag (facultatif) : filtrer par tag.
q (facultatif, max 120 caractères) : rechercher par valeur de clé.
sort (facultatif) : -id (par défaut), id, created_at, -created_at.
Exemple : lister toutes les clés disponibles étiquetées "photoshop-plugin" :
curl "https://islandcloud.co/public-api/v1/license-keys?status=available&tag=photoshop-plugin" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
Exemple de réponse (abrégé) :
{
"data": [
{
"id": "key_abc123",
"key": "PLUG-ABCD-1234-EFGH-5678",
"tag": "photoshop-plugin",
"assigned": false,
"order_id": null,
"order_name": null,
"created_at": "2026-05-01T10:00:00.000Z",
"updated_at": "2026-05-01T10:00:00.000Z"
}
],
"pagination": {
"has_more": true,
"next_cursor": "eyJpZCI6ImtleV9hYmMxMjMifQ=="
}
}
Valider une clé de licence
GET /public-api/v1/license-keys/validate?key=YOUR_KEY
Vérifie si une clé existe et si elle est assignée à une commande. C'est le point de terminaison que votre logiciel appelle lorsqu'un client active sa licence.
Exemple :
curl "https://islandcloud.co/public-api/v1/license-keys/validate?key=PLUG-ABCD-1234-EFGH-5678" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
Réponse :
{
"data": {
"valid": true,
"assigned": true,
"tag": "photoshop-plugin",
"order_name": "#1042",
"order_id": "abc123def456ghi789jkl012"
}
}
valid est true lorsque la clé existe dans votre inventaire. assigned est true lorsque la clé est liée à une commande. Si les deux sont true, le client a une licence légitime.
Une clé qui est valid: true mais assigned: false signifie qu'elle existe mais n'a pas encore été achetée. Une clé qui est valid: false n'existe pas dans votre inventaire.
Créer des clés de licence en lot
POST /public-api/v1/license-keys
Créez jusqu'à 5 000 clés de licence en une seule demande. Vous pouvez les taguer pour l'organisation et contrôler comment les doublons sont gérés.
Corps :
keys (obligatoire, tableau de chaînes, 1-5 000) : les chaînes de clés à ajouter.
tag (facultatif, max 120 caractères) : une étiquette pour regrouper les clés, par exemple le nom du produit ou l'identifiant de lot.
duplicates (facultatif) : skip (par défaut, ignorer les clés existantes), create (insérer des doublons quand même), fail (rejeter l'ensemble du lot si une clé existe déjà).
Exemple : importer 3 clés de votre générateur :
curl -X POST "https://islandcloud.co/public-api/v1/license-keys" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
"keys": [
"PLUG-AAAA-1111-BBBB-2222",
"PLUG-CCCC-3333-DDDD-4444",
"PLUG-EEEE-5555-FFFF-6666"
],
"tag": "photoshop-plugin-v3",
"duplicates": "skip"
}'
Prend en charge un en-tête Idempotency-Key facultatif. Si vous envoyez la même clé d'idempotence dans une fenêtre temporelle, l'API renvoie la même réponse sans créer de doublons. Utilisez cela pour réessayer en toute sécurité les demandes échouées.
Assigner une clé à une commande
POST /public-api/v1/license-keys/{id}/assign
Liaison d'une clé disponible à une commande spécifique par le nom de la commande. Envoie éventuellement l'email de livraison au client.
curl -X POST "https://islandcloud.co/public-api/v1/license-keys/key_abc123/assign" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{"order_name": "#1042", "send_email": true}'
La clé doit être en statut available. Si elle est déjà assignée, la demande échoue.
Désassigner une clé d'une commande
POST /public-api/v1/license-keys/{id}/unassign
Libère une clé de sa commande, la rendant à nouveau disponible dans l'inventaire. Utilisez ceci lors du traitement d'un remboursement ou lorsque qu'une clé a été assignée par erreur.
curl -X POST "https://islandcloud.co/public-api/v1/license-keys/key_abc123/unassign" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
Supprimer une clé de licence
DELETE /public-api/v1/license-keys/{id}
Supprime définitivement une clé non assignée de l'inventaire. La clé doit d'abord être désassignée. Si la clé est actuellement assignée à une commande, désassignez-la avant de la supprimer.
curl -X DELETE "https://islandcloud.co/public-api/v1/license-keys/key_abc123" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
Fichiers
Lister les fichiers
GET /public-api/v1/files
Renvoie tous les fichiers de votre bibliothèque.
Paramètres de requête :
limit (facultatif, 1-100) : résultats par page.
cursor (facultatif) : curseur de pagination.
q (facultatif, max 120 caractères) : recherche par nom de fichier.
type (facultatif) : filtre par type MIME exact, par exemple application/pdf ou application/zip.
uploaded (facultatif, vrai ou faux) : filtre par statut d'achèvement de l'upload.
include (facultatif) : passez products pour voir à quels produits numériques chaque fichier est lié.
sort (facultatif) : -id (par défaut), id, created_at, -created_at.
Exemple : lister tous les fichiers PDF :
curl "https://islandcloud.co/public-api/v1/files?type=application/pdf&include=products" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
Exemple de réponse (abrégé) :
{
"data": [
{
"id": "file_aaa111",
"name": "ebook-photography-basics.pdf",
"size": 4194304,
"type": "application/pdf",
"is_encrypted": true,
"uploaded": true,
"created_at": "2026-04-01T10:00:00.000Z",
"updated_at": "2026-04-01T10:00:00.000Z"
}
],
"pagination": {
"has_more": false,
"next_cursor": null
}
}
Télécharger un fichier
POST /public-api/v1/files
Télécharge un fichier dans votre bibliothèque. Envoyez le fichier en tant que multipart/form-data.
Limites : Maximum 25 Mo par fichier. Limité à 6 téléchargements par minute.
Exemple :
curl -X POST "https://islandcloud.co/public-api/v1/files" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-F "file=@/path/to/my-template.zip"
Avertissement
Gardez votre token API côté serveur. Pour les téléchargements côté front-end, proxy la demande via votre propre backend. Ne jamais exposer votre token dans le JavaScript côté client.
Supprimer un fichier
DELETE /public-api/v1/files/{id}
Supprime un fichier du stockage et du catalogue. L'API refuse la demande avec 409 Conflict si le fichier est toujours attaché à un produit numérique, une ligne de commande ou un lien de téléchargement. Détachez d'abord le fichier, puis supprimez-le.
curl -X DELETE "https://islandcloud.co/public-api/v1/files/file_aaa111" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
Liens de téléchargement
Créer un lien de téléchargement sécurisé
POST /public-api/v1/download-links
Regroupe un ou plusieurs fichiers dans une URL de téléchargement partageable. Optionnellement, définissez une limite de téléchargement et activez le marquage PDF (filigrane).
Corps :
file_ids (obligatoire, tableau, 1-100) : les identifiants de fichier à inclure.
use_download_limit (facultatif, booléen) : activez une limite de téléchargement sur ce lien.
download_limit (optionnel, entier) : nombre maximum de téléchargements. S'applique uniquement lorsque use_download_limit est true. 0 signifie illimité.
use_stamping (optionnel, booléen) : activer le filigrane PDF sur tous les PDF de ce lien.
stamping_text (optionnel, max 500 caractères) : le texte à utiliser pour le filigrane. Par exemple, le nom du client, l'email ou le numéro de commande.
Exemple : créer un lien de téléchargement avec filigrane limité à 3 téléchargements :
curl -X POST "https://islandcloud.co/public-api/v1/download-links" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
"file_ids": ["file_aaa111", "file_bbb222"],
"use_download_limit": true,
"download_limit": 3,
"use_stamping": true,
"stamping_text": "Licencié à : [email protected] — Commande #1042"
}'
Avertissement
Les liens de téléchargement peuvent être créés mais ne peuvent pas être listés, modifiés ou supprimés après création. Conservez l'URL retournée lors de sa création.
Statistiques de téléchargement
Statistiques de téléchargement agrégées
GET /public-api/v1/downloads/stats
Renvoie les comptes de téléchargements et la bande passante pour une période donnée. Par défaut, cela concerne les 30 derniers jours si aucune date n'est spécifiée.
Paramètres de requête :
start (optionnel, ISO 8601) : début de la période.
end (optionnel, ISO 8601) : fin de la période.
Exemple : statistiques pour mai 2026 :
curl "https://islandcloud.co/public-api/v1/downloads/stats?start=2026-05-01T00:00:00Z&end=2026-06-01T00:00:00Z" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
Exemple de réponse :
{
"data": {
"period": {
"start": "2026-05-01T00:00:00.000Z",
"end": "2026-06-01T00:00:00.000Z"
},
"total_downloads": 1423,
"counted_downloads": 1380,
"billable_downloads": 1200,
"total_bandwidth_bytes": 2147483648,
"top_files": [
{
"file": {
"id": "file_aaa111",
"name": "ebook-photography-basics.pdf",
"size": 4194304,
"type": "application/pdf"
},
"downloads": 342,
"bandwidth_bytes": 1434451968
}
]
}
}
total_downloads est chaque événement de téléchargement enregistré. counted_downloads exclut les re-téléchargements. billable_downloads est ce qui compte pour l'utilisation de votre plan. total_bandwidth_bytes est le nombre brut d'octets servis.
Téléchargements des clients
GET /public-api/v1/customers/{customer_gid}/downloads
Renvoie toutes les commandes numériques et les événements de téléchargement enregistrés pour un client spécifique. Utilisez le GID du client Shopify (par exemple, gid://shopify/Customer/987654321) ou l'ID numérique du client.
curl "https://islandcloud.co/public-api/v1/customers/987654321/downloads?limit=50" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
Ceci est utile pour créer une page d'historique de téléchargement pour le client ou pour les agents de support qui ont besoin de voir exactement ce qu'un client a téléchargé et quand.
Pagination
Tous les points de terminaison de liste utilisent la pagination basée sur le curseur. Lorsque la réponse inclut "has_more": true, passez la valeur next_cursor comme paramètre cursor dans votre prochaine requête :
curl "https://islandcloud.co/public-api/v1/orders?cursor=eyJpZCI6IjY3ODlhYmNkIn0=&limit=100" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
L'ordre de tri est préservé à travers les pages. La taille maximale de la page est de 100 résultats.
Codes d'erreur
200 Succès.
201 Ressource créée avec succès (fichiers, clés de licence, liens de téléchargement).
400 Erreur de validation. Un champ requis est manquant ou dans le mauvais format.
401 Token manquant ou invalide.
403 La boutique est inactive ou l'accès est restreint.
404 Ressource non trouvée. L'ID n'existe pas.
409 Conflit. Vous essayez de supprimer un fichier qui est encore attaché à un produit, une commande ou un lien de téléchargement.
413 Fichier trop volumineux. Le téléchargement dépasse la limite de 25 Mo.
429 Limite de taux dépassée. Espacez vos requêtes et réessayez après un moment.
Webhooks : notifications d'événements en temps réel
Alors que l'API vous permet de récupérer des données à la demande, les webhooks vous envoient des données instantanément. Chaque fois qu'une commande est achetée, qu'un email de livraison est envoyé ou qu'un client télécharge un fichier, Big Digital Downloads envoie un POST HTTP signé à l'URL que vous configurez.
Les webhooks sont essentiels pour créer des intégrations en temps réel : synchronisations CRM, notifications Slack, pipelines d'analytique, détection de fraude, ou tout flux de travail qui doit réagir aux événements au fur et à mesure qu'ils se produisent sans interroger.
Configurer un point de terminaison webhook
Dans votre admin Shopify, ouvrez l'application Big Digital Downloads.
Allez dans Paramètres > Webhooks.
Cliquez sur Ajouter un point de terminaison.
Entrez un nom pour votre point de terminaison, par exemple "synchronisation Zapier", "Analytique" ou "pipeline CRM".
Collez votre URL HTTPS. L'URL doit utiliser HTTPS.
Cochez les événements que vous souhaitez recevoir.
Cliquez sur Créer.
Big Digital Downloads affiche un secret de signature commençant par whsec_. Copiez-le immédiatement et conservez-le en sécurité. Ce secret n'est affiché qu'une seule fois et vous en avez besoin pour vérifier les requêtes webhook entrantes sur votre serveur.
Vous pouvez modifier n'importe quel point de terminaison ultérieurement pour changer l'URL ou activer ou désactiver des événements spécifiques. Utilisez le bouton Tester pour envoyer un événement de test et le bouton Voir les livraisons pour vérifier l'historique des livraisons.
Les 4 événements webhook
digital_order.purchased se déclenche lorsqu'un client finalise un achat incluant un produit numérique. La charge utile contient la commande complète avec les données du client, les articles, les prix et le statut financier.
digital_order.delivered se déclenche lorsque l'email de livraison est envoyé pour une commande. Cela se produit automatiquement après l'achat pour les produits de livraison RÉGULIERS et PLANIFIÉS, ou lorsque vous envoyez ou renvoyez manuellement l'email. Utilisez ceci pour confirmer que le client a bien reçu son lien de téléchargement.
file.downloaded se déclenche la première fois qu'un client télécharge un fichier spécifique de sa commande. Utilisez ceci pour l'analytique, pour déclencher des emails d'intégration, ou pour enregistrer des événements d'accès dans votre système.
file.redownloaded se déclenche lorsqu'un client télécharge un fichier qu'il a déjà téléchargé auparavant. Utilisez ceci pour détecter des modèles de téléchargement inhabituels ou pour suivre l'engagement avec votre contenu.
Vérifiez la signature du webhook
Chaque requête de webhook est signée afin que vous puissiez confirmer qu'elle provient réellement de Big Digital Downloads et qu'elle n'a pas été altérée. Le processus de vérification utilise le même modèle que les webhooks Cowlendar : HMAC-SHA256 avec le secret de signature, calculé sur timestamp + "." + raw_body.
Vérifiez les en-têtes de la requête :
X-Webhook-Signature contient la signature HMAC.
X-Webhook-Timestamp contient le timestamp Unix.
Avertissement
Calculez toujours la signature sur le corps brut de la requête, les octets exacts que le serveur a envoyés, et non un objet JSON analysé et re-sérialisé. L'analyse et la re-sérialisation peuvent modifier les espaces ou l'ordre des clés, ce qui casse la signature.
Rejetez les requêtes avec un timestamp plus ancien que 5 minutes pour prévenir les attaques par rejeu.
Node.js (Express) :
import crypto from "crypto";
import express from "express";
const app = express();
app.post(
"/webhooks/bigdd",
express.raw({ type: "application/json" }),
(req, res) => {
const signature =
req.header("X-Webhook-Signature") || "";
const timestamp =
req.header("X-Webhook-Timestamp") || "";
const rawBody = req.body.toString("utf8");
// Rejetez les requêtes plus anciennes que 5 minutes
if (
Math.abs(Date.now() / 1000 - parseInt(timestamp, 10))
> 300
) {
return res.status(400).send("Timestamp trop ancien");
}
const expected = crypto
.createHmac(
"sha256",
process.env.BIGDD_WEBHOOK_SECRET
)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
if (
!crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature)
)
) {
return res.status(401).send("Signature invalide");
}
const event = JSON.parse(rawBody);
// Gérez l'événement en fonction de event.type
res.status(200).send("ok");
}
);
Python (Flask) :
import hmac, hashlib, os, time, json
from flask import Flask, request
app = Flask(__name__)
@app.post("/webhooks/bigdd")
def bigdd_webhook():
signature = request.headers.get(
"X-Webhook-Signature", ""
)
timestamp = request.headers.get(
"X-Webhook-Timestamp", ""
)
raw_body = request.get_data(as_text=True)
if abs(time.time() - int(timestamp)) > 300:
return "Timestamp trop ancien", 400
expected = hmac.new(
os.environ["BIGDD_WEBHOOK_SECRET"].encode(),
f"{timestamp}.{raw_body}".encode(),
hashlib.sha256,
).hexdigest()
if not hmac.compare_digest(expected, signature):
return "Signature invalide", 401
event = json.loads(raw_body)
# Gérez l'événement en fonction de event["type"]
return "ok", 200
PHP :
<?php
$secret = getenv("BIGDD_WEBHOOK_SECRET");
$rawBody = file_get_contents("php://input");
$signature = $_SERVER["HTTP_X_WEBHOOK_SIGNATURE"] ?? "";
$timestamp = $_SERVER["HTTP_X_WEBHOOK_TIMESTAMP"] ?? "";
if (abs(time() - (int)$timestamp) > 300) {
http_response_code(400);
exit("Timestamp trop ancien");
}
$expected = hash_hmac(
"sha256",
$timestamp . "." . $rawBody,
$secret
);
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit("Signature invalide");
}
$event = json_decode($rawBody, true);
// Gérez l'événement en fonction de $event["type"]
http_response_code(200);
echo "ok";
Testez votre webhook avant de passer en production
Chaque point de terminaison de webhook a un bouton Test dans l'admin. En cliquant dessus, un événement de test est envoyé à votre URL en utilisant la même signature et les mêmes en-têtes que les événements réels. Utilisez ceci pour confirmer que votre serveur peut recevoir des événements, que les paramètres HTTPS et de pare-feu sont corrects, et que votre code de vérification de signature fonctionne.
Après avoir cliqué sur Test, vérifiez le bouton Voir les livraisons pour voir le code d'état HTTP que votre point de terminaison a renvoyé.
Meilleures pratiques pour les webhooks
Répondez dans les 10 secondes. Si votre gestionnaire doit effectuer un travail lourd comme appeler une autre API ou écrire dans une base de données, acceptez immédiatement le webhook avec 200, puis traitez-le dans un travail en arrière-plan.
Dédupliquez les événements. Stockez chaque ID d'événement que vous traitez. Si vous recevez le même ID à nouveau lors d'une nouvelle tentative, passez-le.
Utilisez une comparaison en temps constant pour les signatures. crypto.timingSafeEqual dans Node.js, hmac.compare_digest en Python, et hash_equals en PHP.
Limitations actuelles
Les commandes sont créées via le processus de paiement Shopify, pas l'API. L'API fournit un accès en lecture et une gestion post-achat (renvoyer des e-mails, basculer l'accès, réinitialiser les compteurs), mais ne peut pas créer de nouvelles commandes.
Les produits numériques ne peuvent être que partiellement mis à jour. Vous pouvez changer les limites de téléchargement et l'expiration des liens via l'API. Tous les autres paramètres du produit (nom, fichiers, type de livraison, mode d'accès) sont gérés depuis l'admin.
Les clés de licence ne peuvent pas être modifiées après leur création. La chaîne de clé elle-même est immuable. Si vous devez changer une valeur de clé, supprimez l'ancienne et créez-en une nouvelle.
Les liens de téléchargement ne peuvent pas être listés, modifiés ou supprimés après leur création. Conservez l'URL lorsque vous la créez.
Les téléchargements de fichiers sont limités à 25 Mo et 6 par minute. Pour des fichiers plus volumineux, téléchargez-les via l'interface admin qui prend en charge des tailles plus importantes.
Les fichiers ne peuvent pas être téléchargés via l'API. L'API gère votre bibliothèque de fichiers (liste, téléchargement, suppression), mais ne fournit pas d'URL de téléchargement directes. Les fichiers sont livrés aux clients via des e-mails de commande et des pages de téléchargement.
Des limites de taux s'appliquent. Si vous envoyez trop de requêtes dans une courte période, l'API renvoie 429. Pour des opérations en masse comme l'exportation de toutes les commandes, ajoutez un court délai entre les requêtes paginées, par exemple de 200 à 500 ms.
Les secrets de webhook ne sont affichés qu'une seule fois. Si vous perdez votre secret de signature, supprimez le point de terminaison et créez-en un nouveau pour obtenir un nouveau secret.
Les webhooks nécessitent HTTPS. Les points de terminaison HTTP ne sont pas acceptés.
FAQ
Puis-je utiliser l'API avec Zapier ou Make sans écrire de code ?Oui. Pour les webhooks (recevoir des événements de Big DD), créez un déclencheur "Custom Webhook" dans Zapier ou Make, copiez l'URL qu'ils vous donnent et ajoutez-la comme point de terminaison dans Big DD Settings > Webhooks. Pour l'API (envoyer des requêtes à Big DD), utilisez l'action "HTTP Request" avec votre token Bearer pour appeler n'importe quel point de terminaison.
Puis-je construire un système de validation de licence avec l'API ?Oui. C'est l'une des fonctionnalités les plus puissantes. Votre logiciel appelle GET /license-keys/validate?key=XXXXX au lancement. La réponse vous indique si la clé existe (valid) et si elle est assignée à une commande (assigned). Les deux doivent être true pour une licence légitime. Aucun service de licence tiers n'est nécessaire.
Big DD réessaie automatiquement les livraisons échouées. Après plusieurs échecs consécutifs, le point de terminaison peut être désactivé. Vous pouvez le réactiver depuis Settings > Webhooks une fois que votre serveur est de nouveau opérationnel.
Puis-je avoir plusieurs points de terminaison webhook ?Oui. Créez autant que vous en avez besoin, chacun avec des sélections d'événements et des URL différentes.
Puis-je révoquer un token API ?Oui. Allez dans Settings > Public API et cliquez sur le bouton Revoke à côté du token. Il cesse de fonctionner immédiatement.
Où se trouve la référence API complète ?La documentation API interactive avec tous les schémas, paramètres et exemples de réponses est disponible à https://islandcloud.co/public-api/docs
Cette réponse a-t-elle résolu votre question ?