# 계약서 등록/전자서명 요청 페이지 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>


---

# 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/create-form-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.