menu
small_header_general.svg

netcup wiki

Generelles

API

Die netcup API im Detail

Beachten Sie bitte auch unsere ausführliche technische Dokumentation der API.

CCP API

Die APIs im CCP erlauben es Ihnen, programmatisch verschiedene Aktionen durchzuführen.

Aktuell zur Verfügung stehende API-Dienste

  • DNS API

    • Mit der DNS-API können Sie Modifikationen an DNS-Zonen von Domains vornehmen, welche über unsere netcup Nameserver konnektiert sind, sowie Informationen über die DNS-Zonen und -Records erhalten.

  • Domainreselling API

    • Nur nach Abschluss eines Domainreselling-Vertrags mit uns nutzbar
    • Die API erlaubt es Ihnen, Domains zu registrieren und zu transferieren, Kontakthandles anzulegen, Domains Handles zuzuweisen und vieles mehr.

Authentifizierung

Beantragung eines API-Passworts und API-Keys

Für die Nutzung der API-Funktionen benötigen Sie ein API-Passwort, sowie einen API-Key. Die nötigen Daten können Sie in Ihrem Customer Control Panel (CCP) unter "Stammdaten" und dort "API" erhalten.

API-Passwort generieren

Api-pw-gen2.png

Um das API-Passwort zu generieren, klicken Sie bitte auf den Button "API-Passwort generieren". Das Passwort wird von uns generiert, es ist nicht möglich, ein eigenes Passwort zu hinterlegen.

Api-pw-anzeige2.png

Sobald Sie ein neues Passwort generieren, müssen Sie dieses direkt in Ihren Clients anpassen. Das Passwort für die API wird Ihnen einmalig in der Bestätigungsmeldung angezeigt. Sollten Sie dieses vergessen, müssen Sie ein neues Passwort generieren, denn pro Kundenkonto wird lediglich ein API-Passwort vergeben. Bewahren Sie das Passwort also gut auf.

API-Key erstellen

Api-key-gen2.png

Um letztlich eine Verbindung mit der Schnittstelle herstellen zu können, benötigen Sie mindestens einen API-Key. Diesen können Sie ebenfalls im CCP unter "Stammdaten" und "API" erstellen. Bestätigen Sie dazu bitte die Bedingungen für die Nutzung der API mit einem Klick auf die Checkbox. Anschließend können Sie über den Button "API-Key erstellen" einen Key für die Nutzung der Schnittstelle erstellen lassen.

Der API-Key wird von uns generiert und ist hinreichend lang, um eine hohe Sicherheit zu gewährleisten. Der API-Key wird Ihnen anschließend angezeigt und Sie können diesen in Ihren Clients implementieren.

Sie können mehrere API-Keys erzeugen und unabhängig voneinander auch wieder entfernen.

Api-key-remove2.png

Authentifizierung an der API

Um die API nutzen zu können, müssen Sie sich authentifizieren. Jeder Job erfordert eine Authentifizierung mit gültiger Session in Form einer Session ID.

Bei Nutzung der login Methode übermitteln Sie an uns

  • Ihre Kundennummer
  • Ihren API-Key
  • Ihr API-Passwort

Sie erhalten von uns dann als return Wert eine generierte Session ID übermittelt, die Sie, zusammen mit dem API-Key, zur Nutzung der anderen Methoden benötigen. Durch Nutzung Ihrer Session ID sind Sie gegenüber unserer API authentifiziert.

Die Session läuft nach 15 Minuten Inaktivität automatisch ab. Alternativ können Sie die logout Methode nutzen. Diese führt zu einem direkten Ablauf der Session.

API-Log

In Ihrem Customer Control Panel (CCP) können Sie im Bereich "Domains" unter "API Log" die zuletzt ausgeführten API-Aktionen ansehen. Falls Sie kein Domainreseller sind, erscheint der Button, sobald Sie mindestens eine API-Aktion ausgeführt haben.

Api log3.png

