# 同意記録のインポート

`POST /v1/jobs/consent-imports` · 権限 `consent-records:write`

別のシステムに記録されていた法的文書への同意を取り込みます。たとえば、ユーザーをKeenAuthに移行する場合などです。リクエストは同期的に処理されます。1〜500件のレコードが1つのトランザクションで書き込まれるため、すべてが書き込まれるか、まったく書き込まれないかのどちらかになります。取り込まれたすべてのレコードには`method = import`があり、`occurred_at`は移行元システムでの時刻を保持します。バージョン、コンテンツハッシュ、ロケールは文書から取得されるため、指定することはできません。取り込まれたレコードは、ほかのすべての同意レコードと同様に追記のみです。今この時点で得た単一の同意を記録するには、[同意を記録する](/docs/api/management/users/create-consent-record)を使用してください。

`Idempotency-Key` は必須です。同じキーとリクエストで再試行すると、同じレスポンスが返されます（`Idempotent-Replayed: true` 付き）。二重に書き込まれることはありません。

## リクエスト

JSON本文（未知のフィールドは `400 unknown_field` で拒否されます）：

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `records` | object[] | はい | 1〜500件のレコード。この順序で書き込まれます。 |
| `records[].user_id` | string | はい | ユーザーID（`usr_…`）。 |
| `records[].subject_type` | string | はい | `document`のみ。 |
| `records[].subject_id` | string | はい | 法的文書ID（`ldoc_…`）。 |
| `records[].state` | string | はい | `presented`、`accepted`、または`declined`。 |
| `records[].application_id` | string \| null | いいえ | アプリケーション（`app_…`）。省略し、かつ文書がアプリケーション固有の場合は、文書のアプリケーションが記録されます。 |
| `records[].occurred_at` | string (date-time) | はい | 移行元システムでの発生時刻。未来の時刻は指定できません。 |

## レスポンス

書き込まれたレコード（`records`）を入力順に含めた `201 Created` を返します。

```json
{
  "imported_count": 1,
  "records": [
    {
      "id": "crec_01j9xk3m7q8r2s4t6v8w0y2z4b",
      "user_id": "usr_01j9xk3m7q8r2s4t6v8w0y2z4c",
      "subject_type": "document",
      "subject_id": "ldoc_01j9xk3m7q8r2s4t6v8w0y2z4a",
      "subject_version": "2026-10",
      "content_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "locale": "en",
      "state": "accepted",
      "method": "import",
      "application_id": null,
      "occurred_at": "2025-03-14T08:00:00Z"
    }
  ]
}
```

## エラー

| HTTP | code | 条件 |
|---|---|---|
| 400 | `malformed_request`、`unknown_field` | `Idempotency-Key` ヘッダーがない、または不正な形式である場合。本文が有効なJSONではない場合。未知のフィールドがある場合。 |
| 401 | `unauthenticated` | 認証情報がない、無効、または取り消されています。 |
| 403 | `insufficient_permissions` | 認証情報に必要な権限がありません。 |
| 413 | `payload_too_large` | 本文が1 MiBを超えています。 |
| 415 | `unsupported_media_type` | コンテンツタイプが `application/json` ではありません。 |
| 422 | `validation_failed` | レコードが不正です。`errors[].pointer` は `/records/<index>/<field>` です。不明なユーザーは `unknown_user`、不明なアプリケーションは `unknown_application`、不明な文書は `unknown_subject` です。レコードが1件未満または500件を超える場合は、`out_of_range` が `/records` で返されます。何も書き込まれません。 |
| 422 | `idempotency_key_reuse` | `Idempotency-Key` が別のリクエストで使用されました。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` の期間を置いてから再試行してください。 |
| 503 | `service_unavailable` | 依存先のサービスが一時的に利用できません。`Retry-After` の期間を置いてから再試行してください。 |

## 例

```bash
curl -X POST https://api.eu.keenauth.com/v1/jobs/consent-imports \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"records":[{"user_id":"usr_01j9xk3m7q8r2s4t6v8w0y2z4c","subject_type":"document","subject_id":"ldoc_01j9xk3m7q8r2s4t6v8w0y2z4a","state":"accepted","occurred_at":"2025-03-14T08:00:00Z"}]}'
```

CLI：`keenauth jobs consent-imports create --data records.json`

## 個人データ

このエンドポイントは個人データ、つまり同意レコードを扱います。[KeenAuth APIにおける個人データ](/docs/policies/personal-data)では、保存される内容、保持期間、削除方法を説明しています。いかなるフィールドにも、特別な種類の個人データ（健康、生体データ、宗教、政治的意見、性的指向）を送信しないでください。