> For the complete documentation index, see [llms.txt](https://api-kit.prix.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-kit.prix.im/signature/create-form-url.md).

# 계약서 등록/전자서명 요청 페이지 API

계약서를 등록하거나 전자서명을 요청할 수 있는 페이지의 url을 내려줍니다. 해당 경로를 새 창이나 새 탭으로 띄워서 전자계약을 생성할 수 있습니다.

* 계약 문서를 등록하고 전자서명 정보(서명 참여자 및 서명 위치)를 입력하여 제출하면 전자서명이 시작됩니다.
* 참여자 정보에 등록한 이메일이나 전화번호로 참여 링크가 포함된 이메일/카카오톡이 발송됩니다.
* 계약서 등록/전자서명 요청 페이지에서 사용할 수 있는 기본 정보를 전달할 수 있습니다.

<br>

## `POST` kit-api/v1/contracts/form-url

Method: POST Endpoint: kit-api/v1/contracts/form-url

<br>

## Example

```
...kit-api/v1/contracts/form-url
```

```json
{
  // body input은 선택 값으로 body 없이 요청 가능
  "input": {
    "option": {
      "successUrl": "https://..."
    },
    "defaultValue": {
      "customer": {
        "id": 3,
        "customKey": "B5-k159402" // 고객에게 할당된 40자 이하의 식별 key (id 또는 customKey를 전달)
      },
      "contract": {
        "title": "계약서 이름",
        "file": "...contract.pdf", // 계약 문서 url
        "startDate": "2025-03-10T11:02:05.759Z", // Date.toISOString
        "endDate": "2025-03-10T11:02:05.759Z", // Date.toISOString
        "slugColumns": [
          // 계약서에 연결할 커스텀 컬럼 정보
          {
            "slug": "slug-column-1", // 커스텀 컬럼 식별값 (별도 연락 필요)
            "value": "slug-column-value" // 커스텀 컬럼 값 (String)
          }
        ]
      },
      "signature": {
        "participants": [
          {
            "name": "홍길동",
            "send": "EMAIL", // EMAIL 또는 PHONE
            "email": "test@prix.im",
            "phone": undefined,
            "message": "서명 입력 요청드립니다."
          }
        ]
      }
    }
  }
}
```

<br>

## Request Body

| Key                | Description                  | Required |
| ------------------ | ---------------------------- | -------- |
| input.option       | 계약서 등록/전자서명 요청 페이지에 대한 옵션    | no       |
| input.defaultValue | 계약서 등록/전자서명 요청 페이지에 채워둘 기본 값 | no       |

### Request Body : input.option

| Key            | Description                                                 | Required |
| -------------- | ----------------------------------------------------------- | -------- |
| successUrl     | 계약서 등록/전자서명 요청 완료 시 이동될 페이지 (string)                        | no       |
| disabledInputs | 계약서 등록/전자서명 요청 페이지에서 사용하지 않을 인풋 (array / ex. \["customer"]) | 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       |
| contract.slugColumns          | 생성 시 기본적으로 입력될 계약서의 커스텀 컬럼 정보                      | no       |
| contract.slugColumns\[].slug  | 생성 시 기본적으로 입력될 계약서의 커스텀 컬럼 식별값 (별도 연락 필요)          | no       |
| contract.slugColumns\[].value | 생성 시 기본적으로 입력될 계약서의 커스텀 컬럼 값 (String)              | no       |
| signature.participants        | 생성 시 기본적으로 입력될 전자서명 참여자 정보 (array)                 | no       |

### Request Body : input.defaultValue.signature.participants

| Key     | Description                                                       | Required |
| ------- | ----------------------------------------------------------------- | -------- |
| name    | 생성 시 기본적으로 입력될 전자서명 참여자의 이름 (string)                              | no       |
| send    | 생성 시 기본적으로 입력될 전자서명 참여 알림 발송 수단 (string / PHONE or EMAIL)         | no       |
| email   | 생성 시 기본적으로 입력될 전자서명 참여자의 이메일 (string)                             | no       |
| phone   | 생성 시 기본적으로 입력될 전자서명 참여자의 전화번호 (string / - 포함 / ex. 010-0000-0000) | no       |
| message | 생성 시 기본적으로 입력될 전자서명 참여자 안내 메시지 (string)                           | no       |

<br>

## Response

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

<br>

| Status Code | Error Code                                   | Description                |
| ----------- | -------------------------------------------- | -------------------------- |
| 400         | CONTRACT\_FORM\_URL\_INVALID\_DISABLE\_QUERY | 사용할 수 없는 disable 값을 사용한 경우 |

<br>