openapi/README.md

hightrusted CAPTURE — OpenAPI Specification

Status: v1.0.0 — Single Source of Truth für alle SDKs

OpenAPI 3.1 Spezifikation der hightrusted CAPTURE API — forensische Web-Captures mit qualifiziertem Zeitstempel nach RFC 3161 / eIDAS Art. 41.

Diese Spec ist die maschinenlesbare Referenz, aus der wir alle anderen Artefakte ableiten: SDKs, Client-Bibliotheken, Postman-Collection, gerenderte Doku.

Made in Germany. Server in Deutschland. DSGVO-nativ.

Inhalt

• openapi.yaml — die OpenAPI 3.1 Spec
• CHANGELOG.md — Versions-History

Validieren

# Mit redocly cli
npx @redocly/cli lint openapi.yaml

# Oder mit spectral
npx @stoplight/spectral-cli lint openapi.yaml

Doku rendern

# HTML-Doku mit Redoc bauen
npx @redocly/cli build-docs openapi.yaml -o ./docs/index.html

# Mit Swagger UI lokal anzeigen
npx swagger-ui-watcher openapi.yaml

Client-Generierung

Aus dieser Spec lassen sich automatisch Clients für 50+ Sprachen erzeugen:

npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g go \
  -o ./clients/go

Wir pflegen offizielle Clients handgeschrieben für Python, Node.js und PHP — sie sind idiomatischer als generierte Clients und haben getestete Webhook-Verifikation, typisierte Exceptions und ergonomische APIs.

Endpoints (Übersicht)

Endpoint	Beschreibung	Auth
POST /captures	Capture erstellen (sync/async/webhook)	Bearer
GET /captures	Captures auflisten (paginiert)	Bearer
GET /captures/{id}	Status & Metadaten abrufen	Bearer
GET /captures/{id}/pdf	PDF herunterladen	Bearer
POST /verify	Verifizieren (per ID, URL, oder PDF)	—
GET /usage	eigenen Verbrauch abrufen	Bearer

Webhook-Events

Event	Wann
capture.ready	PDF und Zeitstempel fertig
capture.failed	Fehler beim Rendern oder TSA

Webhook-Retry: 3 Versuche mit exponentiellem Backoff (1 min, 5 min, 30 min). Signaturverifikation per HMAC-SHA-256 (X-Hightrusted-Signature: sha256=...).

Versionierung

API-Versionen sind im Pfad: /api/v1/...

• Breaking Changes → neue Major-Version (/api/v2), alte Major bleibt 24 Monate erreichbar
• Non-Breaking Changes (neue Felder, neue Endpoints) → ohne Versionssprung

Diese OpenAPI-Spec verfolgt die API 1:1. Änderungen sind in CHANGELOG.md nachvollziehbar.

Verwandte Repositorys

Im selben Produkt (hightrusted-capture):

• postman — Postman Collection
• examples — Beispiel-Anwendungen
• python — Python-SDK
• node — Node.js-SDK
• php — PHP-SDK

Plattform-übergreifend (hightrusted):

• platform
• developer-portal
• compliance

Support

• Doku: https://capture.hightrusted.net/api/docs
• Status: https://status.hightrusted.net
• Developer Support: developers@hightrusted.net

Lizenz

MIT — siehe LICENSE. Spec und Beispiele dürfen frei für eigene Implementierungen genutzt werden.

---

hightrusted GmbH — The European Trust Infrastructure. Made in Germany. DSGVO-nativ. eIDAS-konform.