So bestellst du Domainnamen mit der API

Du verwaltest viele Domainnamen? Oder verkaufst du sie an deine eigenen Kunden? Dann kannst du sie über die Site.de-API bestellen. Dein Skript bezahlt aus deiner Wallet, und die Bestellung startet sofort.

Mit der API kannst du Domainnamen registrieren, übertragen, verlängern und wiederherstellen. Jeder Aufruf ist eine Bestellung für einen Domainnamen. Du möchtest Webhosting bestellen? Lies nach, wie du Pakete mit der API bestellst. Du bist neu bei unserer API? Dann lies zuerst, wie du mit der API startest.

Was du brauchst

Einen API-Schlüssel. Erstelle ihn in deinem Dashboard unter Einstellungen im Tab API-Schlüssel. Setz unter API-Endpunkte nur bei den Berechtigungen einen Haken, die du brauchst:

• domains.order.create: Domainnamen bestellen (registrieren, übertragen, verlängern und wiederherstellen).
• domains.view: die IDs deiner Domainnamen und den Preis eines Premium-Domainnamens abfragen.
• contacts.required_info: nur, wenn du mit einer Bestellung zusätzliche Angaben zum Domaininhaber mitschickst.

Guthaben in deiner Wallet. Bestellungen über die API werden immer aus deiner Online-Wallet bezahlt. Das Guthaben muss für die ganze Bestellung reichen, inklusive MwSt.

Bestellungen funktionieren nur mit einem API-Schlüssel. Im Browser nutzt du einfach den Warenkorb.

So läuft eine Bestellung ab

Du schickst eine POST-Anfrage an die API. Setz deinen API-Schlüssel in den Header X-API-Key und die Angaben zur Bestellung als JSON in den Body. Zum Beispiel, um einen Domainnamen zu registrieren:

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

Im Body schickst du mindestens domain_name mit, zum Beispiel example.nl. Dann passiert Folgendes:

• Gleicher Preis. Du zahlst dasselbe wie bei einer Bestellung auf unserer Website.
• Stimmt etwas nicht, wird nichts abgebucht. Du bekommst einen Fehlercode, der den Grund nennt.
• Teste es zuerst. Schick dry_run: true mit. Die Antwort zeigt den Preis, die MwSt. und ob dein Wallet-Guthaben reicht. Es wird nichts bestellt und nichts abgebucht.
• Wir starten die Bestellung innerhalb von etwa einer Minute. Ab dann läuft sie wie jede andere Bestellung ab, mit denselben E-Mails.
• Die Bestellung erscheint auf deiner Monatsrechnung, mit dem Vermerk „Via API“. Das passiert auch, wenn die Monatsrechnung bei dir ausgeschaltet ist.

Die API-Dokumentation listet jedes Feld auf und zeigt Beispiele für jede Anfrage und jede Antwort.

Einen Domainnamen registrieren oder übertragen

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

Diese Felder kannst du mitschicken:

• domain_name (Pflichtfeld): der vollständige Domainname, zum Beispiel example.nl.
• auth_key (nur bei Übertragungen): der Transfer-Schlüssel von deinem aktuellen Anbieter. Lies nach, wie du den Transfer-Schlüssel anforderst.
• order_period: 1 bis 5 Laufzeiten. Standard ist 1. Eine Laufzeit ist die kürzeste Registrierungsdauer der Endung, meistens 1 Jahr.
• contact_id: der Kontakt, der Domaininhaber wird. Ohne dieses Feld nutzen wir deinen Standardkontakt.
• name_servers: eine Liste mit 2 bis 8 Nameservern. Ohne dieses Feld bekommt der Domainname deine Standard-Nameserver.
• privacy_protection: true verbirgt den Domaininhaber im WHOIS, sofern die Endung das erlaubt.
• expected_price: der Preis in Cent ohne MwSt., den du akzeptierst. Bei Premium-Domainnamen brauchst du ihn.
• dry_run: true prüft die Bestellung nur und berechnet den Preis.

Du bist nicht sicher, ob der Domainname noch frei ist? Prüf das zuerst. Dafür brauchst du keinen API-Schlüssel:

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

Steht in der Antwort premium: true? Dann frag den Preis mit GET /v2/domain_names/premium_quote ab. Schick diesen Preis als expected_price mit deiner Bestellung mit.

