Grundlagen der JSON-und XML-API
Alle wichtigen Informationen für die Nutzung der JSON- und XML-API finden Sie unter den folgenden Links:
Prozessübersicht
Ablaufdiagramm

Auftragstyp | Code | Route |
---|
ContactCreate | 400201 | POST /sslcontact |
CertificatePrepareOrder | 400110 | POST /certificate/_prepareOrder |
CertificateCreate | 400101 | POST /certificate |
PollInfo | 0905 | GET /poll |
PollConfirm | 0906 | PUT /poll/$id |
CertificateInfo | 400104 | GET /certificate/$id |
DNS-Validierung
Die DNS-Validierung, also die Validierung durch Zonen-Eintrag, wird von vielen domain-validierten Zertifikaten unterstützt. Dafür müssen Sie für manche CAs in der zum Zertifikats-Namen gehörenden Zone einen bestimmter TXT- oder CNAME-Record hinterlegen. Dieser wird von der austellenden Zertifikats-Stelle auf Gültigkeit geprüft. Wird die dazugehörige Zone von InterNetX verwaltet, erfolgt die Provisionierung der Zone automatisch.
Vorbereitung
SSLManager mit AutoDNS verbinden
Für die automatische Provisionierung der Zone, müssen Sie einmalig den SSLManager mit Ihrem AutoDNS Zugang verbinden.
Gehen Sie im SSL Manager zu den Benutzereinstellungen und klicken Sie auf den Menüpunkt SSL Manager mit dem Domain-Verwaltungssystem verbinden. Sie werden dann auf die AutoDNS Login-Seite geleitet.
Geben Sie hier zum Herstellen der Verbindung Ihre AutoDNS Zugangsdaten ein.

