Comment commander des forfaits avec l'API

Tu crées des sites web pour tes clients ? Tu peux alors commander leur hébergement web via l'API Site.fr. Ton script paie avec ton portefeuille, et la commande démarre tout de suite.

Avec l'API, tu peux commander un nouveau forfait, renouveler un forfait et restaurer un forfait. Chaque appel correspond à une commande pour un seul forfait. Tu veux aussi commander des noms de domaine ? Découvre comment commander des noms de domaine avec l'API. Tu débutes avec notre API ? Lis d'abord comment démarrer avec l'API.

Ce dont tu as besoin

Une clé API. Crée-en une dans ton tableau de bord sous Paramètres, dans l'onglet Clés API. Coche uniquement les autorisations dont tu as besoin, sous Points de terminaison API :

• plans.order.create : commander, renouveler et restaurer des forfaits.
• domains.view : retrouver les ID de tes forfaits et de tes noms de domaine.

De l'argent dans ton portefeuille. Les commandes passées par l'API sont toujours payées avec ton portefeuille en ligne. Le solde doit couvrir toute la commande, TVA comprise.

Les commandes ne fonctionnent qu'avec une clé API. Dans ton navigateur, tu utilises simplement le panier.

Comment fonctionne une commande

Tu envoies une requête POST à l'API. Mets ta clé API dans l'en-tête X-API-Key, et les détails de la commande en JSON dans le corps de la requête. Par exemple, pour commander un nouveau forfait :

POST https://backend.site.fr/v2/plans/order
X-API-Key: your API key
Content-Type: application/json

Dans le corps, tu envoies au moins plan_name, par exemple starter. Voici ce qui se passe ensuite :

• Même prix. Tu paies le même prix que pour une commande sur notre site.
• Rien n'est débité en cas de problème. Tu reçois un code d'erreur qui explique pourquoi.
• Teste d'abord. Envoie dry_run: true. La réponse indique le prix, la TVA et si le solde de ton portefeuille suffit. Rien n'est commandé ni débité.
• Nous lançons la commande en une minute environ. Ensuite, elle se déroule comme n'importe quelle autre commande, avec les mêmes e-mails.
• Elle figure sur ta facture mensuelle, avec la mention « Via API ». C'est aussi le cas quand la facturation mensuelle est désactivée.

La documentation de l'API décrit chaque champ et donne des exemples de chaque requête et de chaque réponse.

Commander un nouveau forfait

POST https://backend.site.fr/v2/plans/order

Tu peux envoyer ces champs :

• plan_name (obligatoire) : le nom du forfait en minuscules, comme starter ou power.
• order_period : le nombre d'années, de 1 à 5. La valeur par défaut est 1.
• domain_name_ids : les ID des noms de domaine que tu as déjà chez nous, à placer dans le nouveau forfait. Tu les trouves avec GET /v2/domain_names.
• external_domain_name_ids : les ID des noms de domaine enregistrés ailleurs, mais que tu as ajoutés à ton compte. Tu les trouves avec GET /v2/external_domain_names.
• expected_price : le prix en centimes, hors TVA, que tu acceptes. Le prix est différent ? Nous ne passons alors pas la commande.
• dry_run : true vérifie seulement la commande et en calcule le prix.

Les noms de domaine doivent être actifs, et ils ne peuvent pas déjà se trouver dans un autre forfait. De plus, chaque forfait accepte un nombre maximum de noms de domaine. Tu as besoin d'un nouveau nom de domaine pour le forfait ? Commande-le d'abord, et attends qu'il soit actif.

Renouveler ou restaurer un forfait

POST https://backend.site.fr/v2/plans/91/renew
POST https://backend.site.fr/v2/plans/91/restore

Ici, 91 est l'ID du forfait. Tu le trouves avec GET /v2/plans. Dans le corps, tu peux envoyer order_period (en années), expected_price et dry_run.

• Renouveler : pour un forfait actif. Découvre comment fonctionne le renouvellement d'un forfait.
• Restaurer : pour un forfait qui a expiré ou qui a été annulé, jusqu'à 14 jours après son expiration.

Le forfait est en train d'être déplacé vers un autre utilisateur ? Tu ne peux alors pas le renouveler avant la fin du déplacement.

La réponse

La commande est passée ? Tu reçois alors son order_id, avec order_status paid. Tu reçois aussi les prix en centimes : amount_excluding_vat_in_cents, vat_amount_in_cents et total_including_vat_in_cents. Sous payment, wallet_balance_in_cents indique ce qu'il reste dans ton portefeuille.

Suis la commande grâce à son ID :

GET https://backend.site.fr/v2/orders/5926

Chaque ligne de la commande a un statut : unprocessed, processing, processed, failed ou cancelled.

Ne paie jamais deux fois

Il arrive que la connexion se coupe juste après l'envoi d'une commande. Est-elle passée ou non ? Pour être tranquille, envoie un en-tête Idempotency-Key avec chaque commande. C'est un code unique de 255 caractères maximum, comme un UUID.

Tu renvoies la même commande avec la même clé ? Tu reçois alors la première réponse, et rien n'est jamais débité deux fois. Si tu utilises la clé pour une autre commande, tu reçois l'erreur ORDER_005.

Codes d'erreur

Quelle que soit l'erreur, rien n'est débité. Voici les codes les plus fréquents :

• ORDER_001 : le solde de ton portefeuille est insuffisant. Sous top_up, la réponse indique le montant à ajouter et un lien pour recharger ton portefeuille.
• ORDER_002 : le prix ne correspond pas à ton expected_price. La réponse contient le prix actuel.
• ORDER_003 : cette commande n'est pas possible. Le champ reason explique pourquoi. Par exemple : le forfait ne peut pas contenir autant de noms de domaine, un nom de domaine se trouve déjà dans un forfait, ou la période de restauration est terminée.
• ORDER_004 : le paiement par portefeuille n'est pas possible pour ton compte.
• ORDER_005 : tu as déjà utilisé cette Idempotency-Key pour une autre commande.
• GENERAL_001 : il n'existe pas de forfait avec ce nom, ou le forfait avec cet ID ne t'appartient pas.
• DOMAIN_NOT_FOUND : l'un des ID ne correspond à aucun de tes noms de domaine.

Bon à savoir

• Il n'y a pas d'environnement de test. Chaque commande est réelle. Teste donc d'abord avec dry_run.

Besoin d'aide ? Contacte-nous par WhatsApp, Telegram ou e-mail.