# Referenz der Render-API

Rendern Sie API-Endpunkte, Authentifizierungsheader und Anforderungsfelder.

## Authentifizierung
Senden Sie einen `ApiKey`-Header für einen Projektschlüssel mit `template:render`. Dies ist keine Browsersitzung.

## POST /v1/pdf/render
| JSON-Feld | Bedeutung |
| --- | --- |
| `template_id` | Erforderliche Vorlagen-UUID, kein Slug |
| `version` | Versionsnummer; Wird weggelassen, wird die aktuelle Version der Vorlage ausgewählt |
| `variant` | Optionaler Variantenname |
| `parameters` | Eingabeobjekt passend zur Vorlage |

Das Ziel muss veröffentlicht werden. Beim Rendern werden festgeschriebene Inhalte verwendet, keine nicht gespeicherten Browser-Änderungen. Akzeptiert wird HTTP 202 mit `render_id`, `status: queued` und `status_url`, nicht PDF Bytes oder eine Erfolgsgarantie.

## GET /v1/renders/{render_id}
Verwenden Sie dieselbe Taste. Die Antwort umfasst `render_id`, `status` und optionale Ergebnisfelder wie `error_message`, `duration_ms` und `download_url`. Verarbeitung ist `pending`; Die Endzustände sind `success`, `failed` und `quota_exceeded`.

Unmittelbar nach einer 202-Antwort kann der Statusendpunkt kurzzeitig **404** zurückgeben, während der Workflow seine Verlaufszeile erstellt. Versuchen Sie es mit einer kurzen Verzögerung und einer begrenzten Frist erneut mit der neu akzeptierten Render-ID. Ein anhaltender 404-Fehler, eine unbekannte ID oder eine Nichtübereinstimmung zwischen Projekt und Schlüssel müssen untersucht werden. Senden Sie POST nicht erneut, nur weil die erste Statussuche 404 zurückgegeben hat.

## GET /v1/renders/{render_id}/download
Verwenden Sie einen geeigneten Projektschlüssel. Bei erfolgreicher Ausgabe werden PDF-Bytes zurückgegeben, sofern verfügbar. Es handelt sich nicht um eine permanente öffentliche URL.

## Fehler und Wiederholungsversuche
Authentifizierung, Besitz und fehlende/unveröffentlichte Versionen können vor der Annahme fehlschlagen. Spätere Verarbeitungsfehler werden über den Status angezeigt. Korrigieren Sie 4xx-Anfragen/-Berechtigungen, bevor Sie es erneut versuchen, und gehen Sie nicht davon aus, dass die öffentliche POST-Idempotenz unterstützt wird.

## Fehlerreaktion
Fehler verwenden `code`, `description` und optional `details`. Lesen Sie den Code, um zu entscheiden, was behoben werden soll. Ein akzeptiertes Rendering kann später fehlschlagen und `error_message` über den Status melden.

```json
{"code":"PDF_TEMPLATE_VERSION_NOT_PUBLISHED","description":"template version is not published","details":[]}
```

Eine erfolgreiche Statusantwort kann Folgendes umfassen:

```json
{"render_id":"<render-uuid>","status":"success","duration_ms":1200,"download_url":"/v1/renders/<render-uuid>/download"}
```

Ein Verarbeitungsfehler ist ein Statusergebnis, zum Beispiel:

```json
{"render_id":"<render-uuid>","status":"failed","error_message":"Failed to compile template"}
```

## Geltungsbereich
Diese Referenz deckt öffentliche Rendering-Endpunkte ab, nicht jede von der App verwendete Nur-Sitzungs-Verwaltung API. Umfrage mit Verzögerungen und begrenzter Frist; Behalten Sie die Render-ID nach der Annahme bei.