전자서명 템플릿으로 서명 요청 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": {
        // 대면서명 진행자 정보 (대면서명 미요청 시 facilitator 필드 사용하지 않아야 함)
        "name": "대면서명 담당자", // 대면서명 진행자 이름
        "email": "[e-mail]" // 대면서명 진행자 이메일
      },
      "additionalRequests": [
        {
          "role": "참관자", // 추가 참여자 역할
          "type": "EMAIL", // 발송 방식 (EMAIL, PHONE)
          "contact": "[e-mail]" // 이메일 주소 또는 전화번호
        }
      ],
      "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 중 하나 필수)	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.contract.slugColumns	계약서에 연결할 커스텀 컬럼 정보	no
input.contract.slugColumns[].slug	커스텀 컬럼 식별값 (별도 연락 필요)	no
input.contract.slugColumns[].value	커스텀 컬럼 값 (String)	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.signature.redirectUrl	리다이렉트 경로	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 합본에 실패한 경우