Domeinnamen bestellen met de API

Beheer je veel domeinnamen? Of verkoop je ze aan je eigen klanten? Dan kun je ze bestellen via de Site.nl API. Je script betaalt uit je portemonnee en de bestelling start meteen.

Met de API kun je domeinnamen registreren, verhuizen, verlengen en herstellen. Elke aanroep is één bestelling voor één domeinnaam. Wil je webhosting bestellen? Lees hoe je pakketten bestelt met de API. Werk je voor het eerst met onze API? Lees dan eerst hoe je aan de slag gaat met de API.

Wat je nodig hebt

Een API-sleutel. Maak er een aan in je dashboard onder Instellingen, op het tabblad API-sleutels. Vink onder API-eindpunten alleen de rechten aan die je nodig hebt:

• domains.order.create: domeinnamen bestellen (registreren, verhuizen, verlengen en herstellen).
• domains.view: de ID's van je domeinnamen opzoeken, en de prijs van een premium domeinnaam.
• contacts.required_info: alleen als je bij een bestelling extra gegevens over de domeinhouder meestuurt.

Geld in je portemonnee. Bestellingen via de API betaal je altijd uit je online portemonnee. Het saldo moet de hele bestelling dekken, inclusief btw.

Bestellen via de API kan alleen met een API-sleutel. In je browser gebruik je gewoon de winkelwagen.

Zo werkt een bestelling

Je stuurt een POST-verzoek naar de API. Zet je API-sleutel in de header X-API-Key en de gegevens van de bestelling als JSON in de body. Bijvoorbeeld om een domeinnaam te registreren:

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

In de body stuur je minstens domain_name mee, bijvoorbeeld example.nl. Dan gebeurt dit:

• Dezelfde prijs. Je betaalt hetzelfde als wanneer je op onze website bestelt.
• Er wordt niets afgeschreven als er iets mis is. Je krijgt een foutcode die zegt waarom.
• Test het eerst. Stuur dry_run: true mee. Het antwoord toont de prijs, de btw en of het saldo van je portemonnee genoeg is. Er wordt niets besteld of afgeschreven.
• We starten de bestelling binnen ongeveer een minuut. Vanaf dan gaat alles zoals bij elke andere bestelling, met dezelfde e-mails.
• De bestelling komt op je maandfactuur, met de vermelding "Via API". Dat gebeurt ook als maandelijks factureren uitstaat.

In de API-documentatie staan alle velden, met voorbeelden van elk verzoek en elk antwoord.

Een domeinnaam registreren of verhuizen

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

Deze velden kun je meesturen:

• domain_name (verplicht): de volledige domeinnaam, zoals example.nl.
• auth_key (alleen bij een verhuizing): de verhuiscode van je huidige provider. Lees hoe je de verhuiscode opvraagt.
• order_period: 1 tot 5 termijnen. Standaard is dat 1. Een termijn is de kortste registratieperiode van de extensie, meestal 1 jaar.
• contact_id: het contact dat domeinhouder wordt. Zonder dit veld gebruiken we je standaardcontact.
• name_servers: een lijst van 2 tot 8 nameservers. Zonder dit veld krijgt de domeinnaam je standaard nameservers.
• privacy_protection: true verbergt de domeinhouder in de WHOIS, als de extensie dat toestaat.
• expected_price: de prijs in centen, zonder btw, die je accepteert. Die heb je nodig voor premium domeinnamen.
• dry_run: true controleert de bestelling alleen en berekent de prijs.

Weet je niet zeker of de domeinnaam nog vrij is? Controleer dat eerst. Hiervoor heb je geen API-sleutel nodig:

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

Staat er in het antwoord premium: true? Vraag dan de prijs op met GET /v2/domain_names/premium_quote. Stuur die prijs als expected_price mee met je bestelling.

De verhuizing zelf kan een paar dagen duren. Is die mislukt? Lees dan wat je doet als de verhuizing van je domeinnaam is mislukt.

Een domeinnaam verlengen of herstellen

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

Hier is 6731 het ID van de domeinnaam. Dat vind je met GET /v2/domain_names. In de body kun je order_period, expected_price en dry_run meesturen.

• Verlengen: voor een actieve domeinnaam. Een premium domeinnaam kun je alleen verlengen in het laatste jaar voordat hij verloopt.
• Herstellen: voor een domeinnaam die is verlopen, zolang hij nog in zijn herstelperiode zit. Die periode verschilt per extensie.

Het antwoord

Is de bestelling gelukt? Dan krijg je het order_id, met order_status paid. Je krijgt ook de prijzen in centen: amount_excluding_vat_in_cents, vat_amount_in_cents en total_including_vat_in_cents. Onder payment zie je bij wallet_balance_in_cents wat er nog in je portemonnee staat.

Volg de bestelling met het ID:

GET https://backend.site.nl/v2/orders/5925

Elke regel van de bestelling heeft een status: unprocessed, processing, processed, awaiting_required_info, transfer_failed, failed of cancelled.

Nooit twee keer betalen

Soms valt de verbinding weg vlak nadat je een bestelling verstuurt. Is die nu wel of niet doorgekomen? Stuur voor de zekerheid bij elke bestelling de header Idempotency-Key mee. Dat is een unieke code van maximaal 255 tekens, zoals een UUID.

Stuur je dezelfde bestelling nog een keer met dezelfde code? Dan krijg je het eerste antwoord terug en betaal je nooit twee keer. Gebruik je de code voor een andere bestelling? Dan krijg je de fout ORDER_005.

Heeft de domeinhouder extra gegevens nodig?

Sommige extensies, zoals .es en .it, hebben extra gegevens over de domeinhouder nodig. Een identiteitsnummer bijvoorbeeld. Is het contact nog niet klaar voor de extensie? Dan stopt de bestelling met ORDER_003 en de reden contact_required_info. Er wordt niets afgeschreven. In het antwoord staan onder required_info de velden die je nog nodig hebt.

Je kunt die gegevens met de bestelling meesturen, als required_info. Of je maakt het contact eerst klaar. Lees hoe je met de API een contact aanmaakt en klaarmaakt.

Foutcodes

Bij elke fout wordt er niets afgeschreven. Dit zijn de meest voorkomende:

• ORDER_001: het saldo van je portemonnee is te laag. Onder top_up geeft het antwoord het bedrag dat je moet bijstorten en een link om je portemonnee op te waarderen.
• ORDER_002: de prijs is niet je expected_price. In het antwoord staat de huidige prijs.
• ORDER_003: deze bestelling is niet mogelijk. Het veld reason zegt waarom.
• ORDER_004: betalen uit de portemonnee is voor jouw account niet mogelijk.
• ORDER_005: je hebt deze Idempotency-Key al gebruikt voor een andere bestelling.
• DOMAIN_NOT_AVAILABLE: de domeinnaam is al bezet (registratie), is niet geregistreerd (verhuizing) of staat al bij ons.
• REG_001: we konden de registry niet bereiken. Probeer het later nog eens.

Goed om te weten

• Er is geen testomgeving. Elke bestelling is echt. Test dus eerst met dry_run.
• Wacht een registratie op gegevens van de domeinhouder, of is een verhuizing mislukt? Dan kun je die regel annuleren met PATCH /v2/domain_name_orders/22455/cancel. Hier is 22455 het ID van de regel in de bestelling. Je API-sleutel heeft daarvoor domains.order.cancel nodig. We storten het geld terug in je portemonnee.

Hulp nodig? Neem contact met ons op via WhatsApp, Telegram of e-mail.