# hightrusted CAPTURE — PHP SDK

> **Status:** v0.1 Preview — API stabil, SDK in aktiver Entwicklung

Offizielles PHP-SDK für die [hightrusted CAPTURE API](https://capture.hightrusted.net) —
forensische Web-Captures mit qualifiziertem Zeitstempel nach RFC 3161 / eIDAS Art. 41.

**Made in Germany.** Server in Deutschland. DSGVO-nativ. Kein US-Cloud-Anbieter
in der Verarbeitungskette. Quelloffen unter MIT-Lizenz.

## Was die CAPTURE API tut

Sie nimmt eine URL entgegen, rendert die Seite vollständig (inkl. JavaScript),
liefert sie als PDF/A zurück und versieht das Ergebnis mit einem qualifizierten
Zeitstempel. Das Ergebnis ist gerichtsverwertbar und Jahre später noch
verifizierbar — auch nachdem die Original-Seite längst offline ist.

Anwendungsfälle: Markenrechtsverletzungen dokumentieren, Auftragsbedingungen
zum Buchungszeitpunkt sichern, Compliance-Nachweise für Behörden, Beweissicherung
durch Anwälte und Sachverständige.

## Installation

```bash
composer require hightrusted/capture
```

## Quickstart

```php
<?php
use Hightrusted\Capture\Client;

$client = new Client(['api_key' => 'ht_live_...']);

// Synchron — wartet bis zu 30 s auf das fertige PDF
$capture = $client->capture(['url' => 'https://example.com']);

echo $capture->id . PHP_EOL;
echo $capture->verifyUrl . PHP_EOL;
echo $capture->timestamp->issuedAt . PHP_EOL;

// PDF herunterladen
$capture->download('./beweis.pdf');
```

## Authentifizierung

Bearer-Token mit API-Key. Key-Erzeugung im Dashboard:
https://capture.hightrusted.net/dashboard/api-keys

```php
// API-Key direkt
$client = new Client(['api_key' => 'ht_live_...']);

// oder über Umgebungsvariable HIGHTRUSTED_API_KEY
$client = new Client();
```

## Asynchrone Captures + Webhooks

```php
$job = $client->captureAsync([
    'url'         => 'https://example.com',
    'webhook_url' => 'https://your-app.tld/webhooks/capture',
]);
// $job->status === 'queued'

// später, sobald der Webhook capture.ready geliefert hat:
$capture = $client->get($job->id);
$capture->download('./beweis.pdf');
```

## Verify

```php
$result = $client->verify('cap_...');
echo $result->valid ? 'OK' : 'INVALID';   // OK
echo $result->timestamp;                   // 2026-04-25T11:29:40Z
```

## Rate Limits

Limits werden pro API-Key gemessen. Bei Überschreitung: HTTP 429 mit
`Retry-After`-Header. Das SDK respektiert den Header automatisch und retried.

| Plan      | req/min | Calls/Monat |
|-----------|---------|-------------|
| Developer | 5       | 100         |
| Starter   | 30      | 300         |
| Growth    | 120     | 2.000       |
| Scale     | 600     | 10.000      |

## Voraussetzungen

- PHP 8.1 oder höher
- `ext-curl`, `ext-json`
- `guzzlehttp/guzzle` (wird via Composer installiert)

## Entwicklung

```bash
git clone ssh://git@git.hightrusted.net:2222/hightrusted-capture/php.git
cd php
composer install
vendor/bin/phpunit
```

## Roadmap

- [ ] v0.1 — Basis-Client, Verify, Download
- [ ] v0.2 — Retry-Logik, Webhook-Signatur-Verifikation, PSR-18-kompatibel
- [ ] v0.3 — Laravel Service-Provider als separates Package
- [ ] v1.0 — Stabile API, semantische Versionierung

## Verwandte Repositorys

**Im selben Produkt** ([`hightrusted-capture`](https://git.hightrusted.net/hightrusted-capture)):

- [`openapi`](https://git.hightrusted.net/hightrusted-capture/openapi) — OpenAPI 3.1 Spec (Single Source of Truth)
- [`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

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

- [`platform`](https://git.hightrusted.net/hightrusted/platform) — Plattform-Übersicht, Architektur, Produkt-Liste
- [`developer-portal`](https://git.hightrusted.net/hightrusted/developer-portal) — gemeinsame Konventionen, Auth, Errors, Rate-Limits
- [`compliance`](https://git.hightrusted.net/hightrusted/compliance) — DSGVO, AGB-Templates, Whitepaper

## Support

- **Doku:** https://capture.hightrusted.net/api/docs
- **Status-Page:** https://status.hightrusted.net
- **Developer Support:** developers@hightrusted.net
- **Sicherheitslücken:** siehe [SECURITY.md](./SECURITY.md)

## Lizenz

MIT — siehe [LICENSE](./LICENSE).

---

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