전자서명 템플릿으로 서명 요청 API

전자서명 템플릿을 이용하여 계약서를 생성하고 서명을 요청할 수 있습니다.

`POST` kit-api/v1/signature-templates/[key]/signatures

Method: POST Endpoint: kit-api/v1/signature-templates/[key]/signatures Param: key는 전자서명 템플릿의 id(숫자) 혹은 slug(문자) 값을 의미

Example

.../kit-api/v1/signature-templates/4328/signatures

{
  "input": {
    "title": "솔루션 공급 계약서",
    "participants": [
      // 전자서명 템플릿 생성/편집 시, 옵션으로 '일부 참여자에게 요청' 기능을 허용했다면 일부 참여자 정보만 전달할 수 있습니다.
      {
        "role": "갑", // 참여자 역할 (워크플로우의 참여자와 매칭)
        "input": {
          "name": "홍길동", // 참여자 이름
          "email": "[email protected]", // 참여자 이메일 (이메일, 전화번호 중에 하나 필요)
          "auth": "EMAIL", // 인증 수단 (EMAIL, PHONE 존재 / send와 동일한 값으로 입력)
          "send": "EMAIL" // 발송 수단 (EMAIL, PHONE 존재)
        }
      },
      {
        "role": "을",
        "input": {
          "name": "김프릭",
          "phone": "010-1234-1234", // 참여자 전화번호
          "auth": "PHONE",
          "send": "PHONE",
          "extraAuthList": [
            {
              // 휴대폰 본인인증이 필요한 경우 해당 값 사용
              "type": "MOBILE_IDENTIFICATION",
              "phoneName": "김실명",
              "phoneNumber": "010-1234-1234"
            }
          ]
        }
      }
    ],
    "items": [
      {
        // 사전입력값 내용 추가를 위해 사용
        "id": 231, // 입력값 id (ex. "금액" 사전입력값의 id가 231인 경우)
        "contents": "2,000,000" // 입력값 내용
      },
      {
        "id": 232, // (ex. "주소" 입력값의 id가 232인 경우)
        "contents": "선릉로 551 새롬아파트 101-204"
      },
      {
        "id": 233, // (ex. "동의" 입력값의 id가 233인 경우)
        "contents": "true" // 체크박스 체크 여부 ('true' 혹은 빈 문자열)
      },
      // 사전 입력값 생성/편집 시 slug를 지정한 경우 id 대신 slug를 전달할 수 있습니다.
      {
        "slug": "object-1", // (ex. "동의" 입력값의 slug가 "object-1"인 경우)
        "contents": "true" // 체크박스 체크 여부 ('true' 혹은 빈 문자열)
      }
    ],
    "additionalFiles": ["...견적서.pdf"], // 합본할 파일 url 목록
    "contract": {
      "type": "NEW", // 재계약 여부 (선택 / NEW, RENEWAL)
      "customKey": "custom-id", // 연결할 맞춤 키 값 (선택 / 중복 불가)
      "fileToReplace": "...contract.pdf", // 실제 서명 요청 시 사용할 계약서 문서 url (주의사항: fileToReplace 필드를 사용하여 계약 문서를 변경하여 서명을 요청하는 경우, 템플릿에 등록된 계약서와 페이지 수가 동일해야 합니다.)
      "slugColumns": [
        // 계약서에 연결할 커스텀 컬럼 정보
        {
          "slug": "slug-column-1", // 커스텀 컬럼 식별값 (별도 연락 필요)
          "value": "slug-column-value" // 커스텀 컬럼 값 (String)
        }
      ],
      "connectedContractUuids": ["contract-uuid"], // 연결할 계약서 uuid 목록 (선택)
      "contractDate": {
        "startDate": "2024-10-01T00:00:00.000Z", // 시작일
        "endDate": null, // 종료일
        "concludedDate": null // 체결일
      },
      "customers": [
        // 계약서에 연결할 고객의 Id 또는 CustomKey (고객을 연결하려면 둘 중 하나는 필수로 입력해야 합니다.)
        {
          "id": 1,
          "customKey": "customer-custom-key-32"
        }
      ]
    },
    "signature": {
      "expiredDate": "2024-12-20T15:00:00.000Z", // 서명 만료일 (현재보다 이후 시간이어야 함)
      "ccEmails": [], // 참조자 이메일 목록
      "requesterName": "프릭스 컴퍼니", // 서명 요청자
      "facilitator": {
        // 대면서명 진행자 정보 (대면서명 미요청 시 facilitator 필드 사용하지 않아야 함)
        "name": "대면서명 담당자", // 대면서명 진행자 이름
        "email": "[email protected]" // 대면서명 진행자 이메일
      },
      "additionalRequests": [
        {
          "role": "참관자", // 추가 참여자 역할
          "type": "EMAIL", // 발송 방식 (EMAIL, PHONE)
          "contact": "[email protected]" // 이메일 주소 또는 전화번호
        }
      ],
      "redirectUrl": "https://example.com/callback" // 각 서명 별 리다이렉트 시키고자 하는 경로
    },
    "option": {
      "skipSend": false // 알림 발송 스킵 여부 (선택, true 인 경우 서명 참여 알림을 발송하지 않음)
    }
  }
}

