# Anfragen und Antworten

Die Form, die jeder Aufruf teilt: eine Anfrage als Multipart-Formular, eine Antwort, die das Dokument ist, und kein Zustand dazwischen.

Jede Aktion der API teilt denselben Vertrag. Sie senden eine Anfrage vom Typ
`multipart/form-data` mit Ihrem PDF im Feld `file` und erhalten das verarbeitete
Dokument als Antworttext zurück. Es gibt keinen Auftrag abzufragen, keinen
Schritt zum Hochladen und danach keine Ressource aufzuräumen: eine Anfrage
hinein, ein Dokument heraus. Lernen Sie diese Form einmal, und jede Seite einer
Aktion liest sich gleich.

## Jede Anfrage sieht gleich aus

Jede Aktion ist ein einzelnes `POST` an `/v1/<action>` mit einem Anfragetext vom
Typ `multipart/form-data`. Drei Dinge sind immer vorhanden:

- Der Header `X-API-Key`, der Ihren geheimen Schlüssel trägt, über HTTPS.
- Ein Teil `file`, der das PDF-Eingabedokument enthält.
- Null oder mehr Teile mit Zeichenketten für die Optionen der Aktion, zum
  Beispiel `line_1` oder `pages`, genau so benannt, wie die Referenz der Aktion
  sie auflistet.

Hier eine vollständige Anfrage, die ein Wasserzeichen aufbringt, als reines HTTP
dargestellt:

```http
POST /v1/add_text_watermark HTTP/1.1
Host: api.pdfblocks.com
X-API-Key: your_api_key
Content-Type: multipart/form-data; boundary=----PdfBlocksBoundary

------PdfBlocksBoundary
Content-Disposition: form-data; name="file"; filename="input.pdf"
Content-Type: application/pdf

%PDF-1.7
<binary PDF bytes>
------PdfBlocksBoundary
Content-Disposition: form-data; name="line_1"

CONFIDENTIAL
------PdfBlocksBoundary--
```

Teil für Teil gelesen:

- **Anfragezeile**: `POST /v1/add_text_watermark`. Der Name der Aktion ist der
  Pfad, die Methode ist immer `POST`.
- **`X-API-Key`**: Ihr Schlüssel authentifiziert die Anfrage. Siehe
  [Authentifizierung](/docs/api/authentication).
- **`Content-Type`**: `multipart/form-data` mit einer Grenzzeichenkette. Die
  Multipart-Hilfe jedes HTTP-Clients setzt diesen Header und die Grenze für Sie;
  von Hand schreiben Sie ihn selten.
- **Der Teil `file`**: das PDF-Eingabedokument, binär gesendet.
- **Teile für Optionen**: ein Teil pro Option, hier `line_1`. Jeder ist ein
  einfacher Zeichenkettenwert.

Diesen Anfragetext bauen Sie nie selbst zusammen. Der HTTP-Client jeder Sprache
erstellt ihn aus einem Datei-Handle und ein paar Feldern. Dieselbe Anfrage in
cURL:

```bash title="cURL"
curl https://api.pdfblocks.com/v1/add_text_watermark \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F line_1='CONFIDENTIAL' \
  -o watermarked.pdf
```

<Info>
  Die voreingestellte Basis-URL ist `https://api.pdfblocks.com`. Um die
  Verarbeitung in einer bestimmten Rechtsordnung zu halten, tauschen Sie den
  Host gegen einen regionalen aus. Siehe
  [Regionen und Datenresidenz](/docs/api/regions-and-data-residency). Nur der
  Host ändert sich; Pfad, Header und Anfragetext sind überall identisch.
</Info>

## Jede Antwort ist das Dokument

Eine Aktion mit einer einzelnen Ausgabe antwortet mit `200 OK` und dem
verarbeiteten PDF als reinem Antworttext:

```http
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 48213

%PDF-1.7
<binary PDF bytes>
```

Der Antworttext ist das fertige Dokument, kein JSON, das eine URL umschließt,
und keine base64-Zeichenkette. Verarbeiten Sie ihn als Stream direkt in eine Datei, oder geben
Sie ihn an den nächsten Schritt Ihrer Pipeline weiter. In cURL ist das oben das
`-o watermarked.pdf`; im Code ist es das Schreiben der Bytes von `response` auf
die Festplatte, genau wie es die Beispiele auf jeder Seite einer Aktion tun.

## Bewusst *stateless*

Die API speichert nichts. Ihr Dokument wird im Arbeitsspeicher verarbeitet, in
der Region, die Sie ansprechen, und verworfen, sobald die Antwort geschrieben
ist. Es gibt keine Dokument-ID, auf die Sie später verweisen könnten, und keine
serverseitige Kopie zum Löschen. Da zwischen den Aufrufen nichts bestehen
bleibt, muss jede Anfrage ihre eigene Eingabe `file` mitführen, auch wenn Sie
Aktionen verketten und die Ausgabe eines Aufrufs direkt in den nächsten geben
(siehe [Aktionen verketten](/docs/api/chaining-actions)).

## Wo der Vertrag variiert

Drei Dinge setzen auf dieser Grundlage auf, jedes auf einer eigenen Seite
dokumentiert:

- **Mehr als eine Eingabe.**
  [Dokumente zusammenführen](/docs/api/merge-pdf-documents) nimmt ein geordnetes
  Array von Teilen `file` entgegen, und
  [Bildwasserzeichen hinzufügen](/docs/api/add-image-watermark-to-pdf) nimmt
  einen zweiten binären Teil `image` entgegen. Beides ist unter
  [Mit Dateien arbeiten](/docs/api/working-with-files) beschrieben.
- **Mehr als eine Ausgabe.** Die Familie der Aktionen zum Aufteilen gibt mehrere
  Dokumente zurück, und Sie wählen die Verpackung (ZIP, JSON oder Multipart) mit
  dem Header `Accept`. Siehe
  [Antwortformate](/docs/api/response-formats).
- **Fehlschläge.** Jeder Fehler gibt einen Antworttext vom Typ
  `application/problem+json` gemäß RFC 7807 zurück, niemals ein unvollständiges
  PDF. Siehe [Fehler](/docs/api/errors).