# hightrusted CAPTURE — OpenAPI Specification

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

OpenAPI 3.1 Spezifikation der [hightrusted CAPTURE API](https://capture.hightrusted.net) —
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

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

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

## Doku rendern

```bash
# 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:

```bash
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`](https://git.hightrusted.net/hightrusted-capture)):

- [`postman`](https://git.hightrusted.net/hightrusted-capture/postman) — Postman Collection
- [`examples`](https://git.hightrusted.net/hightrusted-capture/examples) — Beispiel-Anwendungen
- [`python`](https://git.hightrusted.net/hightrusted-capture/python) — Python-SDK
- [`node`](https://git.hightrusted.net/hightrusted-capture/node) — Node.js-SDK
- [`php`](https://git.hightrusted.net/hightrusted-capture/php) — PHP-SDK

**Plattform-übergreifend** ([`hightrusted`](https://git.hightrusted.net/hightrusted)):

- [`platform`](https://git.hightrusted.net/hightrusted/platform)
- [`developer-portal`](https://git.hightrusted.net/hightrusted/developer-portal)
- [`compliance`](https://git.hightrusted.net/hightrusted/compliance)

## Support

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

## Lizenz

MIT — siehe [LICENSE](./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.