Die Übertragung selbst kann ein paar Tage dauern. Ist sie gescheitert? Dann lies nach, was du tun kannst, wenn die Übertragung deines Domainnamens gescheitert ist.

Einen Domainnamen verlängern oder wiederherstellen

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

Hier ist 6731 die ID des Domainnamens. Du findest sie mit GET /v2/domain_names. Im Body kannst du order_period, expected_price und dry_run mitschicken.

• Verlängern: für einen aktiven Domainnamen. Einen Premium-Domainnamen kannst du nur im letzten Jahr vor dem Ablauf verlängern.
• Wiederherstellen: für einen abgelaufenen Domainnamen, solange er noch in seiner Wiederherstellungsfrist ist. Diese Frist ist je nach Endung unterschiedlich.

Die Antwort

Ist die Bestellung durchgegangen? Dann bekommst du ihre order_id mit order_status paid. Außerdem bekommst du die Preise in Cent: amount_excluding_vat_in_cents, vat_amount_in_cents und total_including_vat_in_cents. Unter payment zeigt wallet_balance_in_cents, wie viel Guthaben noch in deiner Wallet ist.

Verfolge die Bestellung mit ihrer ID:

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

Jede Position der Bestellung hat einen Status: unprocessed, processing, processed, awaiting_required_info, transfer_failed, failed oder cancelled.

Nie doppelt bezahlen

Manchmal bricht die Verbindung ab, direkt nachdem du eine Bestellung geschickt hast. Ist sie durchgegangen oder nicht? Schick sicherheitshalber bei jeder Bestellung den Header Idempotency-Key mit. Das ist ein eindeutiger Code mit bis zu 255 Zeichen, zum Beispiel eine UUID.

Du schickst dieselbe Bestellung mit demselben Code noch einmal? Dann bekommst du die erste Antwort zurück, und es wird nie doppelt abgebucht. Nutzt du den Code für eine andere Bestellung, bekommst du den Fehler ORDER_005.

Braucht der Domaininhaber zusätzliche Angaben?

Manche Endungen, wie .es und .it, brauchen zusätzliche Angaben zum Domaininhaber. Zum Beispiel eine Identifikationsnummer. Ist der Kontakt noch nicht für die Endung vorbereitet? Dann stoppt die Bestellung mit ORDER_003 und dem Grund contact_required_info. Es wird nichts abgebucht. Unter required_info listet die Antwort die Felder auf, die noch fehlen.

Du kannst diese Angaben mit der Bestellung mitschicken, als required_info. Oder du bereitest den Kontakt zuerst vor. Lies nach, wie du mit der API einen Kontakt anlegst und vorbereitest.

Fehlercodes

Bei jedem Fehler wird nichts abgebucht. Das sind die häufigsten:

• ORDER_001: Dein Wallet-Guthaben reicht nicht. Unter top_up nennt die Antwort den Betrag, den du aufladen musst, und einen Link zum Aufladen deiner Wallet.
• ORDER_002: Der Preis entspricht nicht deinem expected_price. Die Antwort enthält den aktuellen Preis.
• ORDER_003: Diese Bestellung ist nicht möglich. Das Feld reason nennt den Grund.
• ORDER_004: Für dein Konto ist die Zahlung aus der Wallet nicht möglich.
• ORDER_005: Du hast diesen Idempotency-Key schon für eine andere Bestellung verwendet.
• DOMAIN_NOT_AVAILABLE: Der Domainname ist vergeben (Registrierung), nicht registriert (Übertragung) oder schon bei uns.
• REG_001: Wir konnten die Registrierungsstelle nicht erreichen. Versuch es etwas später noch einmal.

Gut zu wissen

• Es gibt keine Testumgebung. Jede Bestellung ist echt. Teste deshalb zuerst mit dry_run.
• Wartet eine Registrierung auf Angaben zum Domaininhaber, oder ist eine Übertragung gescheitert? Dann kannst du diese Position mit PATCH /v2/domain_name_orders/22455/cancel stornieren. Hier ist 22455 die ID der Position in der Bestellung. Dein API-Schlüssel braucht dafür domains.order.cancel. Wir schreiben das Geld deiner Wallet gut.

Brauchst du Hilfe? Melde dich bei uns per WhatsApp, Telegram oder E-Mail.