1. Hauptseite
2. Infozentrum
3. Tools für die Verwaltung der SSL/TLS-Zertifikate
4. SSLmarket API mit dem Tool Postman manuell ausnutzen

SSLmarket API mit dem Tool Postman manuell ausnutzen

Falls Sie unsere API nicht in die bestehenden Systeme integrieren möchten, oder falls Sie kein solches System haben, wird Ihnen diese Anleitung ermöglichen, die API Anforderungen über das Tool Postman abzusenden. Mit diesem Tool werden Sie ein fertiges Ökosystem für die Absendung von Anfragen und von uns vorkonfigurierte Funktionen erhalten. Die SSLmarket API können Sie somit ohne Kenntnisse im Programmieren ausnutzen und Ihre Zeit sparen.

Die SSLmarket API in andere Ökosysteme zu integrieren ist deshalb vorteilhaft, weil sie Ihnen eine komplexe Lösung bringt. Die in der Anleitung beschriebene Lösung kann zwar nie automatisiert funktionieren, ist nur manuell, aber auch trotzdem kann sie Ihnen viele Stunden Zeit retten.

Installierung der Anwendung Postman

Laden Sie die Desktop-Version der Anwendung auf dem Web herunter. Postman gibt es auch in einer Web-Version, diese ist aber für unseren Zweck nicht geeignet – funktioniert nicht.

Die Windows-Version wird traditionell installiert. Bei Linux werden Sie Postman wahrscheinlich als ein Snap-Packet bereits zur Verfügung haben. Im Terminal geben Sie das Folgende ein:

sudo snap install postman

Einstellung der Anwendung für SSLmarket

Um Ihnen die Arbeit mit API und dem Programm maximal zu vereinfachen, haben wir für Sie eine Auswahl von Aufrufen in der Datei JSON vorbereitet. Diese müssen Sie nur importieren und Sie werden alle Funktionen gleich zur Verfügung haben. Importieren Sie die Auswahl (Button link oben Import) und dann wählen Sie die von uns vorbereitete Datei JSON aus. Unter Collections werden Sie den Posten SSLmarket und zehn Funktionen sehen. Klicken Sie auf SSLmarket mit der rechten Taste und stellen Sie die Variablen in Edit → Variables ein.

Das Wichtigste ist die Variable X-Auth-Token mit dem Wert aus dem Kundenkonto einzustellen. Andere Variablen werden Sie sicher mit den richtigen Werten logischerweise verknüpfen können, aber auf alle Fälle finden Sie unten ihre Übersicht.

Erklärung der Felder

• X-Auth-Token – Feld für die Eingabe des API Schlüssels
• owner_### - Angaben des zukünftigen Zertifikatsinhabers für Konkretisierung
• auth_### - Angaben der Kontaktperson für Autorisierung, die bei den firmenverifizierten Zertifikaten die Bestellung bestätigt.
• tech_### - Angaben der technischen Kontaktperson. Diese beteiligt sich an der Verifizierung nicht, wird aber das ausgestellte Zertifikat per E-Mail erhalten.
• invoice_### - Feld für Konkretisierung der Rechnungsangaben; diese Informationen definieren den Abnehmer der Rechnung.

Diese Defaultangaben werden sich Ihnen in den Variablen anbieten (zum Beispiel beim Aufgeben der Bestellung) und Sie werden sie nicht mehr eingeben müssen. Falls Ihnen die Bedeutung eines der Felder unklar bleibt, finden Sie sie in den API Unterlagen.

Nachdem Sie die Einstellung abschließen und alle Informationen aufführen, können Sie mit der Absendung der Anforderungen in die SSLmarket API anfangen.

Absendung von Anforderungen

Nach der Einstellung des Programms werden Sie die Anforderungen und vor allem neue Bestellungen absenden können. CSR darf keine Leerzeichen und Umbrüche, die mit der escape Sequenz gelöst werden können, enthalten. Mehr in dem folgenden Absatz.

