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

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

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

<br>

## `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(문자)를 의미

<br>

## Example

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

```json
{
  // 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": "test@prix.im",
            "phone": undefined,
            "message": "서명 입력 요청드립니다.",
            "extraAuthList": [
              {
                // 휴대폰 본인인증이 필요한 경우 해당 값 사용
                "type": "MOBILE_IDENTIFICATION",
                "phoneName": "김실명",
                "phoneNumber": "010-1234-1234"
              },
              {
                // 암호 인증이 필요한 경우 해당 값 사용
                "type": "CODE",
                "code": "1234",
                "codeHint": "암호는 1234"
              }
            ]
          }
        ]
      }
    }
  }
}
```

<br>

## 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       |

<br>

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

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

## Response

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

<br>

| 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 | 기본값으로 전달 받은 참여자의 수와 템플릿에 등록된 참여자 수가 일치하지 않는 경우 |

<br>