> ## 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.

# KYB 문서 업로드 API

> 자체 서버에서 기업 확인(KYB) 세션에 법인 문서를 업로드하세요. Didit의 호스팅 파이프라인 OCR 및 검사가 그대로 적용됩니다.



## OpenAPI

````yaml ko/openapi-25.json POST /v3/session/{sessionId}/kyb/documents/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: 신분증 인증 API입니다. x-api-key 헤더로 인증합니다.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/session/{sessionId}/kyb/documents/:
    post:
      tags:
        - Sessions
      summary: 세션에 KYB 문서 업로드
      description: >-
        호스팅 페이지 대신 자체 서버에서 기업 확인 세션의 KYB 문서 단계로 하나 이상의 기업 문서(정관, 주주명부, 법인 설립 증명서
        등)를 업로드합니다. Didit은 압축, OCR, 위변조 및 교차 문서 검사, 문서 그룹화 등 호스팅 파이프라인을 실행하며 필요한
        문서 그룹이 충족되면 세션을 진행합니다. 이 단계는 전송하는 파일 수와 관계없이 단일 고정 요금이 부과됩니다. 세션은 열려 있고
        KYB 문서 단계여야 하며 법인 등기부 단계에서 선택한 기업이 존재해야 합니다. `GET
        /v3/session/{sessionId}/kyb/extracted-parties/`로 문서에 명시된 인물을 확인하세요.
        `write:businesses` 권한이 필요합니다.
      operationId: post_v3_session_kyb_documents
      parameters:
        - name: sessionId
          in: path
          required: true
          description: 기업 확인(KYB) 세션의 UUID입니다. 해당 API 키의 애플리케이션에 속해 있어야 합니다.
          schema:
            type: string
            format: uuid
            example: 33333333-4444-5555-6666-777777777777
        - name: node_id
          in: query
          required: false
          description: >-
            KYB 단계의 워크플로 노드입니다. 워크플로에 둘 이상의 KYB 노드가 있는 경우에만 필요하며, 기본적으로 Didit은
            세션 자체의 노드를 사용합니다.
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - documents
              properties:
                documents:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: >-
                    업로드할 파일: JPG, JPEG, PNG, TIFF, WEBP, PDF 또는 이들의 ZIP 압축
                    파일입니다. PDF는 최대 50 MB, 사진은 압축 전 최대 6 MB까지 가능합니다.
                document_passwords:
                  type: array
                  items:
                    type: string
                  description: >-
                    `documents`의 파일당 동일한 순서의 항목 1개입니다. 보호된 PDF의 비밀번호이며 다른 파일의 경우
                    비어 있습니다.
                document_group:
                  type: string
                  enum:
                    - LEGAL_PRESENCE
                    - COMPANY_DETAILS
                    - OWNERSHIP_STRUCTURE
                    - REPRESENTATIVES_AUTHORIZATION
                  description: 이 업로드가 대응하는 필수 문서 그룹입니다.
                locale:
                  type: string
                  maxLength: 10
                  description: 다음 단계의 응답을 번역하는 데 사용되는 로캘입니다.
      responses:
        '200':
          description: >-
            문서가 처리되었습니다. 필요한 모든 그룹이 충족되면 세션이 진행되고 `next_step`에 다음 단계가 표시됩니다. 그렇지
            않으면 문서 단계에 유지되며 `document_groups` 및 `document_answer`에 누락된 항목이
            표시됩니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                  next_step:
                    type: string
                    nullable: true
                    description: 업로드 후 세션이 위치한 단계입니다.
                  kyb_status:
                    type: string
                    description: 기업 검사의 상태입니다.
                  document_answer:
                    type: object
                    additionalProperties: true
                    description: 업로드된 문서별 결과 및 남은 업로드 수입니다.
                additionalProperties: true
              example:
                valid: true
                next_step: KYB_KEY_PEOPLE
                kyb_status: In Progress
        '400':
          description: >-
            문서가 거부되었거나(위변조, 판독 불가 또는 지원되지 않음) 세션에 아직 KYB 기업이 없습니다. 시도 횟수가 남아 있는
            동안 다른 파일로 재시도하십시오.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 사람이 읽기 쉬운 오류 메시지입니다.
              example:
                message: No KYB company found. Submit company data first.
        '401':
          description: >-
            스코프가 지정된 API 키가 만료되었습니다. `401`이 반환되는 유일한 경우이며, 누락되었거나 유효하지 않거나 폐기된
            키에는 `403`이 반환됩니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 사람이 읽기 쉬운 오류 메시지입니다.
              examples:
                Expired key:
                  summary: 키의 만료일이 지났습니다
                  value:
                    detail: This API key has expired.
        '402':
          description: 문서 단계에 사용할 조직의 크레딧이 남아 있지 않습니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 사람이 읽기 쉬운 오류 메시지입니다.
              example:
                detail: Insufficient credits.
        '403':
          description: >-
            인증 또는 권한 부여에 실패했습니다. 키가 누락된 경우 `403`이 반환되며, 다른 애플리케이션의 키, 이
            endpoint에 필요한 권한이 없는 범위 지정 키, 키의 IP 허용 목록 외부에서 보낸 요청의 경우에도 마찬가지입니다.
            잘못되었거나 취소되었거나 만료된 키는 `401`을 반환합니다. `detail`로 구분하십시오.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 사람이 읽기 쉬운 오류 메시지입니다.
              examples:
                Missing or invalid credentials:
                  summary: x-api-key 헤더가 없거나 키 검증에 실패했습니다
                  value:
                    detail: >-
                      Authentication credentials were not provided or are
                      invalid.
                Other application:
                  summary: 세션과 다른 애플리케이션에 속한 유효한 키입니다
                  value:
                    detail: You do not have permission to perform this action.
                Scoped key without decisions write:
                  summary: '스코프 지정 키에 decisions: write 권한이 없음'
                  value:
                    detail: This API key has no write access to decisions.
                IP not allowed:
                  summary: 키의 IP 허용 목록 외부로부터의 요청
                  value:
                    detail: This API key can't be used from this IP address.
        '404':
          description: >-
            세션이 존재하지 않거나, 삭제되었거나, 다른 애플리케이션에 속해 있거나, 범위가 지정된 키의 제한 범위를 벗어났습니다.
            이를 구분하는 세부 정보는 제공되지 않습니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 사람이 읽기 쉬운 오류 메시지입니다.
              example:
                detail: Session not found.
        '409':
          description: >-
            세션이 종료되었거나(`kyb_session_not_writable`), KYB Documents 단계에 있지
            않습니다(`kyb_step_mismatch`, `next_step`에 현재 단계 표시).
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 사람이 읽기 쉬운 오류 메시지입니다.
                  code:
                    type: string
                  next_step:
                    type: string
              example:
                detail: The session is not on the step this operation completes.
                code: kyb_step_mismatch
                next_step: KYB_REGISTRY
        '429':
          description: >-
            속도 제한을 초과했습니다. API 키당 분당 300회의 쓰기(POST, PATCH, DELETE) 요청으로 제한됩니다.
            재시도하기 전에 `Retry-After`초 동안 대기하세요. `X-RateLimit-*` 헤더에 한도 정보가 표시됩니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 사람이 읽기 쉬운 오류 메시지입니다.
              examples:
                Rate limited:
                  summary: 현재 분에 할당된 예산이 소진되었습니다
                  value:
                    detail: >-
                      Write request rate limit exceeded. You can make up to 300
                      requests per minute.
          headers:
            Retry-After:
              description: 재시도하기 전 대기할 시간(초)입니다.
              schema:
                type: integer
                minimum: 1
                example: 30
        '503':
          $ref: '#/components/responses/DocumentProcessingBusy'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.sessions.upload_kyb_documents(
                "33333333-4444-5555-6666-777777777777",
                documents=[open("document.pdf", "rb")],
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: >-
            import Didit, { fileFromPath } from "@didit-protocol/sdk-node";


            // Reads DIDIT_API_KEY.

            const didit = new Didit();


            const result = await
            didit.sessions.uploadKybDocuments("33333333-4444-5555-6666-777777777777",
            {
              documents: [await fileFromPath("document.pdf")],
            });

            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UploadKYBDocuments(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsUploadKYBDocumentsParams{\n\tDocuments: []didit.File{didit.FileFromPath(\"document.pdf\")},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import java.nio.file.Path;

            import java.util.List;

            import me.didit.Didit;

            import me.didit.types.SessionsUploadKybDocumentsParams;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.sessions().uploadKybDocuments("33333333-4444-5555-6666-777777777777",
            SessionsUploadKybDocumentsParams.builder()
                    .documents(List.of(Path.of("document.pdf")))
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: >-
            <?php


            require 'vendor/autoload.php';


            use Didit\DiditClient;

            use Didit\File;


            // Reads DIDIT_API_KEY.

            $didit = new DiditClient();


            $result =
            $didit->sessions->uploadKybDocuments('33333333-4444-5555-6666-777777777777',
            [
                'documents' => [File::fromPath('document.pdf')],
            ]);

            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.sessions.upload_kyb_documents(
              "33333333-4444-5555-6666-777777777777",
              documents: [Pathname("document.pdf")]
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await
            client.Sessions.UploadKybDocumentsAsync("33333333-4444-5555-6666-777777777777",
            new SessionsUploadKybDocumentsParams

            {
                Documents = new FileUpload[] { FileUpload.FromPath("document.pdf") },
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  responses:
    DocumentProcessingBusy:
      description: >-
        현재 너무 많은 문서가 처리 중이므로 이 업로드가 처리되지 않았습니다. 아무것도 저장되지 않았으며 시도 횟수도 사용되지
        않았습니다. `Retry-After`의 시간(초)이 지난 후 동일한 파일을 다시 전송하세요. 메시지 텍스트가 아닌 `code`를
        기준으로 분기하세요.
      headers:
        Retry-After:
          description: 동일한 요청을 다시 전송하기 전에 대기해야 하는 시간(초)입니다.
          schema:
            type: integer
            example: 10
      content:
        application/json:
          schema:
            type: object
            required:
              - detail
              - code
            properties:
              detail:
                type: string
              code:
                type: string
                enum:
                  - document_processing_busy
          example:
            detail: We are busy processing documents. Please try again in a moment.
            code: document_processing_busy
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Business Console의 Developers -> API keys에서 발급받은 귀하 애플리케이션의 API 키입니다. 기본
        키는 전체 접근 권한을 갖습니다. 이름이 지정된 키는 리소스별 none, read, write 범위로 권한을 제한할 수 있으며
        특정 워크플로나 승인된 세션, IP 주소 목록, 만료일 등으로 제한할 수도 있습니다. 401은 키가 잘못되었거나 폐기되었거나
        만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스나 작업에 대한 접근 권한이 없거나, 요청이 허용된
        IP 목록 외부 주소에서 발생했음을 의미합니다. 세션 경로에서의 404는 해당 세션이 키의 허용 워크플로 또는 상태 범위를
        벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 비디오, PDF URL을 null로 수신하며, 세션 write
        권한이 없는 키는 세션 링크와 token을 null로 수신합니다.
        https://docs.didit.me/console/api-keys 를 참고하십시오.

````

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