Wählen Sie in der Auswahl von Aufrufen die API Funktion aus, die Sie ausnutzen möchten. Nachfolgend werden Sie in dem rechten (großen) Teil des Fensters in dem Tab Body die Konstruktion der Frage sehen. Zum Beispiel bei der Bestellungsaufgabe sind hier alle Informationen zu dem zukünftigen Zertifikat aufgeführt – ihr Umfang entspricht der Bestellung auf dem Web. Die in Klammern aufgeführten Informationen bedeuten, dass die Variable, die Sie früher definiert haben, benutzt wird – zum Beispiel {{owner_name}}. Diese Posten passen Sie an nur falls Sie andere Angaben als die Defaultangaben nutzen brauchen.

Angaben für das Aufgeben der Bestellung

Angaben über den Antragsteller und Kontaktangaben werden aus den vorbereiteten Defaultangaben gelesen. Für jede Bestellung müssen aber die folgenden spezifischen Angaben konkretisiert werden:

• domain - Common Name des Zertifikats
• dns_names - Liste von SANs in dem Zertifikat
• years - Anzahl der Jahre der Gültigkeitsdauer der Bestellung (die Laufzeit des Zertifikats ist zwar beschränkt, aber die Bestellung kann für mehrere Jahre aufgegeben werden)
• csr - Hier geben Sie den CSR-Code ein. Er darf keine Zellenabstände und Leerzeichen enthalten, siehe unten. Es handelt sich um kein Pflichtfeld – CSR können Sie in SSLmarket auch der nach Erstellung der Bestellung über API eingeben.
• dv_auth_method - Auswahl der Verifizierungsmethode DCV (E-Mail, DNS, FTP)

Wenn alle Ihre Angaben ausgefüllt sind, können Sie die vorbereitete Anforderung nach API über den blauen Button Send absenden.

Den Verlauf und das Ergebnis der Anfrage können Sie in dem unteren Teil des Fensters sehen. Falls das Ergebnis erfolgreich ist, erhalten Sie zurück die angeforderte Information, oder, falls Sie eine Bestellung aufgegeben haben, ihre Nummer. Andernfalls werden Sie eine Fehlermeldung erhalten, aus der Sie erkennen werden, was falsch ist oder was fehlt.

Beispiel der erfolgreichen Bestellungsaufgabe

{
    "order_id": "155252"
}

Beispiel der Fehlermeldung

   {
    "error": [
        "dv_auth_method => isEmpty - Der Posten ist obligatorisch und darf nicht leer bleiben"
    ]
}

Mögliche Kollisionen beim Absenden der Bestellungen

• Genutzte URL – Nutzen Sie die URL des Endpoints in der Form www.sslmarket.tld, nicht nur sslmarket.tld. Auf der Basis-Domain kommt es zur Umleitung und nachfolgend zu Problemen mit Requests.
• CSR request - Achten Sie darauf, dass der CSR-Code nicht in mehrere Zeilen verteilt wird. Falls Sie den CSR in der richtigen Form nicht eingeben können, senden Sie die Bestellung ohne ihn ab und nachfolgend kopieren Sie den Code wie üblicherweise in das Detail der Bestellung in Ihrer Kundenverwaltung ein.
  • CSR kann nicht in Zeilen verteilt gesendet werden, obwohl Sie ihn so von Ihrem Server erhalten.
  • Im CSR kann es nicht Leerzeichen geben, Zeilenenden oder Absatzumbrüche, die Zeilen beenden Sie mit der „escape Sequenz“ rn.
  • Den CSR können Sie in die richtige Form einfach mit einem Klick anpassen – mit dem Tool Remove or Replace line breaks. Wählen Sie die Option Replace line breaks with customer text und als Custom text geben Sie rn ein. Andere Möglichkeiten deaktivieren Sie und klicken Sie auf den grünen Button unten.

FAQ für manuelle API-Nutzung