Sie finden dort den Zeitpunkt, die Aktion, den Status, eine kurze Rückmeldung, das Handle bzw. die Domain, auf die sich die Handlung bezieht, den verwendeten API-Key, sowie den Zeitpunkt, zu dem die Nachricht (mit ackpoll) gelesen wurde.

API-Log2.png

Wie auch auf dem obigen Screenshot zu erkennen, werden Aktionen, die am selben Tag und in der gleichen Stunde, Minute und Sekunde durchgeführt werden, nicht zwangsläufig in chronologischer Reihenfolge dargestellt.

Über einen Klick auf die Lupe links neben der Aktion erhalten Sie eine lange Rückmeldung, die Request Message und die Response Message angezeigt. Ferner sehen Sie auch die Server Request ID, die Client Request ID, die Rückmeldungsnummer, sowie das verwendete Nachrichtenformat.

Die Rückmeldungsnummern orientieren sich an den üblichen Gruppen der HTTP-Fehlercodes:

  • 2*** Erfolgsmeldungen
  • 4*** Fehler tendenziell auf Kundenseite
  • 5*** Fehler tendenziell auf Serverseite

Geloggt werden folgende Aktionen:

  • cancelDomain
  • changeOwnerDomain
  • createDomain
  • createHandle
  • deleteHandle
  • getAuthcodeDomain
  • transferDomain
  • updateDnsRecords
  • updateDnsZone
  • updateDomain
  • updateHandle

Technische Informationen

Im Folgenden erhalten Sie technische Informationen zur Nutzung der API.

API-Endpoint

Der API-Endpoint befindet sich unter folgender URI:

https://ccp.netcup.net/run/webservice/servers/endpoint.php

