Kunden-API

Dieser Artikel zeigt, wie Sie Ihren eigenen Systemen Zugriff auf Ihre Daten in Certado geben. Über die Kunden-API ruft etwa Ihr Abrechnungssystem die geprüften Geräte eines Monats ab.

Sie finden die Einstellungen im Menü unter „Konfiguration”, Reiter „Kunden-API”. Die Konfiguration steht der Rolle Administrator offen, siehe Berechtigungen.

Freischaltung

Die Kunden-API ist nicht für jedes Konto freigeschaltet. Solange sie fehlt, zeigt die Konfiguration den Reiter „Kunden-API” nicht an. Wenden Sie sich für die Freischaltung an den Certado-Support.

Wie der Zugriff funktioniert

Ihr System meldet sich bei jedem Aufruf mit einem API-Schlüssel an. Es sendet ihn im Header Authorization. Der Schlüssel steht dort nach dem Wort Bearer, also Authorization: Bearer ck_live_…. Ein Schlüssel gilt für alle Daten Ihres Kontos, unabhängig von Arbeitsbereichen. Die API ist lesend. Ihr System kann Daten abrufen, aber nichts ändern.

API-Schlüssel anlegen

1. Klicken Sie auf „Schlüssel anlegen”.
2. Geben Sie eine Bezeichnung ein, zum Beispiel „ERP Abrechnung”. Sie dient nur Ihrer eigenen Übersicht.
3. Legen Sie bei Bedarf ein Ablaufdatum (optional) fest. Der Schlüssel gilt bis zum Ende dieses Tages. Ohne Angabe läuft er nicht ab.
4. Klicken Sie auf „Anlegen”.

Die Anwendung zeigt danach den Dialog „Neuer API-Schlüssel”. Klicken Sie auf „Kopieren” und hinterlegen Sie den Schlüssel in Ihrem System.

Achtung

Der Schlüssel erscheint nur in diesem Dialog, und nur dieses eine Mal. Nach dem Schließen lässt er sich nicht mehr anzeigen. Ist er verloren, widerrufen Sie ihn und legen einen neuen an.

Ein Konto kann höchstens 10 aktive Schlüssel haben. Abgelaufene und widerrufene Schlüssel zählen nicht mit. Sind 10 aktiv, bleibt „Schlüssel anlegen” gesperrt. Widerrufen Sie dann einen Schlüssel, um einen neuen anzulegen.

Schlüssel im Überblick

Die Tabelle „API-Schlüssel” zeigt je Schlüssel diese Spalten:

• „Bezeichnung”
• „Schlüssel”, das ist der Anfang des Schlüssels
• „Status”, entweder „aktiv”, „abgelaufen” oder „widerrufen”
• „Angelegt”, mit Datum und der Person, die den Schlüssel angelegt hat
• „Läuft ab”, bei Schlüsseln ohne Ablaufdatum steht dort „nie”
• „Zuletzt genutzt”, bei ungenutzten Schlüsseln steht dort „noch nie”
• „Aufrufe (30 Tage)“, das sind die Aufrufe von heute und den 29 Tagen davor

Auch Schlüssel, die der Certado-Support für Sie angelegt hat, stehen in dieser Tabelle.

Schlüssel widerrufen

Klicken Sie in der Zeile eines aktiven Schlüssels auf den Papierkorb. Die Anwendung öffnet den Dialog „API-Schlüssel widerrufen” und fragt nach: „Systeme, die diesen Schlüssel verwenden, verlieren sofort den Zugriff. Das lässt sich nicht rückgängig machen.” Nach der Bestätigung ist der Schlüssel ungültig. Er bleibt mit dem Status „widerrufen” ausgegraut in der Tabelle stehen.

Aufrufgrenze

Je Schlüssel sind im Mittel 10 Aufrufe pro Sekunde erlaubt, kurzzeitig bis zu 50. Darüber antwortet die API mit dem Status 429. Wie lange Ihr System warten soll, nennt die Antwort im Header Retry-After. Danach wiederholt es den Aufruf. Für Abrechnungen und Auswertungen reicht die Grenze in aller Regel.

Dokumentation für Ihre IT

Die technische Dokumentation der Kunden-API finden Sie unter api.certado.app/api/public/v1/docs, auf Englisch unter api.certado.app/api/public/v1/docs?lang=en. Der Reiter „Kunden-API” verlinkt sie unter „Dokumentation der Kunden-API” ebenfalls, dazu diesen Artikel unter „Hilfeartikel”.