Interface API de ClickBank

Veuillez noter que l'interface API de ClickBank est destinée aux personnes très expérimentées en matière de développement.

Grâce à l'interface API de ClickBank, un nombre important de programmes informatiques peuvent accéder en toute sécurité aux informations des comptes ClickBank pour le compte de leurs propriétaires respectifs. Sur l'interface API, les utilisateurs peuvent notamment effectuer les opérations suivantes :

• demander le remboursement d'un achat effectué par un client ;
• demander l'annulation de la souscription d'un client ;
• récupérer une liste de transactions d'un compte ClickBank pour une période donnée.

De nombreux programmes peuvent utiliser l'interface API de ClickBank, notamment un tableau de bord comportant les données ClickBank et les données des comptes associés à d'autres services en ligne, un outil de gestion des souscriptions et un ensemble d'outils analytiques indiquant les tendances de ventes d'un compte ClickBank donné. Grâce à la nouvelle interface API de ClickBank, vous pouvez utiliser toutes ces applications et d'autres encore. Vous avez également la possibilité de les vendre sur la Place de marché ClickBank.

L'interface API de service de ClickBank repose sur une architecture REST et fournit un mécanisme http fiable et sécurisé pour la récupération de données.

REST

REST est un style d'architecture conçu par Roy Fielding (l'un des principaux créateurs du protocole http) qu'il décrit dans sa thèse intitulée « Architectural Styles and the Design of Network-based Software Architectures» (Styles d'architecture et conception d'architectures logicielles en fonction du réseau). L'article de Wikipédia Representational State Transfer présente une brève introduction de l'architecture REST.

Gestion des versions

La version actuelle de l'interface API de service de ClickBank est : 1.3.

Les informations sur la version sont contenues dans l'URL d'accès aux services. Cela présente les avantages suivants :

• Les informations relatives à la version de l'interface API utilisée sont limpides.
• Vous pouvez facilement comprendre la méthode de mise à niveau lors de la publication des nouvelles versions de l'interface API.

L'interface de service API de ClickBank est garantie d'être compatible avec trois versions antérieures. Ainsi, lorsque la version 4.0 de l'interface API est publiée, la version 1.3 reste fonctionnelle.

Infrastructure

L'interface API REST de ClickBank est basée sur JSR-311, l'interface API Java des services Web RESTful. Il s'agit d'un détail de l'implémentation de l'interface API de service de ClickBank. Les services eux-mêmes sont basés sur le protocole HTTP et indépendants de l'implémentation. Tous les clients Web (NET, PHP, Java, Python, Ruby, etc.) peuvent par conséquent les utiliser.

Bien que ClickBank ne cautionne aucun des outils de développement REST, nous avons constaté que RestClient est très utile lors du développement et des tests des services Web RESTful.

En-tête de la demande

L'en-tête de l'interface API de service de ClickBank est constitué de paramètres de sécurité, de sortie et de page. L'interface API de service de ClickBank accepte uniquement les paramètres de la requête ; les requêtes basées sur des formulaires de base (post) des paramètres sont ignorées.

La spécification HTTP indique que la longueur d'une URL ne peut pas dépasser 2 Ko. Les développeurs de l'interface API doivent s'assurer que l'URL de l'interface API REST comporte au maximum 2 000 caractères.

Certification

Avec certains langages de programmation, l'interface API de service de ClickBank exige la présence d'un certificat associé au domaine suivant sur le système :

*.clickbank.com

Pour obtenir le certificat, il vous suffit d'accéder à l'URL suivante, de cliquer deux fois sur le verrou d'authentification situé dans le coin inférieur droit du navigateur et d'enregistrer le certificat sur votre système.

https://api.clickbank.com/rest/1.3/orders

Sécurité

Les méthodes utilisées par l'interface API de service de ClickBank sont sécurisées et renvoient un code de statut 403 [Interdit] pour tout accès non vérifié. L'accès sécurisé à l'interface API requiert un paramètre d'en-tête Autorisation contenant les clés suivantes :

• la clé des développeurs qui permet d'attribuer le rôle « ROLE_HAS_DEVELOPER_KEY » à l'utilisateur ;
• la clé des employés qui permet d'attribuer le rôle « ROLE_API_ORDER_READ » ou « ROLE_API_ORDER_WRITE » à l'utilisateur.

D'un point de vue conceptuel, une clé de développeur est un jeton généralement utilisé pour autoriser l'accès aux interfaces API, tandis que la clé de l'interface API d'un employé est généralement associée à un utilisateur spécifique. Lorsque vous créez le paramètre d'en-tête à l'aide des deux rôles, vous devez séparer chaque valeur par deux points.

