전자서명 템플릿 사용 페이지 API

전자서명 템플릿을 사용 기능은 기본적으로 프릭스 서비스를 통해 사용할 수 있지만, API를 통해서 페이지 URL을 얻어 사용할 수도 있습니다.

API 응답으로 전자서명 템플릿을 사용해 계약서를 생성하고 전자서명을 요청할 수 있는 페이지의 url을 내려주며, 해당 경로를 새 창이나 새 탭으로 띄워서 전자서명 템플릿을 사용할 수 있습니다.

POST kit-api/v1/signature-templates/[key]/use-template-url

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

Example

...kit-api/v1/signature-templates/4328/use-template-url

{
  // body input은 선택 값으로 body 없이 요청 가능
  "input": {
    "option": {
      "successUrl": "https://..."
    },
    "defaultValue": {
      "customer": {
        "id": 3
      },
      "contract": {
        "title": "계약서 이름",
        "startDate": "2025-03-10T11:02:05.759Z", // Date.toISOString
        "endDate": "2025-03-10T11:02:05.759Z" // Date.toISOString
      },
      "signature": {
        "participants": [
          {
            "role": "갑", // 템플릿 생성 시 등록한 참여자 역할
            "name": "홍길동",
            "send": "EMAIL", // EMAIL 또는 PHONE
            "email": "[email protected]",
            "phone": undefined,
            "message": "서명 입력 요청드립니다.",
            "extraAuthList": [
              {
                // 휴대폰 본인인증이 필요한 경우 해당 값 사용
                "type": "MOBILE_IDENTIFICATION",
                "phoneName": "김실명",
                "phoneNumber": "010-1234-1234"
              },
              {
                // 암호 인증이 필요한 경우 해당 값 사용
                "type": "CODE",
                "code": "1234",
                "codeHint": "암호는 1234"
              }
            ]
          }
        ]
      }
    }
  }
}

Request Body

Key	Description	Required
input.option	전자서명 템플릿 사용 페이지에 대한 옵션	no
input.defaultValue	전자서명 템플릿 사용 페이지에 채워둘 기본 값	no

Request Body : input.option

Key	Description	Required
successUrl	템플릿 사용(계약서 생성 및 전자서명 요청) 완료 시 이동될 페이지 (string)	no

Request Body : input.defaultValue

Key	Description	Required
customer.id	템플릿 사용 시 생성할 계약서에 기본적으로 연결할 고객을 설정하기 위한 식별값 (number)	no
customer.customKey	템플릿 사용 시 생성할 계약서에 기본적으로 연결할 고객 설정을 설정하기 위한 customKey 값 (string)	no
contract.title	템플릿 사용 시 생성할 계약서에 기본적으로 등록될 계약 제목 (string)	no
contract.file	기존 템플릿에 등록된 계약 문서를 대체할 pdf 형식의 계약 문서 파일 경로 (string / url)	no
contract.startDate	템플릿 사용 시 생성할 계약서에 기본적으로 입력될 계약 시작일 (string / Date의 iso 형태 문자열)	no
contract.endDate	템플릿 사용 시 생성할 계약서에 기본적으로 입력될 계약 종료일 (string / Date의 iso 형태 문자열)	no
signature.participants	템플릿 사용 시 생성할 계약서에 기본적으로 입력될 전자서명 참여자 정보 (array)	no

Request Body : input.defaultValue.signature.participants

Key	Description	Required
role	템플릿 사용 시 요청할 전자서명 참여자의 역할 (string)	yes
name	템플릿 사용 시 요청할 전자서명 참여자의 이름 (string)	no
send	템플릿 사용 시 요청할 전자서명 참여 알림 발송 수단 (string / PHONE or EMAIL)	no
email	템플릿 사용 시 요청할 전자서명 참여자의 이메일 (string)	no
phone	템플릿 사용 시 요청할 전자서명 참여자의 전화번호 (string / - 포함 / ex. 010-0000-0000)	no
message	템플릿 사용 시 요청할 전자서명 참여자 안내 메시지 (string)	no
extraAuthList	추가 인증 정보 목록	no

*참여자 추가 인증은 2가지 방식을 사용할 수 있습니다.

1. 휴대폰 본인 인증 휴대폰 본인 인증 시, 서명 참여자 이름(participant.name)이 실명이어야 하며, 본인 명의의 휴대폰 번호를 입력해야 합니다.

2. 암호 인증

Response

{
  "ok": true, // api 성공 여부
  "message": undefined, // Error가 존재하면 message(string)로 전달
  "data": {
    "url": "https://www.prix.im/..." // 대량계약을 생성할 수 있는 페이지 주소
  }
}

Status Code	Error Code	Description
404	NOT_FOUND_CUSTOMER	전자서명 템플릿 사용 시, 계약서에 연결할 고객이 존재하지 않는 경우
400	SIGNATURE_TEMPLATE_FILE_INVALID	형식에 맞지 않은 파일인 경우(pdf 형식이 아닌 경우)
500	SIGNATURE_TEMPLATE_FILE_SAVED_FAILED	파일 저장에 실패한 경우
404	NOT_FOUND_SIGNATURE_TEMPLATE	존재하지 않는 전자서명 템플릿인 경우
403	FORBIDDEN_BUSINESS	비즈니스 접근 권한이 없는 경우
400	SIGNATURE_TEMPLATE_PARTICIPANT_COUNT_MISMATCH	기본값으로 전달 받은 참여자의 수와 템플릿에 등록된 참여자 수가 일치하지 않는 경우