전자서명 템플릿으로 서명 요청 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": "[e-mail]", // 참여자 이메일 (이메일, 전화번호 중에 하나 필요)
          "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' 혹은 빈 문자열)
      }
    ],
    "contract": {
      "type": "NEW", // 재계약 여부 (선택 / NEW, RENEWAL)
      "customKey": "custom-id", // 연결할 맞춤 키 값 (선택 / 중복 불가)
      "fileToReplace": "...contract.pdf" // 실제 서명 요청 시 사용할 계약서 문서 url (주의사항: fileToReplace 필드를 사용하여 계약 문서를 변경하여 서명을 요청하는 경우, 템플릿에 등록된 계약서와 페이지 수가 동일해야 합니다.)
    },
    "signature": {
      "expiredDate": "2024-12-20T15:00:00.000Z", // 서명 만료일 (현재보다 이후 시간이어야 함)
      "ccEmails": [], // 참조자 이메일 목록
      "requesterName": "프릭스 컴퍼니", // 서명 요청자
      "facilitator": {
        // 대면서명 진행자 정보 (대면서명 요청 시 필요)
        "name": "대면서명 담당자", // 대면서명 진행자 이름
        "email": "[e-mail]" // 대면서명 진행자 이메일
      },
      "additionalRequests": [
        {
          "role": "참관자", // 추가 참여자 역할
          "type": "EMAIL", // 발송 방식 (EMAIL, PHONE)
          "contact": "[e-mail]" // 이메일 주소 또는 전화번호
        }
      ]
    },
    "option": {
      "skipSend": true // 알림 발송 스킵 여부 (선택 / *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 중 하나 필수)	no
input.participants[].input.phone	참여자 전화번호 (email 또는 phone 중 하나 필수)	no
input.participants[].input.auth	인증 수단 (EMAIL, PHONE)	yes
input.participants[].input.send	발송 수단 (EMAIL, PHONE)	yes
input.participants[].input.extraAuthList	추가 인증 정보 목록	no
input.items	전자서명 사전입력값 정보	yes
input.items[].id	사전입력값 ID	yes
input.items[].contents	사전입력값 내용	yes
input.contract	계약서 관련 추가 정보	no
input.contract.type	재계약 여부 (NEW, RENEWAL)	no
input.contract.customKey	연결할 맞춤 키 값 (중복 불가)	no
input.contract.contractDate.startDate	계약 시작일 (string / Date의 iso 형태 문자열)	no
input.contract.contractDate.endDate	계약 종료일 (string / Date의 iso 형태 문자열)	no
input.signature	전자서명 관련 추가 정보	no
input.signature.expiredDate	서명 만료일 (현재보다 이후 시간)	no
input.signature.ccEmails	참조자 이메일 목록	no
input.signature.requesterName	서명 요청자 이름	no
input.signature.facilitator	대면서명 진행자 정보 (대면서명 시 사용)	no
input.signature.facilitator.name	대면서명 진행자 이름	대면서명 시 yes
input.signature.facilitator.email	대면서명 진행자 이메일	대면서명 시 yes
input.signature.additionalRequests	추가 발송 참여자 정보	no
input.signature.additionalRequests[].role	추가 참여자 역할	no
input.signature.additionalRequests[].type	발송 방식 (EMAIL, PHONE)	no
input.signature.additionalRequests[].contact	연락처 (이메일 또는 전화번호)	no
input.option	전자서명 옵션 정보	no
input.option.skipSend	알림 발송 스킵 여부 (true 시 알림 발송 안함)	no

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": "[e-mail]"
      },
      "participants": [
        {
          "uuid": "689a0e2b-db58-4f16-9b9a-e745408de889", // 참여자 식별값
          "name": "홍길동", // 참여자 이름
          "status": "CREATED", // 참여자 상태
          "order": 1, // 참여 순서
          "email": "[e-mail]", // 참여자 이메일
          "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 합본에 실패한 경우