Comment commander des noms de domaine avec l'API

Tu gères beaucoup de noms de domaine ? Ou tu les revends à tes propres clients ? Tu peux alors les commander via l'API Site.fr. Ton script paie avec ton portefeuille, et la commande démarre tout de suite.

Avec l'API, tu peux enregistrer, transférer, renouveler et restaurer des noms de domaine. Chaque appel correspond à une commande pour un seul nom de domaine. Tu veux commander de l'hébergement web ? Découvre comment commander des forfaits 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 :

• domains.order.create : commander des noms de domaine (enregistrement, transfert, renouvellement et restauration).
• domains.view : retrouver les ID de tes noms de domaine, et le prix d'un nom de domaine premium.
• contacts.required_info : uniquement si tu envoies des informations supplémentaires sur le titulaire du domaine avec une commande.

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 enregistrer un nom de domaine :

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

Dans le corps, tu envoies au moins domain_name, par exemple example.nl. 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.

Enregistrer ou transférer un nom de domaine

POST https://backend.site.fr/v2/domain_names/register
POST https://backend.site.fr/v2/domain_names/transfer

Tu peux envoyer ces champs :

• domain_name (obligatoire) : le nom de domaine complet, comme example.nl.
• auth_key (transferts uniquement) : la clé de transfert de ton fournisseur actuel. Découvre comment demander la clé de transfert.
• order_period : de 1 à 5 périodes. La valeur par défaut est 1. Une période correspond à la durée d'enregistrement la plus courte de l'extension, généralement 1 an.
• contact_id : le contact qui devient titulaire du domaine. Sans ce champ, nous utilisons ton contact par défaut.
• name_servers : une liste de 2 à 8 serveurs de noms. Sans ce champ, le nom de domaine reçoit tes serveurs de noms par défaut.
• privacy_protection : true masque le titulaire du domaine dans le WHOIS, si l'extension le permet.
• expected_price : le prix en centimes, hors TVA, que tu acceptes. Tu en as besoin pour les noms de domaine premium.
• dry_run : true vérifie seulement la commande et en calcule le prix.

Tu ne sais pas si le nom de domaine est encore libre ? Vérifie-le d'abord. Tu n'as pas besoin de clé API pour ça :

GET https://backend.site.fr/v2/domain_names/check_availability?domain_name=example.nl

La réponse indique premium: true ? Demande alors son prix avec GET /v2/domain_names/premium_quote. Envoie ce prix comme expected_price avec ta commande.

Le transfert lui-même peut prendre quelques jours. Il a échoué ? Découvre alors que faire quand le transfert de ton domaine a échoué.

Renouveler ou restaurer un nom de domaine

POST https://backend.site.fr/v2/domain_names/6731/renew
POST https://backend.site.fr/v2/domain_names/6731/restore

Ici, 6731 est l'ID du nom de domaine. Tu le trouves avec GET /v2/domain_names. Dans le corps, tu peux envoyer order_period, expected_price et dry_run.

• Renouveler : pour un nom de domaine actif. Un nom de domaine premium ne peut être renouvelé que pendant la dernière année avant son expiration.
• Restaurer : pour un nom de domaine qui a expiré, tant qu'il est encore dans sa période de restauration. Cette période varie selon l'extension.

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/5925

Chaque ligne de la commande a un statut : unprocessed, processing, processed, awaiting_required_info, transfer_failed, 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.

Faut-il des informations supplémentaires sur le titulaire ?

Certaines extensions, comme .es et .it, demandent des informations supplémentaires sur le titulaire du domaine. Un numéro d'identification, par exemple. Le contact n'est pas encore prêt pour l'extension ? La commande s'arrête alors avec ORDER_003 et la raison contact_required_info. Rien n'est débité. Sous required_info, la réponse indique les champs qu'il te reste à fournir.

Tu peux envoyer ces informations avec la commande, dans required_info. Ou tu prépares d'abord le contact. Découvre comment créer un contact et le préparer avec l'API.

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.
• 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.
• DOMAIN_NOT_AVAILABLE : le nom de domaine est déjà pris (enregistrement), n'est pas enregistré (transfert) ou est déjà chez nous.
• REG_001 : nous n'avons pas pu joindre le registre. Réessaie un peu plus tard.

Bon à savoir

• Il n'y a pas d'environnement de test. Chaque commande est réelle. Teste donc d'abord avec dry_run.
• Un enregistrement attend des informations sur le titulaire, ou un transfert a échoué ? Tu peux alors annuler cette ligne avec PATCH /v2/domain_name_orders/22455/cancel. Ici, 22455 est l'ID de la ligne dans la commande. Ta clé API a besoin de l'autorisation domains.order.cancel. Nous remettons l'argent dans ton portefeuille.

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