# 전자서명 템플릿 대량계약 페이지 API

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

API 응답으로 대량계약 페이지의 url을 내려주며, 해당 경로를 새 창이나 새 탭으로 띄워서 대량계약을 진행할 수 있습니다.

* 참여자가 한 명인 템플릿으로만 대량계약을 이용할 수 있습니다.

<br>

## `POST` kit-api/v1/signature-templates/\[key]/bulk-url

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

<br>

## Example

```
...kit-api/v1/signature-templates/4328/bulk-url
```

```json
{
  "input": {
    "customerId": 3, // (Deprecated) defaultValue.customer.id를 사용해 주세요
    "customerCustomKey": "CUSTOMER-TEST-001", // (Deprecated) defaultValue.customer.customKey를 사용해 주세요
    "defaultValue": {
      "customer": {
        "id": 3,
        "customKey": "B5-k159402" // 고객에게 할당된 40자 이하의 식별 key (id 또는 customKey를 전달)
      },
      "contract": {
        "slugColumns": [
          // 계약서에 연결할 커스텀 컬럼 정보
          {
            "slug": "slug-column-1", // 커스텀 컬럼 식별값 (별도 연락 필요)
            "value": "slug-column-value" // 커스텀 컬럼 값 (String)
          }
        ]
      },
      "signature": {
        "requesterName": "요청자 이름" // 전자서명 요청자 이름
      }
    },
    "options": {
      "disabledInputs": ["REQUESTER_EMAIL"]
    },
    "items": [
      {
        "title": "테스트서명1",
        "participant": {
          "name": "김프릭",
          "send": "EMAIL",
          "email": "test@prix.im"
        },
        "customKey": "TEST-001",
        "items": [
          {
            "id": 13,
            "contents": "김프릭"
          }
        ]
      },
      {
        "title": "테스트서명2",
        "participant": {
          "name": "이래티스",
          "send": "EMAIL",
          "email": "test@lattice.im",
          "phone": "010-1234-1234", // 참여자 전화번호
          "message": "빠른 서명 요청드립니다.",
          "extraAuthList": [
            {
              // 추가 휴대폰 본인인증이 필요한 경우 해당 값 사용
              "type": "MOBILE_IDENTIFICATION",
              "phoneNumber": "010-1234-1234" // 참여자 명의의 휴대폰 번호
            },
            {
              // 추가 암호인증이 필요한 경우 해당 값 사용
              "type": "CODE",
              "code": "secret1234"
            }
          ]
        },
        "customerTitle": "ABC컴퍼니",
        "items": [
          {
            "id": 13,
            "contents": "이래티스"
          }
        ]
      }
    ]
  }
}
```

<br>

## Request Body

| Key                                  | Description                   | Required |
| ------------------------------------ | ----------------------------- | -------- |
| (Deprecated) input.customerId        | 대량계약 시 계약과 연결할 고객의 id         | no       |
| (Deprecated) input.customerCustomKey | 대량계약 시 계약과 연결할 고객의 custom key | no       |
| input.defaultValue                   | 대량계약 시 페이지에 채워둘 기본 값          | no       |
| input.options                        | 대량계약 시 페이지에서 사용할 옵션           | no       |
| input.items                          | 대량계약 서명자 및 서명 정보 기본값          | no       |

## Request Body (input.defaultValue)

| Key                           | Description                                          | Required |
| ----------------------------- | ---------------------------------------------------- | -------- |
| customer.id                   | 대량계약 시 기본적으로 연결할 고객을 설정하기 위한 식별값 (number)            | no       |
| customer.customKey            | 대량계약 시 기본적으로 연결할 고객 설정을 설정하기 위한 customKey 값 (string) | no       |
| contract.slugColumns          | 대량계약 시 기본적으로 입력될 계약서의 커스텀 컬럼 정보                      | no       |
| contract.slugColumns\[].slug  | 대량계약 시 기본적으로 입력될 계약서의 커스텀 컬럼 식별값 (별도 연락 필요)          | no       |
| contract.slugColumns\[].value | 대량계약 시 기본적으로 입력될 계약서의 커스텀 컬럼 값 (String)              | no       |
| signature.requesterName       | 대량계약 시 기본적으로 입력될 전자서명 요청자 이름 (String)                | no       |

## Request Body (input.options)

| Key            | Description                                               | Required |
| -------------- | --------------------------------------------------------- | -------- |
| disabledInputs | 대량계약 페이지에서 사용하지 않을 인풋 (array / ex. \["REQUESTER\_EMAIL"]) | no       |

## Request Body (input.items)

| Key                             | Description                            | Required |
| ------------------------------- | -------------------------------------- | -------- |
| input.items.title               | 각 서명 제목                                | yes      |
| input.items.participant         | 대량계약 서명자 정보                            | yes      |
| input.participant.name          | 대량계약 서명자 이름                            | yes      |
| input.participant.send          | 대량계약 서명 발송 수단 (EMAIL, PHONE)           | yes      |
| input.participant.email         | 대량계약 서명자 이메일 (email 또는 phone 중 하나 필수)  | no       |
| input.participant.phone         | 대량계약 참여자 전화번호 (email 또는 phone 중 하나 필수) | no       |
| input.participant.extraAuthList | 추가 인증 정보 목록                            | no       |
| input.items.items               | 계약서 생성에 필요한 사전입력값 정보                   | yes      |
| input.items.customerTitle       | 서명과 연결될 고객명                            | no       |
| input.items.customKey           | 계약서 식별을 위한 사용자 정의 키 값                  | no       |

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

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

<br>

## Response

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

<br>

| Status Code | Error Code                                    | Description                             |
| ----------- | --------------------------------------------- | --------------------------------------- |
| 400         | SIGNATURE\_TEMPLATE\_BULK\_PARTICIPANT\_COUNT | 대량서명을 이용할 수 없는 템플릿인 경우 (참여자가 1명이 아닌 경우) |
| 401         | INVALID\_BUSINESS                             | 전자서명 템플릿에 권한이 없는 경우                     |
| 404         | SIGNATURE\_TEMPLATE\_NOT\_FOUND               | 전자서명 템플릿이 존재하지 않는 경우                    |
| 404         | NOT\_FOUND\_CUSTOMER                          | 존재하지 않는 고객인 경우                          |

<br>