---
title: ドキュメント生成
description: "テンプレートとレコードからドキュメントができます。生成はキューに入り、状態をポーリングし、ダウンロードは回収できない短命の署名付き URL です。"
---

ここのすべてのエンドポイントは `documents` モジュールを必要とします。生成は**非同期**です。この API で書き込みが作業を完了させない唯一のモジュールです。

## 先にストレージの設定が必要

まず前提として、ドキュメントのストレージが設定されていないワークスペースは生成を `document_storage_unconfigured` で拒否します。これは管理者の設定でクライアントが整えられるものではないため、一時的な失敗ではなく前提条件として扱ってください。

## テンプレートはオブジェクトに紐づく

[`POST /document-templates`](/ja/reference/documents/post-api-v1-document-templates) は `name`、ドキュメントの出力元となる `objectId`、`layout`、`version` を取ります。

**テンプレートはそのオブジェクトが持つフィールドしか指定できません。** 存在しないフィールドを参照するレイアウトは、出力時ではなく作成時に `template_field_unavailable` を返します。壊れたテンプレートが保存されて後で見つかることはありません。

## 生成はキューであり、レスポンスではない

[`POST /documents`](/ja/reference/documents/post-api-v1-documents) は `templateId`、`recordId`、レコードの `revision` を取ります。作業を**キューに入れ**、すぐに応答します。

`revision` はどのバージョンのレコードを出力するかを固定します。承認が承認者の読む内容を固定するのと同じです。つまりドキュメントは、ファイルを開いた時点ではなく生成を依頼した時点のレコードを示します。

`template_revision_mismatch` は、テンプレートを読んでからドキュメントを依頼するまでの間にテンプレートが変わったことを意味します。テンプレートを読み直して再度依頼してください。

## 結果のポーリング

[`GET /documents/{id}`](/ja/reference/documents/get-api-v1-documents-by-id) は `pending`・`ready`・`failed` のいずれかの `status` を、`inputHash` と（出力がある場合は）`outputHash` とともに返します。

**`ready` か `failed` になるまでポーリングしてください。** コールバックもストリーミングもありません。`pending` は待ち続けることを意味します。2 つのハッシュは、同じ入力からの再出力と新しい出力をクライアントが区別する手段です。

## 再試行とダウンロード

[`POST /documents/{id}/retry`](/ja/reference/documents/post-api-v1-documents-by-id-retry) は `failed` のドキュメント専用です。`pending` や `ready` のものは `document_not_failed` で拒否されるため、**再試行が進行中の作業を巻き戻したり完成したファイルを捨てたりすることはありません**。

[`POST /documents/{id}/download`](/ja/reference/documents/post-api-v1-documents-by-id-download) は**短命の署名付き URL** を返します。そこから 2 つのことが導かれます。

- `ready` でないドキュメントには署名する対象がなく、`document_not_ready` を返します。
- **リンクは回収できません。** 一度発行されると、誰が持っていても有効期限まで使えます。そのファイル 1 つに対するベアラー資格情報として扱ってください。ログに出さず、第三者が読めるリダイレクトに入れず、事前にではなく利用者が求めた瞬間に発行してください。

`GET` ではなく `POST` なのは、資格情報の発行が読み取りではなく操作だからです。

## 1 つのスコープが 4 つのエンドポイントを覆う

`documents.read` はテンプレートの一覧、`documents.manage` はその作成ですが、**生成・状態の読み取り・再試行・ダウンロードはすべて `documents.generate` を必要とします。** 完成したファイルを取得するためのより狭いスコープはないため、ダウンロードできるトークンは生成もできます。