Commander un nom de domaine
Utilisez l'API publique OVHcloud pour commander vos noms de domaines
Utilisez l'API publique OVHcloud pour commander vos noms de domaines
Dernière mise à jour le 05/05/2022
Pour suivre ce guide, vous devez déjà vous connecter à l'API OVHcloud. Vous trouverez plus de détails sur la page d'introduction à l'API.
Afin de commander vos noms de domaine, voici une présentation des différents objets que vous allez devoir manipuler au travers de l'API.
L'objet cart de l'API représente ce panier. Différentes actions sont disponibles :
Les APIs concernées commencent par /order/cart/
Un item représente un produit qui peut être ajouté dans un panier. Il est possible de :
Ces APIs commencent par /order/cart/{cartId}/item/
Globalement, la commande d'un produit OVHcloud via l'API se fera toujours à travers ces étapes :
La première étape de commande d'un nom de domaine est la création du panier avec l'API suivante :
Paramètre | Obligatoire | Défaut | Description |
---|---|---|---|
ovhSubsidiary | oui | Filiale OVHcloud | |
description | non | "" | Description personnalisée du panier |
expire | non | maintenant + 1 jour | Expiration du panier |
{
"cartId": "c87b5e9d-f586-4456-9f56-1709f40e7b1d",
"description": "",
"expire": "2020-10-18T13:44:30+00:00",
"readOnly": false,
"items": []
}
Notez bien la propriété cartId
, elle nous servira tout au long des étapes suivantes.
La seconde étape consiste à récupérer les offres accessibles pour un domaine.
Paramètre | Obligatoire | Défaut | Description |
---|---|---|---|
domain | oui | "" | Le nom de domaine souhaité |
[
{
"action": "create", // 1
"configurations": [],
"deliveryTime": "",
"duration": [
"P1Y", // 2
"P2Y",
"P3Y",
"P4Y",
"P5Y",
"P6Y",
"P7Y",
"P8Y",
"P9Y",
"P10Y"
],
"offer": "gold",
"offerId": "fr-create", // 3
"orderable": true,
"phase": "ga",
"prices": [
{
"label": "PRICE",
"price": {
"currencyCode": "EUR",
"text": "6.99 €",
"value": 6.99
}
},
{
"label": "RENEW",
"price": {
"currencyCode": "EUR",
"text": "6.99 €",
"value": 6.99
}
},
{
"label": "DISCOUNT",
"price": {
"currencyCode": "EUR",
"text": "2.00 €",
"value": 2
}
},
{
"label": "FEE",
"price": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
}
},
{
"label": "TOTAL",
"price": {
"currencyCode": "EUR",
"text": "4.99 €",
"value": 4.99
}
}
],
"pricingMode": "default", // 4
"productId": "domain",
"quantityMax": 1
}
]
Il y a 4 valeurs à retenir ici :
action
: celle réalisable sur le domaine, ça peut être un create
ou un transfer
duration
: ce champ représente l'unité de période sur laquelle il est possible de commander le domaine, au format ISO 8601. Pour un domaine, P1Y (Period 1 Year) équivaut à une période d'un an, P2Y une période de deux ans, etc.offerId
: c'est le nom de l'offre qu'il faudra mettre lors de l'ajout du domaine dans le panierpricing-mode
: c'est le détail de l'offre qu'il faudra également mettre lors de l'ajout du domaine dans le panierPour déterminer le statut du domaine, on utilise la table de correspondance suivante, en fonction du pricing-mode.
Pricing-mode | Description |
---|---|
create-default |
Le domaine est libre et au prix standard |
create-premium |
Le domaine est libre mais est un premium. Son prix est variable d'un domaine à l'autre |
transfer-default |
Le domaine n'est pas libre mais est transférable si vous en êtes le propriétaire. Son transfert est au prix standard |
transfer-premium |
Le domaine n'est pas libre mais est transférable si vous en êtes le propriétaire. C'est un domaine premium et son prix est variable d'un domaine à l'autre |
transfer-aftermarket1 , transfer-aftermarket2 |
Le domaine est libre via un marché secondaire. Son prix est variable d'un domaine à l'autre |
Pour le moment, bien que le retour soit un tableau, seulement une offre à la fois est disponible. Dans le futur, il est possible que d'autres offres soient disponibles pour un même domaine. Un domaine pourrait être à la fois transférable depuis un autre registrar ou bien disponible via un marché secondaire.
Tandis que la deuxième étape est optionnelle, celle-ci est obligatoire pour la commande d'un nom de domaine. L'appel suivant permet en effet d'ajouter le domaine désiré dans le panier :
Paramètre | Obligatoire | Description |
---|---|---|
domain |
oui | Le nom de domaine souhaité |
duration |
non | Période de réservation. Les valeurs supérieures à P1Y peuvent être acceptées sur certaines extensions, mais ne peuvent en aucun cas excéder P10Y |
offerId |
non | Offre disponible pour le domaine. Une seule valeur est possible pour un domaine donné, voir ci-dessus pour la récupérer (déprécié) |
quantity |
non | Seule la valeur "1" est autorisée |
planCode |
non | Représente le plan lié au domaine |
pricingMode |
non | Représente l'offre liée au plan du domaine |
{
"cartId": "c87b5e9d-f586-4456-9f56-1709f40e7b1d",
"configurations": [68544099],
"duration": "P1Y",
"itemId": 109074889,
"offerId": null,
"options": [],
"prices": [
{
"label": "TOTAL",
"price": {
"currencyCode": "EUR",
"text": "6.99 €",
"value": 6.99
}
},
{
"label": "FEE",
"price": {
"currencyCode": "EUR",
"text": "6.99 €",
"value": 6.99
}
},
{
"label": "RENEW",
"price": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
}
},
{
"label": "PRICE",
"price": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
}
}
],
"productId": "domainblog",
"settings": {
"catalogName": "dom-public",
"domain": "exemple.fr",
"planCode": "fr",
"pricingMode": "create-default",
"quantity": 1
}
}
Pensez à bien noter la valeur itemId
, elle nous servira pour la suite.
Cette étape est optionnelle. Elle donne un aperçu du contenu du panier, mais elle ne valide pas sa cohérence ou les configurations qu'il contient.
{
"contracts": [],
"details": [
{
"cartItemID": null,
"description": "testdomainorder.com - Zone DNS",
"detailType": "DURATION",
"domain": "*001.001",
"originalTotalPrice": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
},
"quantity": 1,
"reductionTotalPrice": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
},
"reductions": [],
"totalPrice": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
},
"unitPrice": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
}
},
{
"cartItemID": null,
"description": "DNS zone",
"detailType": "INSTALLATION",
"domain": "*001.001",
"originalTotalPrice": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
},
"quantity": 1,
"reductionTotalPrice": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
},
"reductions": [],
"totalPrice": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
},
"unitPrice": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
}
},
{
"cartItemID": null,
"description": "testdomainorder.com - .com demande d'enregistrement - 12 mois",
"detailType": "DURATION",
"domain": "*001",
"originalTotalPrice": {
"currencyCode": "EUR",
"text": "9.99 €",
"value": 9.99
},
"quantity": 1,
"reductionTotalPrice": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
},
"reductions": [],
"totalPrice": {
"currencyCode": "EUR",
"text": "9.99 €",
"value": 9.99
},
"unitPrice": {
"currencyCode": "EUR",
"text": "9.99 €",
"value": 9.99
}
},
{
"cartItemID": null,
"description": "Domain .com",
"detailType": "INSTALLATION",
"domain": "*001",
"originalTotalPrice": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
},
"quantity": 1,
"reductionTotalPrice": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
},
"reductions": [],
"totalPrice": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
},
"unitPrice": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
}
},
{
"cartItemID": null,
"description": ".COM Create Prix barre",
"detailType": "GIFT",
"domain": "*001",
"originalTotalPrice": {
"currencyCode": "EUR",
"text": "-2.50 €",
"value": -2.5
},
"quantity": 1,
"reductionTotalPrice": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
},
"reductions": [],
"totalPrice": {
"currencyCode": "EUR",
"text": "-2.50 €",
"value": -2.5
},
"unitPrice": {
"currencyCode": "EUR",
"text": "-2.50 €",
"value": -2.5
}
}
],
"orderId": null,
"prices": {
"originalWithoutTax": {
"currencyCode": "EUR",
"text": "7.49 €",
"value": 7.49
},
"reduction": {
"currencyCode": "EUR",
"text": "0.00 €",
"value": 0
},
"tax": {
"currencyCode": "EUR",
"text": "1.50 €",
"value": 1.5
},
"withTax": {
"currencyCode": "EUR",
"text": "8.99 €",
"value": 8.99
},
"withoutTax": {
"currencyCode": "EUR",
"text": "7.49 €",
"value": 7.49
}
},
"url": null
}
Sans rentrer dans les détails de ce payload, il y a certaines choses à retenir :
detailType
= GIFT
)prices
représente le total du panier avec et sans taxe.La présence d'une zone DNS (représentée par deux lignes de détails) alors qu'elle n'a pas été ajoutée au panier peut surprendre. Cela fait écho à une notion souvent méconnue, ou tout du moins mal comprise. Une zone DNS et un domaine sont deux choses (produits) différentes. Un nom de domaine peut très bien être chez OVHcloud alors que la zone peut être hébergée autre part.
Cependant, les deux étant très liés et dans le but de faciliter la commande d'un nom de domaine, nous avons fait le choix d'installer automatiquement une zone à l'achat d'un nom de domaine. Bien sûr, il est possible de commander soi-même une zone associée au domaine afin d'y ajouter des options telles que DNSSEC ou DNS Anycast. Mais nous reparlerons de ceci lorsque nous aborderons les options.
Bien que cette opération puisse se faire dès la création du panier, elle devient indispensable à partir de maintenant. Nous le verrons par la suite, les configurations d'un nom de domaine et leur validation dépendent du nic OVHcloud assigné au panier.
A ce stade, le panier contient un domaine. Il faut maintenant gérer les configurations requises afin de pouvoir, par la suite, valider le bon de commande.
Pour connaître les configurations requises, il suffit d'appeler l'API suivante.
Paramètre | Obligatoire | Défaut | Description |
---|---|---|---|
cartId | oui | "" | L'identifiant du panier |
itemId | oui | "" | L'identifiant de l'item inséré dans le panier |
[
{
"label": "OWNER_LEGAL_AGE",
"type": "bool"
},
{
"label": "OWNER_CONTACT",
"type": "/me/contact"
},
{
"label": "ADMIN_ACCOUNT",
"type": "Nichandle"
},
{
"label": "TECH_ACCOUNT",
"type": "Nichandle"
},
{
"label": "DNS",
"type": "String"
}
]
La réponse ci-dessus représente l'exemple le plus commun que vous pourrez retrouver lors de la commande de création d'un nom de domaine. Mais celle-ci dépend fortement de l'action désirée (transfert, création), de l'extension ou bien du type de domaine (premium, issu d'un marché secondaire).
Voici la liste exhaustive des différentes configurations requises pour un nom de domaine :
Label | Type | Obligatoire | Description |
---|---|---|---|
ADMIN_ACCOUNT |
string | non | Représente le nic OVHcloud qui pourra administrer le domaine et sera associé en tant qu'admin sur le Whois. Si vide, le nic connecté à l'API sera pris par défaut. La valeur attendue doit être un nic valide sous la forme xxx-ovh |
TECH_ACCOUNT |
string | non | Représente le nic OVHcloud qui pourra gérer techniquement le domaine et sera associé en tant que tech sur le Whois. Si vide, le nic connecté à l'API sera pris par défaut. La valeur attendue doit être un nic valide sous la forme xxx-ovh |
OWNER_CONTACT |
/me/contact ou /domain/contact | non | Représente le propriétaire du nom de domaine. Si vide, le nic admin sera pris en modèle pour créer un contact. La valeur attendue est une chaîne de caractères sous la forme /me/contact/1234 ou /domain/contact/12345 |
DOMAIN_CONFIG |
json | selon l'extension | Très rarement présent, il est lié à certaines contraintes d'extensions spécifiques (gov.uk par exemple) |
ACCEPT_CONDITIONS |
bool | oui si présent | Indique que l'extension possède des conditions particulières à l'obtention de l'extension |
REASON |
string | oui si présent | Il indique que le registre demande la raison pour laquelle le domaine veut être commandé. Cela concerne généralement des domaines réservés à des usages spécifiques (ville par exemple) |
CLAIMS_NOTICE |
string | oui si présent | Indique si un avis de marque est présent sur le domaine. Si oui, alors le domaine est protégé par une marque et une notification sera alors envoyée au détenteur de la marque. Si le registrant n'est pas détenteur de la marque, le domaine pourra être supprimé par la suite sans remboursement possible |
PROTECTED_CODE |
string | oui si présent | Certains domaines sont réservés par un registre et nécessitent un code spécifique pour débloquer leur obtention |
OWNER_LEGAL_AGE |
bool | oui | Toujours présent, il s'agit d'une configuration de type "opt-in" afin de certifier que le registrant à l'âge légal pour posséder un nom de domaine |
AUTH_INFO |
string | non | Code d'autorisation utilisé pour prouver que vous êtes le propriétaire du domaine. Utilisé pour les transferts de nom de domaines. |
Cette API est conçue pour répondre aux besoins de la plupart des produits OVHcloud.
Les noms de domaine ont la particularité d'avoir des règles complexes concernant la valeur de certaines configurations, notamment sur les configurations ADMIN_ACCOUNT
, OWNER_CONTACT
ou encore DOMAIN_CONFIG
, celles-ci étant liées aux règles de gestion des registres.
Par exemple, pour l'obtention d'un .berlin, soit le contact registrant soit le contact admin doit résider à Berlin. Or cette API est en incapacité de décrire ce genre de règle.
Pour cela, il existe d'autres API afin de décrire les informations nécessaires à un nom de domaine de manière précise. Ces APIs correspondant à un usage avancé, et étant utilisées également en dehors de la commande (comme pour la mise à jour d'un contact), elles sont décrites en détail dans la section Gestion des règles.
Ici, le OWNER_CONTACT
représente une API de "ressource", à savoir /me/contact
ou plus précisement /domain/contact
.
Les APIs permettant de créer ces contacts sont décrites dans la section Gestion des contacts.
Maintenant qu'on a récupéré la liste des configurations requises, il suffit de les ajouter sur le produit.
Paramètre | Obligatoire | Défaut | Description |
---|---|---|---|
cartId |
oui | "" | L'identifiant du panier |
itemId |
oui | "" | L'identifiant de l'item inséré dans le panier |
label (corps de requête) |
oui | "" | Clé de configuration (voir liste ci-dessus) |
value (corps de requête) |
oui | "" | Valeur de configuration à définir |
{
"id": 69663774,
"label": "OWNER_CONTACT",
"value": "/me/contact/13189481"
}
A tout moment, il est bien entendu possible de visualiser et manipuler le panier avec les API suivantes :
Cette étape est sans doute la plus importante du processus de commande et se fait via l'appel suivant.
Elle permet de récupérer le bon de commande dans sa forme finale sans le générer (c'est un "dry-run"). L'objet retourné contient les contrats associés aux différents produits.
Cet appel permet également de valider les configurations comme par exemple les éligibilités du propriétaire pour un nom de domaine.
Paramètre | Obligatoire | Défaut | Description |
---|---|---|---|
autoPayWithPreferredPaymentMethod |
oui | "" | Permet de payer automatiquement le bon de commande avec le moyen de paiement par défaut du nic |
waiveRetractationPeriod |
oui | "" | Obligatoire pour un nom de domaine. Il représente la renonciation au droit de rétractation |
Si vous n'avez pas payé le bon de commande automatiquement lors de la précédente étape, vous aurez besoin de manipuler les APIs de gestion des bons de commande. Bien qu'il existe de nombreuses APIs en relation avec les moyens de paiement et la gestion des bons de commande, nous partirons du principe qu'au moins un moyen de paiement est enregistré sur votre compte.
Dans un premier temps, récupérons les moyens de paiement disponibles pour le bon de commande effectué plus tôt avec la route suivante :
Paramètre | Obligatoire | Défaut | Description |
---|---|---|---|
orderId |
oui | "" | Identifiant du BC obtenu lors de la création du bon de commande |
[
{
"paymentMean": "bankAccount"
}
]
/* Valeurs possibles pour paymentMean :
"CREDIT_CARD"
"CURRENT_ACCOUNT"
"DEFERRED_PAYMENT_ACCOUNT"
"ENTERPRISE"
"INTERNAL_TRUSTED_ACCOUNT"
"PAYPAL"
"bankAccount"
"creditCard"
"deferredPaymentAccount"
"fidelityAccount"
"ovhAccount"
"paypal"
*/
Le paiement du bon de commande se fait via l'API ci-dessous. Celle-ci ne retourne aucun résultat mais le statut 200 indique une réussite.
Paramètre | Obligatoire | Défaut | Description |
---|---|---|---|
orderId |
oui | "" | Identifiant du BC obtenu lors de la création du bon de commande |
paymentMean |
oui | "" | Moyen de paiement récupéré lors de la récupération des moyens de paiement disponible |
paymentMeanId |
selon moyen de paiement | "" | L'identifiant du moyen de paiment est obligatoire poour les valeurs bankAccount , creditCard ou paypal |
L'API suivante permet de connaître l'état d'un bon de commande.
Paramètre | Obligatoire | Défaut | Description |
---|---|---|---|
orderId |
oui | "" | Identifiant du BC obtenu lors de la création du bon de commande |
"notPaid"
/* Valeurs possibles :
"cancelled"
"cancelling"
"checking"
"delivered"
"delivering"
"documentsRequested"
"notPaid"
"unknown"
*/
N’hésitez pas à nous proposer des suggestions d’amélioration afin de faire évoluer cette documentation.
Images, contenu, structure… N’hésitez pas à nous dire pourquoi afin de la faire évoluer ensemble !
Vos demandes d’assistance ne seront pas traitées par ce formulaire. Pour cela, utilisez le formulaire "Créer un ticket" .
Merci beaucoup pour votre aide ! Vos retours seront étudiés au plus vite par nos équipes..
Accedez à votre espace communautaire. Posez des questions, recherchez des informations, publiez du contenu et interagissez avec d’autres membres d'OVHcloud Community.
Echanger sur OVHcloud Community