Kontakt anlegen
Für die Bestellung eines QuickSSLPremium Zertifikats wird ein technischer und administrativer Kontakt benötigt. Sie können bereits vorhandene Kontakte verwenden oder neue Kontakte anlegen. Sie können neu angelegte Kontakte für zukünftige Bestellungen verwenden.
POST /sslcontact
{
"fname": "John",
"lname": "Doe",
"phone": "+49-123-12345",
"fax": "+49-123-12345",
"email": "john.doe@example.com",
"title": "Admin",
"organization": "Company",
"address": "123 Main Street",
"pcode": "12345",
"city": "Anytown",
"country": "DE",
"state": "BY"
}
{
"stid": "20180926-stid",
"status": {
"code": "S400201",
"text": "Kontakt wurde erfolgreich angelegt.",
"type": "SUCCESS"
},
"object": {
"type": "contact",
"value": "100"
},
"data": [
{
"fname": "John",
"lname": "Doe",
"phone": "+49-123-12345",
"email": "john.doe@example.com",
"title": "Admin",
"organization": "Company",
"address": "123 Main Street",
"pcode": "12345",
"city": "Anytown",
"country": "DE",
"state": "BY",
"owner": {
"user": "user",
"context": 9
},
"id": 100
}
]
}
<request>
<auth>
<user>USER</user>
<context>CONTEXT</context>
<password>PASSWORD</password>
</auth>
<task>
<code>400201</code>
<contact>
<first>Michael</first>
<last>Mustermann</last>
<phone>+49-941-1234560</phone>
<email>michael.mustermann@example.com</email>
<title>Admin</title>
<organization>Beispiel GmbH</organization>
<address>Maximilianstrasse 36000</address>
<postal_code>93047</postal_code>
<city>Regensburg</city>
<country>DE</country>
<state>Bayern</state>
</contact>
</task>
</request>
<response>
<result>
<data/>
<status>
<code>S400201</code>
<text>Kontakt wurde erfolgreich angelegt.</text>
<type>success</type>
<object>
<type>contact</type>
<value>100</value> <!-- Die ID des angelegten Kontaktes -->
</object>
</status>
</result>
</response>
Ein QuickSSLPremium Zertifikat bestellen
DNS-Record erzeugen und CSR prüfen
QuickSSLPremium Zertifikate werden durch TXT-Einträge verifiziert. Dafür muss in der zum Common-Name (CNAME) gehörenden Zone ein neuer TXT-Record mit bestimmten Werten hinterlegt werden.
Beispiel TXT :
example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"
Mit dem Auftragstyp CertificatePrepareOrder wird der bereitgestellte CSR-Schlüssel geprüft (z.B. auf die richtige Bit-Länge) und es werden die benötigten Authentifizierungsdaten erzeugt.
CertificateOrderPrepare Beispiel
POST /certificate/_prepareOrder
{
"plain": "----BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----",
"product": "QUICKSSLPREMIUM"
}
{
"stid": "20180926-stid",
"status": {
"code": "S400110",
"text": "CSR-Schlüssel wurde erfolgreich geprüft.",
"type": "SUCCESS"
},
"data": [
{
"plain": "-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----",
"name": "example.com",
"keySize": 2048,
"countryCode": "DE",
"state": "BY",
"city": "Regensburg",
"organization": "Company GmbH",
"organizationUnit": "Entwicklung",
"product": "QUICKSSLPREMIUM",
"authentication": [
{
"method": "EMAIL",
"approverEmails": [
"admin@example.com",
"administrator@example.com",
"hostmaster@example.com",
"webmaster@example.com",
"postmaster@example.com"
]
},
{
"method": "DNS",
"dns": "example.com.\t\t300\tIN\tTXT\t\"2018092608362142n4sbul8rv8ttv7zkhjgzvyim8n1kpa9lys0uqdszxzs0pa0l\""
},
{
"method": "FILE"
}
],
"algorithm": "RSA",
"signatureHashAlgorithm": "SHA256"
}
]
}
<request>
<auth>
<user>USER</user>
<context>CONTEXT</context>
<password>PASSWORD</password>
</auth>
<task>
<code>400110</code>
<certificate_request>
<plain><![CDATA[----BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----]]></plain>
<product>QUICKSSLPREMIUM</product>
</certificate_request>
</task>
</request>
<response>
<result>
<data>
<certificate_request>
<plain><![CDATA[-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----]]></plain>
<name><![CDATA[example.com]]></name>
<key_size>2048</key_size>
<country_code>DE</country_code>
<state><![CDATA[Bayern]]></state>
<city><![CDATA[Regensburg]]></city>
<organization><![CDATA[Company GmbH]]></organization>
<organization_unit>Entwicklung</organization_unit>
<email>email@example.com</email>
<product>QUICKSSLPREMIUM</product>
<authentication>
<method>DNS</method>
<dns>example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"</dns>
<provisioning>1</provisioning>
</authentication>
<authentication>
<method>FILE</method>
<file_name><![CDATA[http://example.com/.well-known/pki-validation/fileauth.txt]]></file_name>
<file_content><![CDATA[201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q]]></file_content>
</authentication>
<algorithm>RSA</algorithm>
<signature_hash_algorithm>SHA256</signature_hash_algorithm>
</certificate_request>
</data>
<status>
<code>S400110</code>
<text>CSR-Schlüssel wurde erfolgreich geprüft.</text>
<type>success</type>
</status>
</result>
<stid>20170407-app1-3562</stid>
</response>
Zertifikat bestellen
Mit dem Auftragstyp CertificateCreate senden Sie die eigentliche Bestellung ans System. Dabei müssen Sie bestimmte Werte setzen:
- Kontakt: Geben Sie die Kontakt-ID der geforderten Kontakte an. Bei QuickSSLPremium sind dies der administrative Kontakt und der technische.
- Name: Der Name des Zertifikates
- Produkt: Der Wert für QuickSSLPremium ist QUICKSSLPREMIUM
- Authentifizierung: Die generierten Authentifizierungsdaten
- Laufzeit: Geben Sie eine für das Zertifikat zulässige Laufzeit an. Bei QuickSSLPremium sind dies 12 oder 24 Monaten
- Software: Wählen Sie APACHESSL oder IIS5 aus
- CSR: Der zum Zertifikat gehörende CSR
CertificateCreate Beispiel
POST /certificate
{
"adminContact": {
"id": 100
},
"technicalContact": {
"id": 100
},
"name": "example.com",
"lifetime": {
"unit": "MONTH",
"period": 12
},
"software": "APACHESSL",
"csr": "-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----",
"product": "QUICKSSLPREMIUM",
"authentication": {
"method": "DNS",
"dns": "example.com.\t\t300\tIN\tTXT\t\"2018092608362142n4sbul8rv8ttv7zkhjgzvyim8n1kpa9lys0uqdszxzs0pa0l\"",
"provisioning": true
}
}
{
"stid": "20180926-stid",
"status": {
"code": "N400101",
"text": "Zertifikatsauftrag wurde erfolgreich gestartet. ",
"type": "NOTIFY"
},
"object": {
"type": "Certificate",
"value": "example.com"
},
"data": [
{
"id": 123456
}
]
}
<request>
<auth>
<user>USER</user>
<password>PASSWORD</password>
<context>CONTEXT</context>
</auth>
<task>
<code>400101</code>
<certificate>
<technical>
<id>100</id>
</technical>
<admin>
<id>100</id>
</admin>
<name>example.com</name>
<product>QUICKSSLPREMIUM</product>
<authentication>
<method>DNS</method>
<dns>example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"</dns>
<provisioning>1</provisioning>
</authentication>
<lifetime>12</lifetime>
<software>APACHESSL</software> <!-- APACHESSL / IIS5 -->
<csr><![CDATA[---------BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----]]></csr> <!-- Der CSR KEY -->
</certificate>
</task>
</request>
<response>
<result>
<data>
<certificate_job>
<job>
<id>123456</id><!-- Die ID des angelegten Jobs -->
<status>RUNNING</status><!-- Der Status des angelegten Jobs -->
</job>
</certificate_job>
</data>
<status>
<code>N400101</code><!-- Beschreibt den Status des Tasks -->
<text>Zertifikatsauftrag wurde erfolgreich gestartet. </text>
<type>notify</type><!-- Beschreibt den Status des Tasks -->
<object>
<type>certificate</type>
<value>example.com</value><!-- Der Name des Zertifikats -->
</object>
</status>
</result>
<stid>20170407-app1-3762</stid>
</response>
Auftragsbenachrichtigungen abfragen und bestätigen
Der Auftragstyp CertificateCreate erzeugt automatisch einen Auftrag für die Bestellung des Zertifikats. Ist der Auftrag abgearbeitet, wird eine Auftragsbenachrichtigung generiert, mit Informationen über den Auftrag. Diese können Sie über den Auftragstyp PollInfo abfragen.
War der Auftrag erfolgreich, so erhalten Sie unter anderem die ID des bestellten Zertifikates. Abschließend müssen Sie den Auftrag mit PollConfirm bestätigen.
PollInfo Beispiel
{
"stid": "20180926-stid",
"status": {
"code": "S0905",
"text": "Die Benachrichtigung wurde erfolgreich abgerufen.",
"type": "SUCCESS"
},
"object": {
"type": "message",
"value": "1405448",
"summary": 2
},
"data": [
{
"id": 1405448,
"job": {
"created": "2018-12-11T15:10:43.000+0100",
"updated": "2018-12-11T15:10:55.000+0100",
"status": "SUCCESS",
"execution": "2018-12-11T15:10:42.000+0100",
"id": 9218718,
"type": "ssl",
"subType": "QUICKSSLPREMIUM",
"action": "create"
},
"stid": "20180926-stid",
"object": {
"type": "Certificate",
"value": "example.com",
"data": {
"created": "2018-12-11T00:00:00.000+0100",
"id": 570,
"orderId": "2742528",
...
}
}
}
]
}
<request>
<auth>
<user>USER</user>
<context>CONTEXT</context>
<password>PASSWORD</password>
</auth>
<task>
<code>0905</code>
</task>
</request>
<response>
<result>
<data>
<summary>1</summary>
<message>
<id>650664</id><!-- Die ID der PollMessage -->
<owner>
<user>USER</user>
<context>CONTEXT</context>
</owner>
<job>
<certificate>
...
<id>1485</id><!-- Die ID des Zertifikats -->
...
</certificate>
<job_id>536396</job_id><!-- Die ID des Jobs -->
<status>
<code>S400101</code><!-- Zeigt an ob der Task CertifikateCreate erfolgreich war oder nicht -->
<type>success</type>
<object>
<type>ssl</type>
<value>example.com</value><!-- Der Name des Zertifikats -->
</object>
</status>
</job>
</message>
</data>
<status>
<code>S0905</code>
<text>Die Benachrichtigung wurde erfolgreich versendet.</text>
<type>success</type>
<object>
<type>message</type>
<value>650664</value>
</object>
</status>
</result>
<stid>20181211-app1-3572</stid>
</response>
PollConfirm Beispiel
{
"stid": "20180926-stid",
"status": {
"code": "S0906",
"text": "Die Benachrichtigung wurde erfolgreich bestätigt.",
"type": "SUCCESS"
},
"object": {
"type": "message",
"value": "1819853"
}
}
<request>
<auth>
<user>USER</user>
<context>CONTEXT</context>
<password>PASSWORD</password>
</auth>
<task>
<code>0906</code>
<message>
<id>650664</id>
</message>
</task>
</request>
<response>
<result>
<data>
<summary>0</summary>
<message>
<id>650664</id>
</message>
</data>
<status>
<code>S0906</code>
<text>Die Benachrichtigung wurde erfolgreich versendet.</text>
<type>success</type>
<object>
<type>message</type>
<value>650664</value>
</object>
</status>
</result>
<stid>20181211-app1-3762</stid>
</response>
Zertifikats-Daten ermitteln
Der Auftragstyp CertificateInfo ermittelt alle Zertifikats-Daten. Die Daten können mit Hilfe der ID aus dem Schritt Auftrags-Benachrichtigungen abfragen und bestätigen abgefragt werden.
CertificatInfo - Beispiel
{
"stid": "20180926-stid",
"status": {
"code": "S400104",
"text": "Zertifikatsdaten wurden erfolgreich ermittelt.",
"type": "SUCCESS"
},
"object": {
"type": "Certificate",
"value": "example.com"
},
"data": [
{
"created": "2018-09-26T00:00:00.000+0200",
"updated": "2018-09-26T11:38:08.000+0200",
"id": 13258,
"owner": {
"user": "user",
"context": 9
},
"orderId": "2695961",
"adminContact": {
"id": 100
...
},
"technicalContact": {
"id": 100
...
},
"name": "example.com",
"lifetime": {
"unit": "MONTH",
"period": 12
},
"software": "APACHESSL",
"csr": "-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----",
"server": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----\n",
"serialNumber": "750C3006B23B90D0F396A3D153EB4C8",
"product": "QUICKSSLPREMIUM",
"expire": "2019-09-26T12:00:00.000+0200",
"authentication": {
"method": "DNS",
"dns": "example.com.\t\t300\tIN\tTXT\t\"2018092608362142n4sbul8rv8ttv7zkhjgzvyim8n1kpa9lys0uqdszxzs0pa0l\"",
"provisioning": true
},
"certificateTransparencyPrivacy": "PUBLIC",
"domain": "example.com"
}
]
}
<request>
<auth>
<user>USER</user>
<context>CONTEXT</context>
<password>PASSWORD</password>
</auth>
<task>
<code>400104</code>
<certificate>
<id>100</id>
</certificate>
</task>
</request>
<response>
<result>
<data>
<certificate>
<order_id>1003396954</order_id>
<technical>
<first>Michael</first>
<last>Mustermann</last>
<phone>+49-941-1234560</phone>
<email>michael.mustermann@example.com</email>
<title>Admin</title>
<organization>Beispiel GmbH</organization>
<address>Maximilianstrasse 36000</address>
<postal_code>93047</postal_code>
<city>Regensburg</city>
<country>DE</country>
<state>Bayern</state>
<owner>
<user>USER</user>
<context>CONTEXT</context>
</owner>
<updater>
<user>USER</user>
<context>CONTEXT</context>
</updater>
<id>20398</id>
<created>2017-01-01 10:35:22</created>
<updated>2017-01-01 01:05:07</updated>
</technical>
<admin>
<first>Michael</first>
<last>Mustermann</last>
<phone>+49-941-1234560</phone>
<email>michael.mustermann@example.com</email>
<title>Admin</title>
<organization>Beispiel GmbH</organization>
<address>Maximilianstrasse 36000</address>
<postal_code>93047</postal_code>
<city>Regensburg</city>
<country>DE</country>
<state>Bayern</state>
<owner>
<user>USER</user>
<context>CONTEXT</context>
</owner>
<updater>
<user>USER</user>
<context>CONTEXT</context>
</updater>
<id>20398</id>
<created>2017-01-01 10:35:22</created>
<updated>2017-01-01 01:05:07</updated>
</admin>
<name>example.com</name><!-- Der Name des Zertifikats -->
<lifetime>12</lifetime><!-- Die Laufzeit des Zertifikats -->
<software>APACHE2</software>
<csr><![CDATA[----BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----]]></csr>
<server><![CDATA[----BEGIN CERTIFICATE ----- .... -----END CERTIFICATE-----]]></server>
<serial_number>SERIALNUMBER</serial_number>
<product>QUICKSSLPREMIUM</product>
<sha>SHA2</sha>
<expire>2030-01-01 23:59:59</expire><!-- Das Expire Datum des Zertifikats -->
<extension />
<certification_authority>
<ca_type>ICA1</ca_type>
<ca_cert><![CDATA[----BEGIN CERTIFICATE ----- .... -----END CERTIFICATE-----]]></ca_cert>
</certification_authority>
<authentication>
<method>DNS</method>
<dns>example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"</dns>
</authentication>
<owner>
<user>USER</user>
<context>CONTEXT</context>
</owner>
<updater>
<user>USER</user>
<context>CONTEXT</context>
</updater>
<id>100</id><!-- Die ID des Zertifikats -->
<created>2017-01-01 00:00:00</created>
<updated>2017-01-01 14:30:36</updated>
</certificate>
</data>
<status>
<code>S400104</code>
<text>Zertifikatsdaten wurden erfolgreich ermittelt.</text>
<type>success</type>
<object>
<type>certificate</type>
<value>example.com</value><!-- Der Name des Zertifikats -->
</object>
</status>
</result>
<stid>20181211-app1-3892</stid>
</response>