Programmierschnittstelle

Die Schnittstelle ist für Agenturen gedacht, die Complianty an eigene Systeme anbinden: Daten ins eigene Dashboard ziehen, Prüfungen aus dem eigenen Werkzeugkasten auslösen, bei neuen Befunden automatisch ein Ticket oder eine Nachricht erzeugen. Sie liegt unter /api/v1/public und ist eine Server-zu-Server-Schnittstelle. Für den Einsatz im Browser ist sie nicht gedacht.

Eine vollständige Endpunktreferenz mit Beispielen ist ohne Konto unter /api/v1/public/docs erreichbar.

Zugang und Schlüssel

Der Zugang ist als Tarifschalter hinterlegt. Ist er aus, wird jede Anfrage abgelehnt. Schlüssel anlegen darf ausschließlich der Kontoeigentümer. Ein Schlüssel gilt immer für das gesamte Konto und würde die Einschränkung einzelner Mitarbeitender auf Mandanten sonst aushebeln.

Schlüssel beginnen mit clp_live_ beziehungsweise clp_test_ und werden genau einmal im Klartext angezeigt. Gespeichert werden nur ein Hashwert und ein nicht geheimes Anzeigefragment. Ein verlorener Schlüssel lässt sich deshalb nicht wiederherstellen, nur ersetzen. Die Authentifizierung erfolgt als Authorization: Bearer ….

Pro Schlüssel gibt es weitere Schranken: eine optionale Liste erlaubter IP-Adressen oder Netze, ein optionales Ablaufdatum, einen automatischen Widerruf lange ungenutzter Schlüssel und einen Austausch mit Übergangsfrist. Beim Austausch bleibt der alte Schlüssel kurz gültig, damit die Umstellung ohne Ausfall gelingt. Jeder authentifizierte Zugriff wird im Konto protokolliert. Aktionen an einem Mandanten erscheinen zusätzlich in dessen Compliance-Protokoll.

Rechteumfang

Jeder Schlüssel trägt eine Liste von Berechtigungen. Lesende Rechte sind die Voreinstellung. Aktionen und Schreibzugriffe müssen Sie ausdrücklich auswählen, etwa scans:read gegenüber scans:trigger oder todos:read gegenüber todos:write. Einen Sammel- oder Administratorumfang gibt es nicht. Fehlt das nötige Recht, antwortet die Schnittstelle mit 403 und der Kennung insufficient_scope.

Was abrufbar ist

Der lesende Zugriff deckt die Compliance-Daten des Kontos ab:

• Mandanten und Websites: GET /clients, GET /clients/{id}/websites
• Scans samt Verlauf und Unterseiten: GET /websites/{id}/scans, GET /scans/{id}/timeline, GET /scans/{id}/pages
• Befunde inklusive Beweisblock: GET /clients/{id}/todos
• Einzelprüfungen: GET /websites/{id}/banner-audit, /impressum-check, /ssl-check/latest, /form-check/latest, /a11y-check, jeweils auch als Historie
• Dokumente: GET /clients/{id}/vvt, /dse, /avv, /training
• Compliance-Protokoll, Dateiliste, Domain-Whitelist, Verdachtsfälle proxierter Werkzeuge, Akquise-Kontakte
• Agenturübersicht und Verbrauch: GET /dashboard, GET /usage

Listen werden über einen Cursor geblättert. Die Antwort enthält next_cursor und has_more, der Cursor verankert auf dem zuletzt gelieferten Datensatz. Die Seitengröße können Sie anfragen, der Server deckelt sie auf eine Obergrenze.

Aktionen

Prüfungen werden als Auftrag eingereiht, nicht synchron ausgeführt. POST /websites/{id}/scan und die entsprechenden Endpunkte für Banner-Audit, Impressum-, SSL-, Formular- und Barrierefreiheits-Check antworten mit 202 und einer Auftragskennung. Deren Stand fragen Sie über GET /jobs/{id} ab. Jede dieser Aktionen bucht auf dasselbe Tagesbudget des Tarifs wie die Oberfläche. Ist es erschöpft, folgt 429 mit Angabe des Rücksetzzeitpunkts.

Schreibend sind außerdem möglich: Befunde erledigen und wieder öffnen, Einträge im AVV-Tracker und Schulungsnachweise pflegen, eine Notiz ins Compliance-Protokoll schreiben, Akquise-Kontakte anlegen und übernehmen, Verarbeitungsverzeichnis und Datenschutzerklärung neu erzeugen sowie einen Datenexport anstoßen und herunterladen.

Testumgebung

Ein Schlüssel mit dem Präfix clp_test_ arbeitet gegen einen festen, erfundenen Beispieldatensatz. Er berührt die Produktivdaten nicht, löst keine echten Prüfungen aus und verbraucht kein Budget. Schreibzugriffe werden nur simuliert. So bauen Sie eine Anbindung vollständig fertig, bevor sie auf echte Mandanten losgelassen wird.

Webhooks

Statt zu pollen, hinterlegen Sie HTTPS-Adressen, an die Complianty meldet. Abonnierbar sind derzeit neun Ereignisse: scan.completed, banner_audit.completed, impressum_check.completed, ssl_check.completed, a11y_check.completed, form_check.completed, todo.created, todo.resolved und client.status_changed.

Jede Zustellung trägt die Kopfzeilen X-Complianty-Event, X-Complianty-Delivery und X-Complianty-Signature. Die Signatur ist ein HMAC mit SHA-256 über Zeitstempel und Rumpf, im Format t=…,v1=…. Das zugehörige Geheimnis wird beim Anlegen einmal angezeigt und liegt nicht im Klartext in der Datenbank. Prüfen Sie empfangsseitig immer Signatur und Zeitstempel. Nur so ist eine Wiedereinspielung alter Meldungen ausgeschlossen.

Schlägt eine Zustellung fehl, wird sie mehrfach mit wachsendem Abstand wiederholt. Antwortet ein Endpunkt dauerhaft nicht, wird er nach einer festgelegten Zahl aufeinanderfolgender Fehlschläge automatisch deaktiviert, statt endlos weiterzusenden. Ziel-Adressen müssen öffentlich erreichbar und HTTPS sein. Adressen im privaten Netz werden abgelehnt, beim Anlegen und noch einmal unmittelbar vor jedem Versand. Zum Ausprobieren gibt es eine Testzustellung.