# リクエストとレスポンス

すべての呼び出しが共有する形：multipart 形式のリクエスト、ドキュメントとして返るレスポンス、そして両者の間に保持されない状態。

API 内のすべてのアクションは1つの契約を共有しています。PDF を `file` フィールドに入れて `multipart/form-data` リクエストを送信すると、処理済みのドキュメントがレスポンス本文として返ってきます。ポーリングするジョブも、アップロードの手順も、後片付けが必要なリソースもありません。1つのリクエストが入り、1つのドキュメントが出てくるだけです。この形を一度学べば、どのアクションページも同じように読めます。

## リクエストの形はすべて同じ

各アクションは、`multipart/form-data` 形式の本文を持つ、`/v1/<action>` への単一の `POST` です。次の3つは常に存在します。

- シークレットキーを運ぶ `X-API-Key` ヘッダー（HTTPS 経由）。
- 入力 PDF を含む `file` パート。
- アクションのオプション用の文字列パートが0個以上（例えば `line_1` や `pages`）。アクションリファレンスに記載されている名前と正確に一致させます。

透かしを付与する完全なリクエストを、生の HTTP として示します。

```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--
```

パートごとに見ていきます。

- **リクエスト行**：`POST /v1/add_text_watermark`。アクション名がパスになり、メソッドは常に `POST` です。
- **`X-API-Key`**：あなたのキーがリクエストを認証します。詳細は [認証](/docs/api/authentication) を参照してください。
- **`Content-Type`**：バウンダリ文字列を伴う `multipart/form-data`。HTTP クライアントの multipart ヘルパーがこのヘッダーとバウンダリを自動的に設定するため、手書きすることはほとんどありません。
- **`file` パート**：バイナリとして送信される入力 PDF。
- **オプションのパート**：オプションごとに1パート、ここでは `line_1`。それぞれが単純な文字列値です。

その本文を自分で組み立てることはありません。どの言語の HTTP クライアントも、ファイルハンドルといくつかのフィールドから本文を構築します。同じリクエストを 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>
  デフォルトのベース URL は `https://api.pdfblocks.com` です。処理を特定の法域にとどめるには、ホストをリージョン別のものに入れ替えてください。詳細は [リージョンとデータの保存地域](/docs/api/regions-and-data-residency) を参照してください。変わるのはホストだけで、パス、ヘッダー、本文はどこでも同じです。
</Info>

## すべてのレスポンスはドキュメントそのもの

単一出力のアクションは `200 OK` で応答し、処理済みの PDF を生の本文として返します。

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

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

本文は完成したドキュメントであり、URL を包んだ JSON でも base64 文字列でもありません。ファイルへ直接ストリーミングするか、パイプラインの次のステップに渡してください。cURL では上記の `-o watermarked.pdf` がそれにあたり、コードでは各アクションページの例がそうしているように、`response` のバイト列をディスクへ書き込みます。

## ステートレスな設計

この API は何も保存しません。ドキュメントは、あなたが指定したリージョンでメモリ上で処理され、レスポンスが書き込まれると同時に破棄されます。後で参照するドキュメント ID も、削除すべきサーバー側のコピーもありません。呼び出しの間に何も永続化されないため、アクションを連結する場合、つまり1つの呼び出しの出力を次の呼び出しに直接渡す場合も含めて、各リクエストは自分自身の入力 `file` を持たなければなりません（[アクションの連結](/docs/api/chaining-actions) を参照）。

## この契約が変わる場合

この基本形の上に3つの要素が乗ることがあり、それぞれ専用のページで説明しています。

- **入力が複数になる場合。** [ドキュメントを結合する](/docs/api/merge-pdf-documents) は `file` パートの順序付き配列を受け取り、[画像透かしを追加する](/docs/api/add-image-watermark-to-pdf) は2つ目のバイナリパート `image` を受け取ります。どちらも [ファイルの扱い方](/docs/api/working-with-files) で扱っています。
- **出力が複数になる場合。** 分割系のアクションは複数のドキュメントを返し、`Accept` ヘッダーで梱包形式（ZIP、JSON、multipart）を選べます。詳細は [レスポンスフォーマット](/docs/api/response-formats) を参照してください。
- **失敗する場合。** エラーは常に RFC 7807 に従う `application/problem+json` 本文を返し、途中までの PDF が返ることはありません。詳細は [エラー](/docs/api/errors) を参照してください。