Utilisation manuelle de l'API avec Postman

Si vous ne souhaitez pas intégrer notre API dans vos systèmes déjà construis, ou si votre système ne le permet pas, utilisez ce guide qui vous aidera à envoyer des requêtes à l'API à l'aide de Postman. Grâce à l'appli Postman, vous disposez d'une interface pour l'envoi de requêtes et de fonctions préconfigurées par nos spécialistes. En bref, vous n'avez pas besoin d'avoir les connaissances particulières en programmation pour utiliser l'API de SSLmarket, sans parler du temps que vous gagnez.

L'intégration de l'API SSLmarket dans d'autres environnements permet d'implémenter des solutions de manière complète. La solution décrite ne peut pas fonctionner automatiquement, elle est manuelle, mais au moins elle vous fera gagner du temps.

Installer l'application Postman

Postman est disponible en tant qu'application de bureau pour les systèmes d'exploitation Mac, Windows et Linux, et en version web. Téléchargez la version desktop, la version web n'est pas adaptée à notre objectif (ne fonctionne pas).

Pour installer Postman sous Windows, double-cliquez sur le fichier .exe. Le Postman pour Linux est disponible sous forme de package snap. Utilisez la commande :

sudo snap install postman
Lancez l'application. L'application vous demande de vous connecter ou de créer un compte utilisateur ; cela peut être ignoré grâce à un lien discret tout en bas de la fenêtre. La connexion au compte Postman permet de synchroniser des projets entre les instances. Vous pouvez facilement continuer votre travail à la maison. Si vous ne souhaitez pas utiliser de compte et la synchronisation, ou si vous tester l'API, vous n'avez pas besoin de vous connecter.

Paramétrer l'application pour SSLmarket

Pour vous simplifier votre travail avec le programme, nous avons préparé un fichier JSON contenant une "collection" d'appels, dont vous avez besoin. Vous n'avez qu'à importer le fichier et ensuite, toutes les fonctions seront immédiatement disponibles. Cliquez sur Import (bouton "import" en haut à gauche), et sélectionnez le fichier JSON. Dans Collections, vous avez l'élément SSLmarket et dix fonctions. En utilisant le bouton droit de votre souris, cliquez sur la collection SSLmarket et définissez les variables dans "Edition → Variables".

Editer les variables
Editer les variables pour la Collection. Cliquez pour agrandir.

Faites attention à la variable X-Auth-Token : utilisez la valeur de votre compte client. Les autres variables ne sont pas compliquées à renseigner. Voir la liste ci-dessous.

Comprendre les principales variables

  • X-Auth-Token – saisissez la clé API
  • owner_### - coordonnées du futur propriétaire du certificat
  • auth_### - coordonnées du contact d'autorisation qui confirme la commande des certificats et représente l'organisation lors du processus de vérification
  • tech_### - coordonnées du contact technique. Il n'entre pas dans le processus de vérification, il reçoit le certificat par e-mail
  • invoice_### - spécifie les données de facturation ; les informations sur le client facturé.
Les variables de collection remplies
Les variables de collection remplies. Cliquez pour agrandir.

Ces informations seront proposées dans les variables (par exemple, lors de la commande) et vous n'aurez pas à les saisir à nouveau. Si l'un des champs n'est pas clair pour vous, veuillez consulter la documentation API.

Une fois la configuration terminée, vous pouvez commencer à envoyer des requêtes à l'API SSLmarket.

Envoi des requêtes

Vous pouvez commencer à envoyer des requêtes et des nouvelles commandes. La demande CSR doit être sans interlignes et espaces. Pour le résoudre, vous pouvez utiliser des séquences d'échappement (voir le paragraphe suivant).

Dans la Collection, sélectionnez la fonctionnalité API que vous souhaitez utiliser. Ensuite, dans la partie droite, dans l'onglet Body, vous trouverez tout ce qui constitue une requête. Par exemple, pour une nouvelle commande, vous y trouverez toutes les informations sur le futur certificat (exactement comme pour une commande en ligne). Les informations entre parenthèses signifient que la variable que vous avez définie précédemment sera utilisée - par exemple {{owner_name}}. Ne modifiez ces éléments que si vous allez utiliser des données différentes que celles par défaut.

Informations de commande

Les informations relatives au demandeur (au contact) seront chargées à partir des informations préremplies. Ensuite, pour chaque commande, vous devez spécifiez les données suivantes :

  • domain - Common name du certificat
  • dns_names - Liste des noms supplémentaires protégés par le certificat
  • years - Nombre d'années de validité de la commande (la validité du certificat est limitée, mais la commande peut durer plus d'années)
  • csr - Insérez la Demande de signature de certificat (CSR) (cela doit être sans interlignes et espaces, voir ci-dessous). Ce champ est facultatif ; la CSR peut être saisie plus tard.
  • dv_auth_method - choix de la méthode d'authentification DCV (email, dns, ftp)

Si vous avez rempli tous les champs et la demande est prête, envoyez-la à l'API en cliquant sur le bouton bleu Send.

La progression et le résultat de la requête s'affiche en bas de la fenêtre. Si votre requête a été traitée avec succès, vous allez recevoir les informations requises ou le numéro de commande. Dans le cas contraire, vous obtenez un message d'erreur indiquant ce qui est incorrect ou manquant dans la requête.

Exemple de commande réussie :

{
    "order_id": "155252"
}

Exemple de message d'erreur :

   {
    "error": [
        "dv_auth_method => isEmpty - Champ obligatoire"
    ]
}

Collisions possibles lors de l'envoi de commandes

  • URL utilisé – utilisez l'URL www.sslmarket.tld, non seulement sslmarket.tld. Les redirections sur le domaine principal produisent des problèmes avec les requêtes.
  • CSR request - Assurez-vous que le texte de CSR n'est pas divisé en plusieurs lignes. Si vous ne réussissez pas, envoyez la commande sans avoir rempli la CSR et collez-la plus tard via votre espace client.
    • La CSR ne peut pas être divisé en lignes, même si vous l'obtenez de votre serveur de cette façon.
    • Dans la CSR, il ne doit y avoir aucun espace, saut de ligne ou saut de paragraphe ; terminez les lignes avec "Séquences d'échappement" rn.
    • En utilisant l'outil "Remove or replace line breaks", vous pouvez facilement ajuster la CSR à la forme appropriée. Sélectionnez l'option "Replace line breaks with customer text" et entrez "rn" comme custom text. Supprimez les autres options et cliquez sur le bouton vert dessous.

FAQ pour l'utilisation manuelle de l'API

Pas du point de vue des fonctions disponibles, les deux approches portent les mêmes résultats. L'utilisation de l'API SSLmarket avec Postman vous fera économiser du temps et de l'argent liés à l'intégration de l'API dans votre système, mais vous devez exécuter les actions manuellement (ce qui est le seul inconvénient de cette approche). Vous ne pouvez pas automatiser la commande ou le renouvellement des certificats, pour cela aurez besoin de votre propre solution avec l'implémentation de notre API.

Vous retrouverez toutes les commandes sur votre compte client, exactement comme avec la commande habituelle via le site web. Votre requête identifie la clé API générée pour votre compte.

Les commandes sont facturées de la même façon comme les commandes saisies en ligne.