So bestellst du Pakete mit der API

Du richtest Websites für deine Kunden ein? Dann kannst du ihr Webhosting über die Site.de-API bestellen. Dein Skript bezahlt aus deiner Wallet, und die Bestellung startet sofort.

Mit der API kannst du ein neues Paket bestellen, ein Paket verlängern und ein Paket wiederherstellen. Jeder Aufruf ist eine Bestellung für ein Paket. Du möchtest auch Domainnamen bestellen? Lies nach, wie du Domainnamen 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:

• plans.order.create: Pakete bestellen, verlängern und wiederherstellen.
• domains.view: die IDs deiner Pakete und Domainnamen abfragen.

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 ein neues Paket zu bestellen:

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

Im Body schickst du mindestens plan_name mit, zum Beispiel starter. 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.

Ein neues Paket bestellen

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

Diese Felder kannst du mitschicken:

• plan_name (Pflichtfeld): der Name des Pakets in Kleinbuchstaben, zum Beispiel starter oder power.
• order_period: die Anzahl der Jahre, 1 bis 5. Standard ist 1.
• domain_name_ids: die IDs von Domainnamen, die du schon bei uns hast und die ins neue Paket sollen. Du findest sie mit GET /v2/domain_names.
• external_domain_name_ids: die IDs von Domainnamen, die woanders registriert sind, die du aber zu deinem Konto hinzugefügt hast. Du findest sie mit GET /v2/external_domain_names.
• expected_price: der Preis in Cent ohne MwSt., den du akzeptierst. Weicht der Preis ab? Dann geben wir die Bestellung nicht auf.
• dry_run: true prüft die Bestellung nur und berechnet den Preis.

Die Domainnamen müssen aktiv sein und dürfen noch in keinem anderen Paket sein. Außerdem hat jedes Paket eine Höchstzahl an Domainnamen. Du brauchst einen neuen Domainnamen für das Paket? Bestell ihn zuerst und warte, bis er aktiv ist.

Ein Paket verlängern oder wiederherstellen

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

Hier ist 91 die ID des Pakets. Du findest sie mit GET /v2/plans. Im Body kannst du order_period (in Jahren), expected_price und dry_run mitschicken.

• Verlängern: für ein aktives Paket. Lies nach, wie die Verlängerung eines Pakets funktioniert.
• Wiederherstellen: für ein Paket, das abgelaufen ist oder gekündigt wurde, bis zu 14 Tage nach dem Ablauf.

Wird das Paket gerade in ein anderes Konto umgezogen? Dann kannst du es erst verlängern, wenn der Umzug abgeschlossen ist.

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

Jede Position der Bestellung hat einen Status: unprocessed, processing, processed, 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.

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. Zum Beispiel: Das Paket kann nicht so viele Domainnamen aufnehmen, ein Domainname ist schon in einem Paket, oder die Wiederherstellungsfrist ist vorbei.
• 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.
• GENERAL_001: Es gibt kein Paket mit diesem Namen, oder die Paket-ID gehört nicht zu deinem Konto.
• DOMAIN_NOT_FOUND: Eine der Domainnamen-IDs gehört nicht zu deinem Konto.

Gut zu wissen

• Es gibt keine Testumgebung. Jede Bestellung ist echt. Teste deshalb zuerst mit dry_run.

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