---
title: 承認
description: "定義が誰が何段階で承認するかを述べ、申請がそれを 1 段ずつ進み、1 件の却下で終わります。各拒否が何を意味するかを扱います。"
---

ここのすべてのエンドポイントは `approvals` モジュールを必要とします。定義は一度書き、申請はレコードに対して提出され、その段階を進みます。

## 定義は最大 3 段階

[`POST /approval-definitions`](/ja/reference/approvals/post-api-v1-approval-definitions) は `label`、適用先の `objectId`、`version`、そして `stages` を取ります。**1〜3 個**で、各段階がちょうど 1 人の承認者を指定します。

```json
{ "approverUserId": "…", "label": "部長" }
```

**すべての承認者はその組織のメンバーでなければなりません。** そうでないユーザー id は `approver_outside_organization` を返し、欠けのある定義が作られるのではなく定義全体が拒否されます。

## 提出はレコードを固定する

[`POST /approvals`](/ja/reference/approvals/post-api-v1-approvals) は `definitionId`、`recordId`、そしてレコードの `revision` を取ります。

**承認者が読む内容をスナップショットします。** 申請は `recordRevision`、レコードとその関連のスナップショット、そして `contentHash` を保存します。承認者はそのスナップショットに対して判断し、その後レコードがどう変わったかは見ません。

古いリビジョンを送ると拒否されます。最新に解決されない理由は[リビジョン](/ja/guides/concepts/revisions)にあります。

**提出者は承認者になれません。** 定義のいずれかの段階に提出者自身のユーザー id が現れる場合、提出は `approver_is_submitter` で拒否されます。検査は判断時ではなく提出時なので、自分を指名している定義は自分には使えません。

## 判断は 1 段ずつ進む

[`POST /approvals/{id}/decisions`](/ja/reference/approvals/post-api-v1-approvals-by-id-decisions) は `decision`（`approve` か `reject`）、`stage` 番号、そして任意の `comment`（最大 4,000 文字）を取ります。

**段階番号は必須で、検査されます。** 申請は `activeStage` を持ち、`stage` がその番号でない判断は `approval_stage_moved` で拒否されます。`pending` でない申請への判断も同じです。どの段階が開いているかを仮定せず、判断の前に申請を読んでください。

**指名された承認者だけが判断できます。** 段階 _n_ の承認者は `stages[n-1].approverUserId` で、それ以外（提出者を含む）は `approver_not_assigned` を受けます。

申請の `state` は 4 つのいずれかで、遷移は図を描く価値があるほど複雑ではありません。

| 判断 | 結果 |
| --- | --- |
| どの段階でも `reject` | `rejected`。**1 件の却下で申請は終わります**。残りの段階に関係なく |
| 最終段階での `approve` | `approved` |
| それより前の段階での `approve` | `pending` のまま、`activeStage` が 1 つ進む |

## 取り下げ

[`POST /approvals/{id}/withdraw`](/ja/reference/approvals/post-api-v1-approvals-by-id-withdraw) は状態を `withdrawn` にします。

**取り下げられるのは提出者だけ**で、申請が `pending` の間だけです。それ以外は `withdraw_not_submitter`、既に判断済みの申請は `approval_not_pending` を受けます。

## 承認は他の作業を止める

保留中の承認は意図の記録にとどまりません。**提出対象のレコードの編集が拒否されます**（`record_approval_pending`）。先に承認を取り下げてください。開いている承認がある見積も同様に改訂を拒否し、`quote_approval_pending` を返します。承認の提出は通知を送ることより、承認対象にロックを取ることに近いものです。

## スコープは 1 つではなく 4 つ

| スコープ           | 対象                                          |
| ------------------ | --------------------------------------------- |
| `approvals.read`   | 定義・申請・判断の一覧                        |
| `approvals.manage` | 定義の作成。管理者のみ                        |
| `approvals.submit` | 提出**と取り下げ**。この 2 つは一緒に動きます |
| `approvals.decide` | 段階の判断                                    |

この分割は上の規則を反映しています。提出と判断は別のスコープなので、申請を出すために作られたクライアントは、申請ごとの検査が走る前の段階で既に承認できません。

## 読み取り

[`GET /approvals`](/ja/reference/approvals/get-api-v1-approvals) は申請を一覧し、[`GET /approvals/{id}/decisions`](/ja/reference/approvals/get-api-v1-approvals-by-id-decisions) は 1 件に対する判断を `stage`、`decision`、`comment`、`decidedBy` とともに返します。却下された申請も判断を保持するため、理由は拒否のあとも残ります。