Request Body

Key

Description

Required

input.title

전자서명 이름

yes

input.participants

전자서명 참여자 정보

yes

input.participants[].role

참여자 역할 (템플릿에 정의된 역할과 일치해야 함)

yes

input.participants[].input

참여자 상세 정보

yes

input.participants[].input.name

참여자 이름

yes

input.participants[].input.email

참여자 이메일 (email 또는 phone 중 하나 필수)

input.participants[].input.phone

참여자 전화번호 (email 또는 phone 중 하나 필수)

input.participants[].input.auth

인증 수단 (EMAIL, PHONE)

yes

input.participants[].input.send

발송 수단 (EMAIL, PHONE)

yes

input.participants[].input.extraAuthList

추가 인증 정보 목록

input.additionalFiles

합본할 파일 url 목록

input.items

전자서명 사전입력값 정보

input.items[].id

사전입력값 ID

no (id 또는 slug 중 1개 필수)

input.items[].slug

사전입력값 Slug

no (id 또는 slug 중 1개 필수)

input.items[].contents

사전입력값 내용

yes

input.contract

계약서 관련 추가 정보

input.contract.type

재계약 여부 (NEW, RENEWAL)

input.contract.customKey

연결할 맞춤 키 값 (중복 불가)

input.contract.contractDate.startDate

계약 시작일 (string / Date의 iso 형태 문자열)

input.contract.contractDate.endDate

계약 종료일 (string / Date의 iso 형태 문자열)

input.contract.slugColumns

계약서에 연결할 커스텀 컬럼 정보

input.contract.slugColumns[].slug

커스텀 컬럼 식별값 (별도 연락 필요)

input.contract.slugColumns[].value

커스텀 컬럼 값 (String)

input.contract.connectedContractUuids

연결할 계약서 uuid 목록

input.contract.customers

계약서에 연결할 고객 정보

input.contract.customers[].id

계약서에 연결할 고객 id (Number)

input.contract.customers[].customKey

계약서에 연결할 고객 customKey (String)

input.signature

전자서명 관련 추가 정보

input.signature.expiredDate

서명 만료일 (현재보다 이후 시간)

input.signature.ccEmails

참조자 이메일 목록

input.signature.requesterName

서명 요청자 이름

input.signature.facilitator

대면서명 진행자 정보 (대면서명 시 사용)

input.signature.facilitator.name

대면서명 진행자 이름

대면서명 시 yes

input.signature.facilitator.email

대면서명 진행자 이메일

대면서명 시 yes

input.signature.additionalRequests

추가 발송 참여자 정보

input.signature.additionalRequests[].role

추가 참여자 역할

input.signature.additionalRequests[].type

발송 방식 (EMAIL, PHONE)

input.signature.additionalRequests[].contact

연락처 (이메일 또는 전화번호)

input.signature.redirectUrl

리다이렉트 경로

input.option

전자서명 옵션 정보

input.option.skipSend

알림 발송 스킵 여부 (true 시 알림 발송 안함)

Response

