전자서명 템플릿으로 서명 요청 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

Request Body

Key	Description	Required
title	전자서명 이름	yes
participants	전자서명 참여자 정보	yes
items	전자서명 사전입력값 정보	yes
contract	계약서 관련 추가 정보	no
signature	전자서명 관련 추가 정보	no

{
  "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"
      }
    ],
    "contract": {
      "contractType": "NEW", // 재계약 여부 (NEW, RENEWAL)
      "customKey": "custom-id" // 연결할 맞춤 키 값 (중복 불가)
    },
    "signature": {
      "expiredDate": "2024-12-20T15:00:00.000Z", // 서명 만료일 (현재보다 이후 시간이어야 함)
      "ccEmails": [], // 참조자 이메일 목록
      "requesterName": "프릭스 컴퍼니" // 서명 요청자
    }
  }
}

Response

{
  "ok": true,
  "message": undefined, // 실패하는 경우 메시지 (string)
  "data": {
    // 전자서명 정보
    "signature": {
      "uuid": "jvakfljva-fad3edd-badfawdcah", // 전자서명 ID
      "title": "솔루션 공급 계약서", // 전자서명 제목
      "expiredDate": "2024-12-20T15:00:00.000Z", // 전자서명 만료일
      "status": "WAITING", // 상태 (WAITING은 서명 요청 후 대기 상태를 의미)
      "createdAt": "2024-10-15T00:00:00.000Z" // 생성일
    },
    "contract": {
      "uuid": "akahgk23-afasdvc-asdkhfwh3sd", // 문서 ID (uuid 값을 api에서 사용합니다)
      "file": "...contract.pdf", // 계약 문서 url
      "status": "CREATED", // 상태 (CREATED, CONCLUDED)
      "createdAt": "2024-10-15T00:00:00.000Z" // 생성일
    }
  }
}

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 합본에 실패한 경우