Exemple :

Certaines interfaces API de service de ClickBank (notamment le sandbox) ne requièrent pas les deux clés. La documentation relative à l'interface API prise en charge répertorie les rôles requis pour accéder à un service spécifique. Si l'interface API requiert uniquement la clé des développeurs, il n'est pas nécessaire d'insérer les deux points dans le paramètre d'en-tête.

Exemple :

Pour obtenir les clés des développeurs et des employés, il vous suffit d'ouvrir une session de votre compte ClickBank et d'accéder à l'onglet Paramètres du compte. Cliquez ensuite sur « éditer » dans les zones relatives à la clé de l'interface API du développeur et de l'employé.

Chaque clé doit être approuvée, présente et active pour réussir l'authentification.

Sortie

L'interface API de service de ClickBank prend en charge les formats de sortie suivants :

• XML
• JSON
• CSV (compatible uniquement avec l'interface API des commandes)

Pour demander le format de sortie, insérez un paramètre Accepter dans l'en-tête http. Si vous demandez un format non pris en charge, le serveur renvoie un code de statut 500 [Erreur interne du serveur].

Exemple :

Pagination

L'interface API ne renvoie jamais plus de 100 lignes pour tout appel de service. Pour les requêtes contenant plus de 100 lignes de données, l'interface API renvoie les 100 premières lignes avec un code de statut 206 [Contenu partiel]. Pour récupérer les pages supplémentaires, le développeur doit insérer un paramètre d'en-tête Page indiquant la page du résultat souhaitée.

Exemple :

Lorsque vous accédez à la dernière page, le service renvoie un code de statut 200 [OK] au lieu d'un code de statut 206 [Contenu partiel].

Interfaces API prises en charge

Pour la version 1.3, les interfaces API suivantes sont prises en charge :

• Interface API Analytics : https://api.clickbank.com/rest/1.3/analytics
  • Cette interface vous permet d'accéder aux informations sur les abonnements et les statistiques données, compte tenu de certaines autorisations de compte.
• Interface API images : https://api.clickbank.com/rest/1.3/images
  • Cette interface vous permet d'accéder à l'API du produit, celui-ci présentant des images associées à un site.
• Interface API Commandes : https://api.clickbank.com/rest/1.3/orders2
  • Cette interface vous permet d'accéder à des informations sur la commande à l'aide des paramètres de n° de reçu ou de date/heure.
• Interface API Produits : https://api.clickbank.com/rest/1.3/products
  • Cette interface vous permet les opérations de gestion des produits CRUD au complet. 
• Interface API Livraison : https://api.clickbank.com/rest/1.3/shipping2
  • Cette interface vous permet d'accéder aux informations de livraison pour une ou plusieurs commandes de biens physiques à l'aide des paramètres de n° de reçu ou de date/heure.
• Interface API Tickets : https://api.clickbank.com/rest/1.3/tickets
  • Cette interface vous permet de mettre à jour le statut d'une commande en « remboursée » ou « annulée » via la création d'un ticket de transaction. Vous pouvez par ailleurs rechercher les tickets existants par utilisateur.
• Interface API Notification d'envoi : https://api.clickbank.com/rest/1.3/shipping2/shipnotice
  • Cette interface est le petit de l'API de livraison et vous permet de générer des notifications d'envoi.
• Interface API Stats rapide : https://api.clickbank.com/rest/1.3/quickstats
  • Cette interface vous fournit des statistiques concernant le compte de l'utilisateur.

Les interfaces API de ClickBank sont auto-descriptives. Pour obtenir des détails sur la description du service, il vous suffit d'accéder à l'URL de l'interface API.

Outils supplémentaires

Débogage

L'interface API de ClickBank propose un service Web de débogage [/rest/1.3/debug]. Ce service imprime les informations relatives à la demande [notamment celles relatives à la sécurité] pouvant être nécessaires à la résolution des problèmes liés à l'interface API REST.

Exemples de code

Les exemples de code suivants indiquent comment un développeur peut utiliser les interfaces API :

• C# – https://api.clickbank.com/api/api_13_examples/api_example.csharp
• Java – https://api.clickbank.com/api/api_13_examples/api_example.java
• PHP – https://api.clickbank.com/api/api_13_examples/api_example.php
• Python – https://api.clickbank.com/api/api_13_examples/api_example.py
• Ruby – https://api.clickbank.com/api/api_13_examples/api_example.rb