Allgemeine Informationen zu API-Requests

  • Input und Output erfolgt in UTF-8.
  • Domains die Sonderzeichen wie beispielsweise einen deutschen Umlaut enthalten, müssen vor der Übertragung in Punycode umgewandelt werden. Je nach Registrar kann es trotzdem sein, dass bestimmte Sonderzeichen nicht unterstützt werden. Sie erhalten dann eine Fehlermeldung.
  • Ändert sich die Rückmeldung seitens der Registry (z.B. bei einem Transfer von der Auftragsannahme "return receipt" zu "transfer successful", so wird die Message bei einem poll erneut mit der neuen Rückmeldung übermittelt, auch wenn diese zuvor via ackpoll gelesen wurde.

Validierung

  • Zur Validierung können die in der WSDL enthaltenen XSDs genutzt werden.

URI für SOAP-Requests

https://ccp.netcup.net/run/webservice/servers/endpoint.php?WSDL

Anmerkungen zu SOAP-Requests

  • Geben Sie bei einem SOAP-Aufruf im Client bitte die Parameter wie in der Funktion bzw. der WSDL beschrieben vor.

  • Verwenden sie zum Beispiel den von uns generierten SOAP Client

https://ccp.netcup.net/run/webservice/servers/endpoint.php?PHPSOAPCLIENT

  • Wir garantieren nicht die Fehlerfreiheit des Client. Auf dem Markt findet sich eine Vielzahl von kostenlosen Lösungen, die für die von Ihnen präferierte Sprache Code aus der WSDL erzeugen.
Anmerkungen zu JSON-Requests

Die Nachricht (payload) an den Server muss per POST erfolgen. Ein Login sieht z.B. wie folgt aus:

{
   "action":"login",
   "param":{
      "apikey":"xxxxxxxxxxxx",
      "apipassword":"xxxx",
      "customernumber":"123456"
   }
}

URI für JSON-Requests (REST)

https://ccp.netcup.net/run/webservice/servers/endpoint.php?JSON

Wichtige Anmerkungen zu JSON-Requests
  • Nutzen Sie die JSON-URI für Requests in REST-Form.
  • Die Parameterreihenfolge ist bei JSON-Requests irrelevant, da die Parameter per Key definiert werden.

Technische Clients

Bitte beachten Sie, dass wir für die Funktionsfähigkeit, Stabilität, Zuverlässigkeit, usw. bezüglich der folgenden Clients keine Haftung übernehmen. Diese wurden nicht von oder im Auftrag der netcup GmbH entwickelt oder von uns getestet. Wir können dafür keinen Support leisten. Bei Fragen wenden Sie sich bitte an den Entwickler des jeweiligen Clients.

Einige unserer Nutzer haben Clients entwickelt, die mit unseren APIs verwendet werden können. Wir freuen uns über das Engagement unserer Nutzer und möchten Ihnen die Projekte hier gerne vorstellen. Haben Sie auch einen Client für eine unserer APIs entwickelt und dieser fehlt in der folgenden Liste? Schreiben Sie uns gerne eine E-Mail mit einer kurzen Beschreibung Ihres Projekts und wir nehmen Ihren Client auf.

Inhaltsverzeichnis

  • 1 Liste der CCP API-Clients
    • 1.1 DNS API
      • 1.1.1 DNS-Verwaltung
      • 1.1.2 Dynamisches DNS
      • 1.1.3 Let's Encrypt Clients
      • 1.1.4 Libraries / Schnittstellen

Liste der CCP API-Clients

DNS API

DNS-Verwaltung
  • ncdapi (inofficial netcup DNS API Client)
Dynamisches DNS
Let's Encrypt Clients
Libraries / Schnittstellen

DNS API

Die DNS-Funktionalität (DNS API) der CCP API ermöglicht es Ihnen, Modifikationen an DNS-Zonen von Domains vorzunehmen, welche über unsere netcup Nameserver konnektiert sind, sowie Informationen über die DNS-Zonen und -Records zu erhalten.

Die zur Verfügung stehende Funktionalität orientiert sich dabei unter anderem an den Möglichkeiten, die Ihnen im CCP im Bereich "DNS" bereits zur Verfügung stehen. Dazu finden Sie bereits umfangreiche Dokumentation in unserem Wiki.

Im Folgenden beschreiben wir die Grundlagen zur Nutzung der DNS-API.

Voraussetzungen

Für die Nutzung der DNS-API müssen Sie keine besonderen Voraussetzungen erfüllen. Die DNS-API kann von jedem Kunden, der Domains bei uns besitzt, genutzt werden. Wichtig ist, dass für die zu bearbeiteten Domains die Nameserver von netcup gesetzt sind. Verwenden Sie externe Nameserver, können wir für diese keine API bereitstellen. Ferner richtet sich die DNS-API an Kunden, die bereits Erfahrung mit der Manipulation und dem Anlegen von DNS-Einträgen gesammelt haben.

Beachten Sie bitte: Ungültige oder falsche DNS-Einträge können die Funktionalität Ihrer Domain beeinträchtigen.

Funktionen

Mit der DNS-API können Sie aktuell:

  • Sich an der API anmelden bzw. abmelden

    • Methoden: login bzw. logout

  • Informationen über die DNS-Zone einer Domain erhalten

    • Methode: infoDnsZone

  • Alle DNS-Records einer Zone erhalten

    • Methode: infoDnsRecords

  • Änderungen an der DNS-Zone einer Domain vornehmen

    • Methode: updateDnsZone

  • Änderungen an den DNS-Records einer Zone vornehmen

    • Methode: updateDnsRecords

Alle Änderungen, die Sie über die API durchführen, sind auch im CCP ersichtlich, umgekehrt gilt das Gleiche.

Nutzung der API

Möchten Sie die Funktionen der API verwenden, so finden Sie hier die nötigen Informationen zur Authentifizierung, sowie technische Informationen zur Verwendung der API unter CCP API.

Domainreselling API – netcup Wiki

Mit der Domainreselling-Funktionalität (Domainreselling API) der CCP API können Sie als Domainreseller vielfältige Aktionen mit Domains durchführen. So erlaubt die API Ihnen, Domains zu registrieren und zu transferieren, Kontakthandles anzulegen, Domains Handles zuzuweisen und vieles mehr.

Die zur Verfügung stehende Funktionalität orientiert sich dabei unter anderem an den Möglichkeiten, die Ihnen das Domainreselling bereits im CCP bietet. Dazu sei hier auf unsere entsprechende Dokumentation verwiesen.

Im Folgenden beschreiben wir die Grundlagen zur Nutzung der Domainreselling-API.

Voraussetzungen

Um die Domainreselling-API nutzen zu können, müssen Sie bestimmte Voraussetzungen erfüllen:

  • Sie müssen Domain-Reseller von netcup sein, um die Domainreselling-API nutzen zu können: Bestellung Reseller-Level

  • Die Domainreselling-API richtet sich an Kunden, die bereits Erfahrung mit Aktionen, die Domains betreffen, gesammelt haben.

  • Bei Verwendung von Funktionen der API, welche die Angabe von Nameservern erfordern, ist es nötig, mindestens zwei eigene Nameserver zu betreiben. In diesem Fall können Sie nicht die von uns bereitgestellten Nameserver nutzen. Möchten Sie diese verwenden, so führen Sie nach der Registrierung oder dem Transfer die nötigen Aktionen bitte über ihr CCP durch.

    • Verwenden Sie auf Ihrem vServer zum Beispiel das vorkonfigurierte PowerDNS Image von netcup, um selbst Nameserver zu installieren.

Funktionen

Mit der Domainreselling-API können Sie aktuell:

  • Sich an der API anmelden bzw. abmelden

    • Methoden: login bzw. logout

  • Kontakthandles anlegen, bearbeiten und löschen

    • Methoden: createHandle, updateHandle und deleteHandle

  • Alle angelegten Kontakthandles auflisten lassen

    • Methode: listallHandle

  • Domains registrieren und transferieren

    • Methoden: createDomain und transferDomain

  • Alle angelegten Domains auflisten lassen

    • Methode: listallDomains

  • Authcodes für Domains beantragen

    • Methode: getAuthcodeDomain

  • Domains kündigen

    • Methode: cancelDomain

  • Inhaberwechsel von Domains durchführen

    • Methode: changeOwnerDomain

  • Domain-UPDATEs durchführen (Handles und Nameserver ändern)

    • Methode: updateDomain

  • Informationen über eine Domain bzw. ein Kontakthandle erhalten

    • Methoden: infoDomain bzw. infoHandle

  • Den Preis einer bestimmten TLD erhalten

    • Methode: priceTopleveldomain

  • Rückmeldungen zu durchgeführten Domainaufträgen erhalten und diese als gelesen markieren

    • Methoden: poll und ackpoll

Alle Änderungen, die Sie über die API durchführen, sind auch im CCP ersichtlich, umgekehrt gilt das Gleiche.

Einschränkungen

  • Bei dem Ausführen von Domainbestellungen über die API (mittels der Methoden createDomain / transferDomain):

    • Es ist nötig, eigene Handles anzugeben. Es ist dabei nicht möglich, unsere Standardhandles zu verwenden.
      • Sollten für eine Domain unsere Standardhandles gesetzt sein, ist eine Kündigung und ein Inhaberwechsel der Domain nur über das CCP möglich.
    • Domains werden immer als zusätzliche Domains angelegt. Es ist nicht möglich, Inklusivdomains über die API zu registrieren.

  • Wie bereits in den Voraussetzungen genannt, müssen Sie bei der Nutzung von Funktionen der API, bei der die Angabe von Nameservern erforderlich ist, eigene Nameserver angeben und somit betreiben. Dabei können Sie auf unseren vServern auch unser PowerDNS-Image nutzen.

Sollten Sie die obige Funktionalität dennoch nutzen wollen, so können Sie die gewünschten Aktionen über Ihr CCP tätigen.

  • Gespeichert werden im Logging ausschließlich die folgenden Aktionen: cancelDomain, createDomain, changeOwnerDomain, createHandle, deleteHandle, getAuthcodeDomain, transferDomain, updateDnsRecords, updateDnsZone, updateDomain, updateHandle

Nutzung der API

Möchten Sie die Funktionen der API verwenden, so finden Sie die nötigen Informationen zur Authentifizierung, sowie technische Informationen zur Verwendung der API unter CCP API.

Zuletzt aktualisiert: 25.9.2023