{
  "ok": true,
  "message": undefined, // 실패하는 경우 메시지 (string)
  "data": {
    // 전자서명 정보
    "signature": {
      "uuid": "57139f5c-37d0-4c30-bdb6-ef6106040756", // 전자서명 식별값
      "title": "솔루션 공급 계약서", // 전자서명 제목
      "expiredDate": "2024-12-20T15:00:00.000Z", // 전자서명 만료일
      "status": "WAITING", // 상태 (WAITING은 서명 요청 후 대기 상태를 의미)
      "createdAt": "2024-10-15T00:00:00.000Z", // 생성일
      "ccEmails": null,
      "facilitator": {
        // 대면서명 진행자 정보 (대면서명 요청 시 값 존재)
        "uuid": "8053804d-581a-4e99-91e3-c077dc461373",
        "name": "대면서명 담당자",
        "email": "[email protected]"
      },
      "participants": [
        {
          "uuid": "689a0e2b-db58-4f16-9b9a-e745408de889", // 참여자 식별값
          "name": "홍길동", // 참여자 이름
          "status": "CREATED", // 참여자 상태
          "order": 1, // 참여 순서
          "email": "[email protected]", // 참여자 이메일
          "send": "EMAIL", // 발송 수단
          "message": null, // 발송 메시지
          "language": "KOREAN", // 언어 설정
          "extraAuthList": null, // 추가 인증 정보
          "role": "갑" // 참여자 역할
        }
      ]
    },
    "contract": {
      "uuid": "ed976505-bcbd-47bd-913d-f4cde05dea7a", // 문서 식별값 (uuid 값을 api에서 사용합니다)
      "file": "...contract.pdf", // 계약 문서 url
      "status": "CREATED", // 상태 (CREATED, CONCLUDED)
      "createdAt": "2024-10-15T00:00:00.000Z", // 생성일
      "type": "NEW",
      "contractDate": {
        "startDate": null,
        "endDate": null
      }
    }
  }
}

Status Code

Error Code

Description

400

INVALID_SIGNATURE_TITLE

title이 없는 경우

400

INVALID_SIGNATURE_EXPIRED_DATE

signature의 expiredDate가 현재 시간 이후가 아닌 경우

400

NOT_ALLOWED_PARTICIPANT_MINIMUM_LENGTH

전자서명 템플릿에 설정된 모든 참여자에 대한 정보가 없는 경우

400

INVALID_ADDITIONAL_INPUT

추가 입력값이 없는 경우

400

SIGNATURE_PARTICIPANT_EMPTY_ADDITIONAL_REQUEST_INPUT

추가 발송 참여자와 값이 없는 경우

400

SIGNATURE_PARTICIPANT_INVALID_ADDITIONAL_REQUEST_EMAIL

추가 발송 참여자의 email 주소가 잘못된 경우

400

SIGNATURE_PARTICIPANT_INVALID_ADDITIONAL_REQUEST_PHONE

추가 발송 참여자의 전화번호가 잘못된 경우

400

EXISTING_CONTRACT_KEY

계약서의 custom key가 이미 존재하는 경우

400

FAILED_USE_SIGNATURE_TEMPLATE

전자서명 템플릿 사용중 알 수 없는 에러가 발생한 경우

403

NOT_ALLOWED_PASS_AUTH_NOT_ENOUGH

휴대폰 본인인증을 위한 크레딧이 부족한 경우

404

NOT_FOUND_SIGNATURE_TEMPLATE

전자서명 템플릿이 존재하지 않는 경우

404

NOT_FOUND_BUSINESS

전자서명 템플릿과 연결된 비즈니스가 존재하지 않는 경우

404

NOT_FOUND_USER

전자서명 템플릿과 연결된 사용자가 존재하지 않는 경우

404

SIGNATURE_TEMPLATE_NOT_FOUND

전자서명 템플릿이 존재하지 않는 경우

500

FAILED_CREATE_CONTRACT

계약서 생성 중 알 수 없는 에러가 발생한 경우

500

FAILED_CREATE_SIGNATURE

전자서명 생성 중 알 수 없는 에러가 발생한 경우

500

FAILED_MERGE_CONTRACT

pdf 합본에 실패한 경우

Previous전자서명 템플릿 상세 조회 API Next전자서명 템플릿 대량계약 페이지 API

Last updated 1 month ago

POST kit-api/v1/signature-templates/[key]/signatures

Example

Request Body

Response

`POST` kit-api/v1/signature-templates/[key]/signatures