Dieses Rezept ergänzt die eigentliche Zertifikatsbestellung um einen kontrollierten Überwachungs- und Abbruchpfad. Es ist besonders nützlich, wenn du Bestellungen automatisiert auslöst und hängende Aufträge nicht manuell nachverfolgen willst.

Voraussetzungen

• ein API-Key mit Zugriff auf TLS-Endpunkte
• ein gültiger CSR
• definierte Regeln, wann eine Bestellung als hängen geblieben oder fachlich ungültig gilt
• ein Job oder Worker, der Statusabfragen wiederholt ausführen kann

Schritt 1: Zertifikatsauftrag anlegen

Die Bestellung liefert dir die id, mit der du den gesamten weiteren Ablauf steuerst.

curl --request POST \
  --url 'https://api.regfish.com/tls/certificate' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "sku": "RapidSSL",
  "common_name": "www.example.com",
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----",
  "dcv_method": "dns-cname-token"
}
'

Wenn dieser Auftrag als explizite Verlängerung laufen soll, fügst du renewal_of_certificate_id hinzu. Monitoring, Timeout-Regeln und Cancel-Ablauf bleiben identisch, weil auch eine Verlängerung über denselben Endpunkt als eigene Bestellung angelegt wird.

Speichere aus der Antwort mindestens:

• id
• status
• order_state
• eventuelle Validierungsdaten

Schritt 2: Status in Intervallen abfragen

Danach pollst du den Auftrag so lange, bis er ausgestellt, eindeutig fehlgeschlagen oder fachlich überfällig ist.

curl --request GET \
  --url 'https://api.regfish.com/tls/certificate/7K9QW3M2ZT8HJ' \
  --header 'x-api-key: YOUR_API_KEY'

Typische Abbruchregeln sind zum Beispiel:

• der Auftrag bleibt zu lange in pending
• die benötigte Validierung wurde im erwarteten Zeitfenster nicht abgeschlossen
• ein nachgelagerter Prozess entscheidet, dass der Auftrag nicht mehr benötigt wird

Mit dem aktuellen API solltest du außerdem mitlesen:

• order_cancellable
• order_cancellation_mode
• order_cancellable_until

Schritt 3: Timeout oder Fehlerfall erkennen

Sobald deine Überwachungslogik entscheidet, dass der Auftrag nicht weiterlaufen soll, markierst du ihn intern als abzubrechen. Üblich ist hier eine Kombination aus Zeitgrenze, Statusbewertung und fachlichem Kontext.

Ein einfaches internes Entscheidungsmodell kann so aussehen:

{
  "certificate_id": "7K9QW3M2ZT8HJ",
  "maxPendingMinutes": 30,
  "cancelWhenStatusStill": "pending",
  "reason": "dcv-timeout"
}

Schritt 4: Auftrag stornieren

Im Fehler- oder Timeout-Fall storniert dein Workflow den Auftrag aktiv. So bleiben keine offenen Bestellungen im System hängen.

curl --request POST \
  --url 'https://api.regfish.com/tls/certificate/7K9QW3M2ZT8HJ/cancel' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "note": "Cancelled automatically after DCV timeout in provisioning workflow"
}
'

Diesen Pfad nutzt du für noch pendende Aufträge. Wenn die gelesene Zertifikatsantwort stattdessen einen vollständigen DigiCert-Order-Cancel oder -Revoke signalisiert, verwendest du /tls/certificate/{certificate_id}/order-cancel.

curl --request POST \
  --url 'https://api.regfish.com/tls/certificate/7K9QW3M2ZT8HJ/order-cancel' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "comment": "Order revoked automatically after policy timeout"
}
'

Schritt 5: Storno nachverfolgen

Nach dem Cancel solltest du den Auftrag noch einmal lesen, damit deine interne Auftragslage und der externe Providerzustand konsistent bleiben.

curl --request GET \
  --url 'https://api.regfish.com/tls/certificate/7K9QW3M2ZT8HJ' \
  --header 'x-api-key: YOUR_API_KEY'

Praxishinweise für produktive Abläufe

• trenne Bestellung, Polling und Storno in eigene Zustandsübergänge
• speichere die Begründung für das Canceln immer mit
• vermeide Endlosschleifen, indem du ein klares Maximalalter für offene Bestellungen definierst
• nutze Alarme nur für Ausnahmen, nicht für jeden Pending-Zustand
• halte deinen Workflow idempotent, damit ein Cancel-Job sicher erneut laufen kann

Ergebnis

Mit diesem Ablauf wird aus der bloßen Zertifikatsbestellung ein kontrollierter Lifecycle mit sauberem Timeout- und Fehlerpfad. Dasselbe gilt für Bestellungen zur expliziten Verlängerung, die über renewal_of_certificate_id erzeugt werden.