---
title: "임베디드 초안 생성"
method: POST
path: "/embedded-drafts"
tags: ["USER API"]
---

# 임베디드 초안 생성

`POST /embedded-drafts`

## Request body

- CreateEmbeddedDraftRequestDto
  - `redirectUrl` string — 임베딩된 서명요청 화면에서 서명요청 완료 후 이동할 주소
  - `title` string, required — 문서의 제목
  - `file` union — 문서 파일 데이터
    - Base64DocumentFileInDraftRequestDto
      - `base64` string, required — base64 형식의 문서 파일
      - `extension` '' | 'pdf' | 'hwp' | 'hwpx' | 'doc' | 'docx' | 'xls' | 'xlsx' | 'ppt' | 'pptx' | 'bmp' | 'gif' | 'jpg' | 'jpeg' | 'png' | 'tiff', required — 문서 파일의 확장자
    - FileRefDocumentFileInDraftRequestDto
      - `fileId` string, required — 파일 ID
      - `token` string, required — 파일 토큰
  - `fileOpenPassword` string — 완료문서(.pdf) 비밀번호
  - `requesterInputs` union[] — 요청자의 입력 (이미지의 개수는 최대 7개)
    - union
      - TextRequesterInputInDraftRequestDto
        - `dataLabel` string — 데이터 라벨
        - `type` string, required — 요청자 입력 타입 (예시 값으로 고정되어 있습니다)
        - `value` string, required — 텍스트 박스에 입력될 값
        - `size` SizeInDraftRequestDto, required
          - `width` number, required — 입력란의 너비
          - `height` number, required — 입력란의 높이 (`type`이 `CHECKBOX`일 경우 무시됩니다)
        - `position` PositionInCreateEmbeddedDraftRequestDto, required
          - `x` number, required — 입력란의 가로 좌표
          - `y` number, required — 입력란의 세로 좌표
          - `page` integer, required — 입력란이 위치할 페이지
        - `textStyle` TextStyleInDraftRequestDto, required
          - `size` 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 24 | 30 | 36 | 48 | 60, required — 텍스트 크기
          - `font` 'NOTO_SANS' | 'NOTO_SERIF', required — 텍스트 글자체
          - `align` 'LEFT' | 'CENTER' | 'RIGHT', required — 텍스트 정렬
      - CheckboxRequesterInputInDraftRequestDto
        - `dataLabel` string — 데이터 라벨
        - `type` string, required — 요청자 입력 타입 (예시 값으로 고정되어 있습니다)
        - `value` boolean, required — 체크박스의 체크 여부
        - `size` SizeInDraftRequestDto, required
          - `width` number, required — 입력란의 너비
          - `height` number, required — 입력란의 높이 (`type`이 `CHECKBOX`일 경우 무시됩니다)
        - `position` PositionInCreateEmbeddedDraftRequestDto, required
          - `x` number, required — 입력란의 가로 좌표
          - `y` number, required — 입력란의 세로 좌표
          - `page` integer, required — 입력란이 위치할 페이지
      - ImageRequesterInputInDraftRequestDto
        - `dataLabel` string — 데이터 라벨
        - `type` string, required — 요청자 입력 타입 (예시 값으로 고정되어 있습니다)
        - `value` ImageInfoInDraftRequestDto, required
          - `base64` string, required — 이미지 데이터를 base64로 인코딩한 문자열
        - `size` SizeInDraftRequestDto, required
          - `width` number, required — 입력란의 너비
          - `height` number, required — 입력란의 높이 (`type`이 `CHECKBOX`일 경우 무시됩니다)
        - `position` PositionInCreateEmbeddedDraftRequestDto, required
          - `x` number, required — 입력란의 가로 좌표
          - `y` number, required — 입력란의 세로 좌표
          - `page` integer, required — 입력란이 위치할 페이지
  - `participants` ParticipantInDraftRequestDto[] — 문서의 참여자들 정보
    - `name` string — 참여자 이름 (특수문자 /?<>\":*|₩ 이 포함된 이름은 사용할 수 없습니다)
    - `role` string — 참여자의 역할
    - `requesterMessage` string, nullable — 참여자에게 전달할 남길말
    - `locale` 'ko' | 'en' | 'zh-CN' | 'ja' | 'vi' — 참여자가 사용할 언어
    - `signingOrder` number — 참여 순서. 순서 없이 참여하려면 모두 1로 설정하세요.
    - `signingDuration` number — 참여자의 참여 유효 기간 (분) * 미지정시 기본값 20160분 (14일)
    - `signingMethod` SigningMethodInDraftRequestDto
      - `type` 'KAKAO' | 'EMAIL' | 'SECURE_LINK', required — 참여 수단 종류
      - `value` string, required — 참여자의 참여 수단 (이메일 또는 휴대전화번호)
    - `attachmentRequests` AttachmentRequestInDraftRequestDto[] — 첨부파일 요청 정보
      - `name` string, required — 첨부파일 이름 (특수문자 /?<>\":*|₩ 이 포함된 이름은 사용할 수 없습니다)
      - `message` string — 첨부파일에 대한 설명
      - `required` boolean — 필수 여부
    - `verification` VerificationInDraftRequestDto
      - `password` PasswordInDraftRequestDto
        - `value` string, required — 비밀번호
        - `hint` string — 비밀번호 힌트
      - `mobileIdentification` MobileIdentificationInDraftRequestDto
        - `name` string — 휴대폰 본인 인증의 명의자 이름
        - `phoneNumber` string — 휴대폰 본인 인증의 명의자 전화번호
        - `allowOptions` string[] — 휴대폰 본인 인증 옵션
      - `dCert` DCertInDraftRequestDto
        - `name` string — 법인 공동인증서 인증 법인명
        - `bizNumber` string — 법인 공동인증서 인증 사업자 등록번호
    - `fields` union[] — 문서 필드 정보
      - union
        - TextFieldInCreateEmbeddedDraftRequestDto
          - `dataLabel` string — 데이터 라벨
          - `type` string, required — 필드 타입 (TEXT로 요청해야 합니다)
          - `required` boolean — 필수 여부
          - `size` TextFieldSizeInCreateEmbeddedDraftRequestDto, required
            - `width` number, required — 입력란의 너비
            - `height` number, required — 입력란의 높이
          - `position` PositionInCreateEmbeddedDraftRequestDto, required
            - `x` number, required — 입력란의 가로 좌표
            - `y` number, required — 입력란의 세로 좌표
            - `page` integer, required — 입력란이 위치할 페이지
          - `textStyle` TextFieldStyleInCreateEmbeddedDraftRequestDto, required
            - `size` 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 24 | 30 | 36 | 48 | 60, required — 텍스트 크기
            - `font` 'NOTO_SANS' | 'NOTO_SERIF', required — 텍스트 글자체
            - `align` 'LEFT' | 'CENTER' | 'RIGHT' — 텍스트 정렬
          - `format` union — 형식
            - PhoneNumberFormatInCreateEmbeddedDraftRequestDto
              - …
            - BizNumberFormatInCreateEmbeddedDraftRequestDto
              - …
            - BankAccountNumberFormatInCreateEmbeddedDraftRequestDto
              - …
            - RegexFormatInCreateEmbeddedDraftRequestDto
              - …
          - `prefilledValue` string, nullable — 사전 입력값
        - CheckboxFieldInCreateEmbeddedDraftRequestDto
          - `dataLabel` string — 데이터 라벨. 그룹 라벨과 함께 사용할 수 없습니다.
          - `type` string, required — 필드 타입 (CHECKBOX로 요청해야 합니다)
          - `required` boolean — 필수 여부 - 체크박스가 그룹에 속하는 경우 무시됩니다.
          - `size` CheckboxFieldSizeInCreateEmbeddedDraftRequestDto, required
            - `width` number, required — 입력란의 너비
          - `position` PositionInCreateEmbeddedDraftRequestDto, required
            - `x` number, required — 입력란의 가로 좌표
            - `y` number, required — 입력란의 세로 좌표
            - `page` integer, required — 입력란이 위치할 페이지
          - `groupLabel` string — 그룹 라벨
          - `valueDescription` string — 체크박스 내용, 체크박스를 호버하거나 한번에 선택할때 서명자에게 노출됩니다.
          - `enableOneClick` boolean — 체크박스를 한번에 선택(체크) 할 수 있는 여부, 문서 서명시 활성화된 체크박스는 서명자가 확인 후 한번에 체크할 수 있습니다.
          - `prefilledValue` boolean, nullable — 사전 입력값
        - SignatureFieldInCreateEmbeddedDraftRequestDto
          - `dataLabel` string — 데이터 라벨
          - `type` string, required — 필드 타입 (SIGNATURE로 요청해야 합니다)
          - `required` boolean, required — 필수 여부 - type이 `SIGNATURE`일 경우는 무조건 true가 됩니다.
          - `signatureTypes` string[], required — 서명 타입
          - `allowedGenerationMethods` string[] — 서명 생성 방식
          - `size` SignatureFieldSizeInCreateEmbeddedDraftRequestDto
            - `width` number, required — 입력란의 너비
            - `height` number, required — 입력란의 높이
          - `position` PositionInCreateEmbeddedDraftRequestDto, required
            - `x` number, required — 입력란의 가로 좌표
            - `y` number, required — 입력란의 세로 좌표
            - `page` integer, required — 입력란이 위치할 페이지
          - `enableOneClick` boolean — 한번에 서명 활성화 여부
        - SigningDateFieldInCreateEmbeddedDraftRequestDto
          - `dataLabel` string — 데이터 라벨
          - `type` string, required — 필드 타입 (SIGNING_DATE로 요청해야 합니다)
          - `size` SigningDateFieldSizeInCreateEmbeddedDraftRequestDto, required
            - `width` number, required — 입력란의 너비
            - `height` number, required — 입력란의 높이
          - `position` PositionInCreateEmbeddedDraftRequestDto, required
            - `x` number, required — 입력란의 가로 좌표
            - `y` number, required — 입력란의 세로 좌표
            - `page` integer, required — 입력란이 위치할 페이지
          - `textStyle` TextFieldStyleInCreateEmbeddedDraftRequestDto, required
            - `size` 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 24 | 30 | 36 | 48 | 60, required — 텍스트 크기
            - `font` 'NOTO_SANS' | 'NOTO_SERIF', required — 텍스트 글자체
            - `align` 'LEFT' | 'CENTER' | 'RIGHT' — 텍스트 정렬
          - `displayFormat` 'YYYY-MM-DD' | 'YYYY/DD/MM' | 'YYYY.MM.DD' | 'YYYYMMDD' | 'YYYY년 MM월 DD일' | 'DD-MM-YYYY' | 'DD/MM/YYYY' | 'DD.MM.YYYY' | 'DDMMYYYY' | 'DD일 MM월 YYYY년' | 'MM-DD-YYYY' | 'MM/DD/YYYY' | 'MM.DD.YYYY' | 'MMDDYYYY' | 'MM월 DD일 YYYY년' | 'YYYY/MM/DD' | 'YYYY-DD-MM' | 'YYYY.DD.MM' | 'YYYYDDMM' | 'YYYY년 DD일 MM월' | 'YY-MM-DD' | 'YY/MM/DD' | 'YY.MM.DD' | 'YYMMDD' | 'YY년 MM월 DD일' | 'DD-MM-YY' | 'DD/MM/YY' | 'DD.MM.YY' | 'DDMMYY' | 'DD일 MM월 YY년' | 'MM-DD-YY' | 'MM/DD/YY' | 'MM.DD.YY' | 'MMDDYY' | 'MM월 DD일 YY년' | 'YY-DD-MM' | 'YY/DD/MM' | 'YY.DD.MM' | 'YYDDMM' | 'YY년 DD일 MM월', required — 날짜 표기 형식
        - ImageFieldInCreateEmbeddedDraftRequestDto
          - `dataLabel` string — 데이터 라벨
          - `type` string, required — 필드 타입 (IMAGE로 요청해야 합니다)
          - `required` boolean — 필수 여부
          - `size` SizeInDraftRequestDto, required
            - `width` number, required — 입력란의 너비
            - `height` number, required — 입력란의 높이 (`type`이 `CHECKBOX`일 경우 무시됩니다)
          - `position` PositionInCreateEmbeddedDraftRequestDto, required
            - `x` number, required — 입력란의 가로 좌표
            - `y` number, required — 입력란의 세로 좌표
            - `page` integer, required — 입력란이 위치할 페이지
        - DateFieldInCreateEmbeddedDraftRequestDto
          - `dataLabel` string — 데이터 라벨
          - `type` string, required — 필드 타입 (DATE로 요청해야 합니다)
          - `required` boolean — 필수 여부
          - `size` SizeInDraftRequestDto, required
            - `width` number, required — 입력란의 너비
            - `height` number, required — 입력란의 높이 (`type`이 `CHECKBOX`일 경우 무시됩니다)
          - `position` PositionInCreateEmbeddedDraftRequestDto, required
            - `x` number, required — 입력란의 가로 좌표
            - `y` number, required — 입력란의 세로 좌표
            - `page` integer, required — 입력란이 위치할 페이지
          - `textStyle` TextFieldStyleInCreateEmbeddedDraftRequestDto, required
            - `size` 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 24 | 30 | 36 | 48 | 60, required — 텍스트 크기
            - `font` 'NOTO_SANS' | 'NOTO_SERIF', required — 텍스트 글자체
            - `align` 'LEFT' | 'CENTER' | 'RIGHT' — 텍스트 정렬
          - `displayFormat` 'YYYY-MM-DD' | 'YYYY/DD/MM' | 'YYYY.MM.DD' | 'YYYYMMDD' | 'YYYY년 MM월 DD일' | 'DD-MM-YYYY' | 'DD/MM/YYYY' | 'DD.MM.YYYY' | 'DDMMYYYY' | 'DD일 MM월 YYYY년' | 'MM-DD-YYYY' | 'MM/DD/YYYY' | 'MM.DD.YYYY' | 'MMDDYYYY' | 'MM월 DD일 YYYY년' | 'YYYY/MM/DD' | 'YYYY-DD-MM' | 'YYYY.DD.MM' | 'YYYYDDMM' | 'YYYY년 DD일 MM월' | 'YY-MM-DD' | 'YY/MM/DD' | 'YY.MM.DD' | 'YYMMDD' | 'YY년 MM월 DD일' | 'DD-MM-YY' | 'DD/MM/YY' | 'DD.MM.YY' | 'DDMMYY' | 'DD일 MM월 YY년' | 'MM-DD-YY' | 'MM/DD/YY' | 'MM.DD.YY' | 'MMDDYY' | 'MM월 DD일 YY년' | 'YY-DD-MM' | 'YY/DD/MM' | 'YY.DD.MM' | 'YYDDMM' | 'YY년 DD일 MM월', required — 날짜 표기 형식
          - `prefilledValue` string, nullable — 사전 입력값
        - DropdownFieldInCreateEmbeddedDraftRequestDto
          - `dataLabel` string — 데이터 라벨
          - `type` string, required — 필드 타입 (DROPDOWN으로 요청해야 합니다)
          - `required` boolean — 필수 여부
          - `size` SizeInDraftRequestDto, required
            - `width` number, required — 입력란의 너비
            - `height` number, required — 입력란의 높이 (`type`이 `CHECKBOX`일 경우 무시됩니다)
          - `position` PositionInCreateEmbeddedDraftRequestDto, required
            - `x` number, required — 입력란의 가로 좌표
            - `y` number, required — 입력란의 세로 좌표
            - `page` integer, required — 입력란이 위치할 페이지
          - `options` DropdownOptionInCreateEmbeddedDraftRequestDto[], required — 드롭다운 옵션 목록
            - `value` string, required — 드롭다운 옵션 값
          - `defaultInputValue` string, nullable — 기본값
          - `textStyle` TextFieldStyleInCreateEmbeddedDraftRequestDto, required
            - `size` 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 24 | 30 | 36 | 48 | 60, required — 텍스트 크기
            - `font` 'NOTO_SANS' | 'NOTO_SERIF', required — 텍스트 글자체
            - `align` 'LEFT' | 'CENTER' | 'RIGHT' — 텍스트 정렬
          - `prefilledValue` string, nullable — 사전 입력값
        - NameFieldInCreateEmbeddedDraftRequestDto
          - `dataLabel` string — 데이터 라벨
          - `type` string, required — 필드 타입 (NAME으로 요청해야 합니다)
          - `required` boolean — 필수 여부
          - `size` SizeInDraftRequestDto, required
            - `width` number, required — 입력란의 너비
            - `height` number, required — 입력란의 높이 (`type`이 `CHECKBOX`일 경우 무시됩니다)
          - `position` PositionInCreateEmbeddedDraftRequestDto, required
            - `x` number, required — 입력란의 가로 좌표
            - `y` number, required — 입력란의 세로 좌표
            - `page` integer, required — 입력란이 위치할 페이지
          - `textStyle` TextFieldStyleInCreateEmbeddedDraftRequestDto, required
            - `size` 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 24 | 30 | 36 | 48 | 60, required — 텍스트 크기
            - `font` 'NOTO_SANS' | 'NOTO_SERIF', required — 텍스트 글자체
            - `align` 'LEFT' | 'CENTER' | 'RIGHT' — 텍스트 정렬
        - CompanyNameFieldInCreateEmbeddedDraftRequestDto
          - `dataLabel` string — 데이터 라벨
          - `type` string, required — 필드 타입 (COMPANY_NAME으로 요청해야 합니다)
          - `required` boolean — 필수 여부
          - `size` SizeInDraftRequestDto, required
            - `width` number, required — 입력란의 너비
            - `height` number, required — 입력란의 높이 (`type`이 `CHECKBOX`일 경우 무시됩니다)
          - `position` PositionInCreateEmbeddedDraftRequestDto, required
            - `x` number, required — 입력란의 가로 좌표
            - `y` number, required — 입력란의 세로 좌표
            - `page` integer, required — 입력란이 위치할 페이지
          - `textStyle` TextFieldStyleInCreateEmbeddedDraftRequestDto, required
            - `size` 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 24 | 30 | 36 | 48 | 60, required — 텍스트 크기
            - `font` 'NOTO_SANS' | 'NOTO_SERIF', required — 텍스트 글자체
            - `align` 'LEFT' | 'CENTER' | 'RIGHT' — 텍스트 정렬
          - `prefilledValue` string, nullable — 사전 입력값
        - AddressFieldInCreateEmbeddedDraftRequestDto
          - `dataLabel` string — 데이터 라벨
          - `type` string, required — 필드 타입 (ADDRESS로 요청해야 합니다)
          - `required` boolean — 필수 여부
          - `size` SizeInDraftRequestDto, required
            - `width` number, required — 입력란의 너비
            - `height` number, required — 입력란의 높이 (`type`이 `CHECKBOX`일 경우 무시됩니다)
          - `position` PositionInCreateEmbeddedDraftRequestDto, required
            - `x` number, required — 입력란의 가로 좌표
            - `y` number, required — 입력란의 세로 좌표
            - `page` integer, required — 입력란이 위치할 페이지
          - `textStyle` TextFieldStyleInCreateEmbeddedDraftRequestDto, required
            - `size` 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 24 | 30 | 36 | 48 | 60, required — 텍스트 크기
            - `font` 'NOTO_SANS' | 'NOTO_SERIF', required — 텍스트 글자체
            - `align` 'LEFT' | 'CENTER' | 'RIGHT' — 텍스트 정렬
          - `prefilledValue` AddressPrefilledValueInCreateEmbeddedDraftRequestDto
            - `address1` string, required — 기본 주소
            - `address2` string, nullable — 상세 주소
            - `city` string, nullable — 시군구
            - `province` string, required — 도시
            - `zip` string, required — 우편번호
            - `country` 'KR', required — 나라
    - `checkboxFieldGroups` CheckboxGroupInDraftRequestDto[] — 체크박스 그룹
      - `groupLabel` string, required — 그룹 라벨
      - `minCheckRequired` 0 | 1, required — 최소 선택 개수. 현재는 0 또는 1만 지원합니다.
      - `maxCheckLimit` number, nullable — 최대 선택 개수. 현재는 1또는 null만 지원합니다. null은 최대 개수까지 선택 가능함을 뜻합니다.
  - `carbonCopies` CarbonCopy[] — 문서의 참조자들 정보
    - `contact` string, required — 참조자 연락처 (이메일 주소 또는 휴대전화번호)
    - `locale` 'ko' | 'en' | 'zh-CN' | 'ja' | 'vi' — 참조자 언어
  - `auditTrail` AuditTrailRequestDto
    - `locales` string[], required — 감사 추적 인증서 제공 언어
  - `metadatas` MetadataInDraftRequestDto[] — 메타데이터 리스트. 최대 10개까지 등록 가능 (응답의 메타데이터는 순서가 보장되지 않습니다)
    - `key` string, required — 메타데이터 키
    - `value` string — 메타데이터 값
  - `brandId` string — 브랜드 ID
  - `seal` DocumentSealInDraftRequestDto
    - `integritySeal` IntegritySealInDraftRequestDto, required
      - `enabled` boolean, required — 진본 증명 도장 활성화 여부
      - `position` 'TOP_LEFT' | 'TOP_RIGHT' | 'BOTTOM_LEFT' | 'BOTTOM_RIGHT', required — 진본 증명 도장 위치

## Response `201`

드래프트 정보

- CreateEmbeddedDraftResponseDto
  - `id` string, required — 생성된 초안의 ID
  - `embeddedUrl` string, required — 임베딩 가능한 서명 요청 주소(유효시간: 2시간)
  - `expiry` string, date-time, required — 생성된 초안의 만료 시간
  - `brandId` string — 브랜드 ID

---

[API](https://skmtc.net/modusign/apis/modusign-api.md) · [All operations](https://skmtc.net/modusign/apis/modusign-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/modusign/modusign-api/versions/5772e872cbf9/schema)