# 전자서명 템플릿 대량계약 페이지 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>


---

# 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/bulk-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.