# 전자서명 템플릿 사용 페이지 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api-kit.prix.im/signature-template/usage-url.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.