> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Document AI 보고서: 추출된 필드

> Didit의 Document AI 레퍼런스: 문서 업로드 endpoint, 문서별 추출 필드 JSON, 상태 및 decision features[] 항목을 확인하세요.

## 개요

Document AI는 단계당 최대 3개의 문서(PDF 또는 이미지 — PDF, JPG, JPEG, PNG, TIFF, WebP)를 허용합니다. 각 문서는 구성된 `document_key`에 따라 분류되고, 필드 정의로 구축된 스키마를 사용하는 시각-언어 모델을 통해 판독되며, PDF/EXIF 포렌식을 거칩니다. 각 문서에 대해 다음 항목이 저장됩니다.

* **추출된 필드** — 구성된 필드 `key`를 키로 하는 맵으로, 선언한 유형의 값(`text` → string, `number` → number, `date` → `YYYY-MM-DD`)을 가집니다. 판독할 수 없는 필드는 `null`입니다.
* **감지된 QR 코드 및 바코드** — 렌더링된 모든 페이지의 디코딩된 payload 및 픽셀 좌표입니다. 위치는 파악되었으나 디코딩할 수 없는 QR 코드도 `parsed_payload: null`과 함께 반환됩니다.
* **문서 상태** — `Approved`, `In Review`, `Declined` 또는 `Not Finished`.
* **문서 메타데이터** — 오버레이/변조 증거를 포함한 파일 포렌식 데이터입니다.
* **교차 확인 결과** — 인증된 신원과의 이름 일치 여부 및 커스텀 필드 상호 대조 결과입니다.

## 문서 업로드

문서는 Document AI endpoint로 한 번에 하나씩 업로드됩니다. 호스팅 세션 또는 SDK 플로우에서는 이 작업이 자동으로 처리되며, 규격은 다음과 같습니다.

```text theme={null}
POST https://verification.didit.me/v3/document-ai/documents/
multipart/form-data — Session-Token: <session token>
```

| 필드 | 필수 여부 | 설명 |
| - | - | - |
| `document_key` | 예 | 이 파일이 충족하는 구성 문서 |
| `document` | 예 | 업로드할 파일 |
| `locale` | 아니요 | 화면에 표시되는 제목/설명을 결정하는 데 사용되는 로캘 |

응답을 통해 플로우가 진행됩니다.

```json theme={null}
{
  "valid": true,
  "next_step": "DOCUMENT_AI",
  "document_ai_status": "In Progress",
  "uploaded_document_keys": ["proof_of_funds"],
  "required_document_keys": ["proof_of_funds", "payslip"]
}
```

`required_document_keys`의 모든 항목이 `uploaded_document_keys`에 나타나고 미완료 상태인 문서가 없으면 해당 단계가 완료(`next_step`이 `DOCUMENT_AI` 이후로 이동)됩니다.

## API 응답에 표시되는 위치

`GET /v3/session/{sessionId}/decision/`은 사용자 인증(KYC) 및 기업 확인(KYB) 세션 모두에서 Document AI를 두 곳에 표시합니다. `document_ai_documents[]` 배열과 PDF 보고서는 `session_kind`에 관계없이 동일합니다.

* **`features[]`** — 실행된 기능을 열거하는 데 사용되는 Document AI 노드별 요약 항목입니다.

  ```json theme={null}
  { "features": [ { "feature": "DOCUMENT_AI", "node_id": "feature_document_ai_1" } ] }
  ```

* **`document_ai_documents[]`** — 전체 결과로, Document AI 노드당 하나의 그룹이 생성됩니다. 각 그룹에는 노드의 결합된 `status`, 업로드된 `items` 목록 및 `warnings`가 포함됩니다. 업로드된 모든 문서는 사용자가 구성한 필드(`extracted_data` 하위), 감지된 코드(`detected_codes` 하위), 자체 `status`, 필드 정의, 포렌식 `document_metadata` 및 `cross_check_result`를 포함하는 항목입니다.

각 노드의 문서별 상태는 **Declined > In Review > Approved** 우선순위에 따라 결합되어 노드 상태가 됩니다.

## 결정 예시

`account_holder`(text), `balance`(number), `currency`(text), `statement_date`(date)로 구성된 **자금 증명** 문서의 경우:

```json theme={null}
{
  "document_ai_documents": [
    {
      "node_id": "feature_document_ai_1",
      "status": "Approved",
      "items": [
        {
          "uuid": "5c1f0a2e-9b3d-4c7a-8f21-0a4e8e7d6c12",
          "document_key": "proof_of_funds",
          "status": "Approved",
          "original_filename": "statement.pdf",
          "extracted_data": {
            "account_holder": "Sophia Martinez",
            "balance": 18450.75,
            "currency": "EUR",
            "statement_date": "2026-05-31"
          },
          "detected_codes": [
            {
              "type": "QR_CODE",
              "page_number": 2,
              "position": [[124, 86], [306, 86], [306, 268], [124, 268]],
              "x": 124,
              "y": 86,
              "width": 182,
              "height": 182,
              "page_width": 1190,
              "page_height": 1684,
              "raw_payload": "SU5WLTIwMjYtMDA0Mg==",
              "parsed_payload": "INV-2026-0042"
            }
          ],
          "fields": [
            { "key": "account_holder", "name": "Account holder", "type": "text", "required": true },
            { "key": "balance", "name": "Balance", "type": "number", "required": false },
            { "key": "currency", "name": "Currency", "type": "text", "required": false },
            { "key": "statement_date", "name": "Statement date", "type": "date", "required": false }
          ],
          "document_metadata": { "is_tampered": false },
          "cross_check_result": null,
          "created_at": "2026-05-31T10:12:00Z"
        }
      ],
      "warnings": []
    }
  ]
}
```

`page_number`는 1부터 시작합니다. `position`에는 감지된 다각형 좌표가 포함되며, `x`, `y`, `width`, `height`는 경계 상자를 제공합니다. 모든 좌표는 치수가 `page_width` 및 `page_height`인 렌더링된 페이지의 픽셀 공간을 사용합니다. 지원되는 코드를 찾을 수 없는 경우 `detected_codes`는 빈 배열이 됩니다. `parsed_payload: null`인 항목은 디코딩된 값이 아닌 존재 여부 및 위치만을 나타내는 것으로 처리하세요.

모든 필드는 `document_ai.<field_key>`로 참조할 수 있으므로 `extracted_data` 값을 기반으로 분기 및 [커스텀 상태 규칙](https://docs.didit.me/ko/core-technology/document-ai/warnings-document-ai.md)을 직접 구동할 수 있으며, 여기에는 `kyc.full_name`이나 설문지 응답과 같은 다른 단계와의 상호 대조도 포함됩니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.