> 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-template/create-signature.md).

# 전자서명 템플릿으로 서명 요청 API

전자서명 템플릿을 이용하여 계약서를 생성하고 서명을 요청할 수 있습니다.

<br>

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

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

<br>

## Example

```
.../kit-api/v1/signature-templates/4328/signatures
```

```json
{
  "input": {
    "title": "솔루션 공급 계약서",
    "participants": [
      // 전자서명 템플릿 생성/편집 시, 옵션으로 '일부 참여자에게 요청' 기능을 허용했다면 일부 참여자 정보만 전달할 수 있습니다.
      {
        "role": "갑", // 참여자 역할 (워크플로우의 참여자와 매칭)
        "input": {
          "name": "홍길동", // 참여자 이름
          "email": "gildong@prix.im", // 참여자 이메일 (이메일, 전화번호 중에 하나 필요)
          "auth": "EMAIL", // 인증 수단 (EMAIL, PHONE 존재 / send와 동일한 값으로 입력)
          "send": "EMAIL" // 발송 수단 (EMAIL, PHONE 존재)
        }
      },
      {
        "role": "을",
        "input": {
          "name": "김프릭",
          "phone": "010-1234-1234", // 참여자 전화번호
          "auth": "PHONE",
          "send": "PHONE",
          "extraAuthList": [
            {
              // 휴대폰 본인인증이 필요한 경우 해당 값 사용
              "type": "MOBILE_IDENTIFICATION",
              "phoneName": "김실명",
              "phoneNumber": "010-1234-1234"
            }
          ]
        }
      }
    ],
    "items": [
      {
        // 사전입력값 내용 추가를 위해 사용
        "id": 231, // 입력값 id (ex. "금액" 사전입력값의 id가 231인 경우)
        "contents": "2,000,000" // 입력값 내용
      },
      {
        "id": 232, // (ex. "주소" 입력값의 id가 232인 경우)
        "contents": "선릉로 551 새롬아파트 101-204"
      },
      {
        "id": 233, // (ex. "동의" 입력값의 id가 233인 경우)
        "contents": "true" // 체크박스 체크 여부 ('true' 혹은 빈 문자열)
      },
      // 사전 입력값 생성/편집 시 slug를 지정한 경우 id 대신 slug를 전달할 수 있습니다.
      {
        "slug": "object-1", // (ex. "동의" 입력값의 slug가 "object-1"인 경우)
        "contents": "true" // 체크박스 체크 여부 ('true' 혹은 빈 문자열)
      }
    ],
    "additionalFiles": ["...견적서.pdf"], // 합본할 파일 url 목록
    "contract": {
      "type": "NEW", // 재계약 여부 (선택 / NEW, RENEWAL)
      "customKey": "custom-id", // 연결할 맞춤 키 값 (선택 / 중복 불가)
      "fileToReplace": "...contract.pdf", // 실제 서명 요청 시 사용할 계약서 문서 url (주의사항: fileToReplace 필드를 사용하여 계약 문서를 변경하여 서명을 요청하는 경우, 템플릿에 등록된 계약서와 페이지 수가 동일해야 합니다.)
      "slugColumns": [
        // 계약서에 연결할 커스텀 컬럼 정보
        {
          "slug": "slug-column-1", // 커스텀 컬럼 식별값 (별도 연락 필요)
          "value": "slug-column-value" // 커스텀 컬럼 값 (String)
        }
      ],
      "connectedContractUuids": ["contract-uuid"], // 연결할 계약서 uuid 목록 (선택)
      "contractDate": {
        "startDate": "2024-10-01T00:00:00.000Z", // 시작일
        "endDate": null, // 종료일
        "concludedDate": null // 체결일
      },
      "customers": [
        // 계약서에 연결할 고객의 Id 또는 CustomKey (고객을 연결하려면 둘 중 하나는 필수로 입력해야 합니다.)
        {
          "id": 1,
          "customKey": "customer-custom-key-32"
        }
      ],
      "shareNotification": {
        // 전자서명 체결 완료 후 계약서 외부 공유 알림 설정 (수신자 여러 명 설정 가능)
        "receivers": [
          {
            "method": "EMAIL", // EMAIL, PHONE
            "contact": "test@prix.im", // PHONE인 경우, 010-xxxx-xxxx 형식
            "name": "EMAIL_TESTER"
          },
          {
            "method": "PHONE", // EMAIL, PHONE
            "contact": "010-XXXX-XXXX", // PHONE인 경우, 010-xxxx-xxxx 형식
            "name": "PHONE_TESTER"
          }
        ]
      }
    },
    "signature": {
      "expiredDate": "2024-12-20T15:00:00.000Z", // 서명 만료일 (현재보다 이후 시간이어야 함)
      "ccEmails": [], // 참조자 이메일 목록
      "requesterName": "프릭스 컴퍼니", // 서명 요청자
      "facilitator": {
        // 대면서명 진행자 정보 (대면서명 미요청 시 facilitator 필드 사용하지 않아야 함)
        "name": "대면서명 담당자", // 대면서명 진행자 이름
        "email": "facilitator@prix.im" // 대면서명 진행자 이메일
      },
      "additionalRequests": [
        {
          "role": "참관자", // 추가 참여자 역할
          "type": "EMAIL", // 발송 방식 (EMAIL, PHONE)
          "contact": "observer@prix.im" // 이메일 주소 또는 전화번호
        }
      ],
      "redirectUrl": "https://example.com/callback" // 각 서명 별 리다이렉트 시키고자 하는 경로
    },
    "option": {
      "skipSend": false // 알림 발송 스킵 여부 (선택, true 인 경우 서명 참여 알림을 발송하지 않음)
    }
  }
}
```

<br>

## Request Body

| Key                                                | Description                            | Required                |
| -------------------------------------------------- | -------------------------------------- | ----------------------- |
| input.title                                        | 전자서명 이름                                | yes                     |
| input.participants                                 | 전자서명 참여자 정보                            | yes                     |
| input.participants\[].role                         | 참여자 역할 (템플릿에 정의된 역할과 일치해야 함)           | yes                     |
| input.participants\[].input                        | 참여자 상세 정보                              | yes                     |
| input.participants\[].input.name                   | 참여자 이름                                 | yes                     |
| input.participants\[].input.email                  | 참여자 이메일 (email 또는 phone 중 하나 필수)       | no                      |
| input.participants\[].input.phone                  | 참여자 전화번호 (email 또는 phone 중 하나 필수)      | no                      |
| input.participants\[].input.auth                   | 인증 수단 (EMAIL, PHONE)                   | yes                     |
| input.participants\[].input.send                   | 발송 수단 (EMAIL, PHONE)                   | yes                     |
| input.participants\[].input.extraAuthList          | 추가 인증 정보 목록                            | no                      |
| input.additionalFiles                              | 합본할 파일 url 목록                          | no                      |
| input.items                                        | 전자서명 사전입력값 정보                          | no                      |
| input.items\[].id                                  | 사전입력값 ID                               | no (id 또는 slug 중 1개 필수) |
| input.items\[].slug                                | 사전입력값 Slug                             | no (id 또는 slug 중 1개 필수) |
| input.items\[].contents                            | 사전입력값 내용                               | yes                     |
| input.contract                                     | 계약서 관련 추가 정보                           | no                      |
| input.contract.type                                | 재계약 여부 (NEW, RENEWAL)                  | no                      |
| input.contract.customKey                           | 연결할 맞춤 키 값 (중복 불가)                     | no                      |
| input.contract.contractDate.startDate              | 계약 시작일 (string / Date의 iso 형태 문자열)     | no                      |
| input.contract.contractDate.endDate                | 계약 종료일 (string / Date의 iso 형태 문자열)     | no                      |
| input.contract.slugColumns                         | 계약서에 연결할 커스텀 컬럼 정보                     | no                      |
| input.contract.slugColumns\[].slug                 | 커스텀 컬럼 식별값 (별도 연락 필요)                  | no                      |
| input.contract.slugColumns\[].value                | 커스텀 컬럼 값 (String)                      | no                      |
| input.contract.connectedContractUuids              | 연결할 계약서 uuid 목록                        | no                      |
| input.contract.customers                           | 계약서에 연결할 고객 정보                         | no                      |
| input.contract.customers\[].id                     | 계약서에 연결할 고객 id (Number)                | no                      |
| input.contract.customers\[].customKey              | 계약서에 연결할 고객 customKey (String)         | no                      |
| input.contract.shareNotification                   | 전자서명 체결 완료 후 계약서 외부 공유 알림 설정           | no                      |
| input.contract.shareNotification.receivers.method  | 전자서명 체결 완료 후 계약서 외부 공유 알림 설정 (전송 방법)   | yes                     |
| input.contract.shareNotification.receivers.contact | 전자서명 체결 완료 후 계약서 외부 공유 알림 설정 (수신자 연락처) | yes                     |
| input.contract.shareNotification.receivers.name    | 전자서명 체결 완료 후 계약서 외부 공유 알림 설정 (수신자 이름)  | yes                     |
| input.signature                                    | 전자서명 관련 추가 정보                          | no                      |
| input.signature.expiredDate                        | 서명 만료일 (현재보다 이후 시간)                    | no                      |
| input.signature.ccEmails                           | 참조자 이메일 목록                             | no                      |
| input.signature.requesterName                      | 서명 요청자 이름                              | no                      |
| input.signature.facilitator                        | 대면서명 진행자 정보 (대면서명 시 사용)                | no                      |
| input.signature.facilitator.name                   | 대면서명 진행자 이름                            | 대면서명 시 yes              |
| input.signature.facilitator.email                  | 대면서명 진행자 이메일                           | 대면서명 시 yes              |
| input.signature.additionalRequests                 | 추가 발송 참여자 정보                           | no                      |
| input.signature.additionalRequests\[].role         | 추가 참여자 역할                              | no                      |
| input.signature.additionalRequests\[].type         | 발송 방식 (EMAIL, PHONE)                   | no                      |
| input.signature.additionalRequests\[].contact      | 연락처 (이메일 또는 전화번호)                      | no                      |
| input.signature.redirectUrl                        | 리다이렉트 경로                               | no                      |
| input.option                                       | 전자서명 옵션 정보                             | no                      |
| input.option.skipSend                              | 알림 발송 스킵 여부 (true 시 알림 발송 안함)          | no                      |

<br>

## Response

```json
{
  "ok": true,
  "message": undefined, // 실패하는 경우 메시지 (string)
  "data": {
    // 전자서명 정보
    "signature": {
      "uuid": "57139f5c-37d0-4c30-bdb6-ef6106040756", // 전자서명 식별값
      "title": "솔루션 공급 계약서", // 전자서명 제목
      "expiredDate": "2024-12-20T15:00:00.000Z", // 전자서명 만료일
      "status": "WAITING", // 상태 (WAITING은 서명 요청 후 대기 상태를 의미)
      "createdAt": "2024-10-15T00:00:00.000Z", // 생성일
      "ccEmails": null,
      "facilitator": {
        // 대면서명 진행자 정보 (대면서명 요청 시 값 존재)
        "uuid": "8053804d-581a-4e99-91e3-c077dc461373",
        "name": "대면서명 담당자",
        "email": "facilitator@prix.im"
      },
      "participants": [
        {
          "uuid": "689a0e2b-db58-4f16-9b9a-e745408de889", // 참여자 식별값
          "name": "홍길동", // 참여자 이름
          "status": "CREATED", // 참여자 상태
          "order": 1, // 참여 순서
          "email": "gildong@prix.im", // 참여자 이메일
          "send": "EMAIL", // 발송 수단
          "message": null, // 발송 메시지
          "language": "KOREAN", // 언어 설정
          "extraAuthList": null, // 추가 인증 정보
          "role": "갑" // 참여자 역할
        }
      ]
    },
    "contract": {
      "uuid": "ed976505-bcbd-47bd-913d-f4cde05dea7a", // 문서 식별값 (uuid 값을 api에서 사용합니다)
      "file": "...contract.pdf", // 계약 문서 url
      "status": "CREATED", // 상태 (CREATED, CONCLUDED)
      "createdAt": "2024-10-15T00:00:00.000Z", // 생성일
      "type": "NEW",
      "contractDate": {
        "startDate": null,
        "endDate": null
      }
    }
  }
}
```

<br>

| Status Code | Error Code                                                  | Description                             |
| ----------- | ----------------------------------------------------------- | --------------------------------------- |
| 400         | INVALID\_SIGNATURE\_TITLE                                   | title이 없는 경우                            |
| 400         | INVALID\_SIGNATURE\_EXPIRED\_DATE                           | signature의 expiredDate가 현재 시간 이후가 아닌 경우 |
| 400         | NOT\_ALLOWED\_PARTICIPANT\_MINIMUM\_LENGTH                  | 전자서명 템플릿에 설정된 모든 참여자에 대한 정보가 없는 경우      |
| 400         | INVALID\_ADDITIONAL\_INPUT                                  | 추가 입력값이 없는 경우                           |
| 400         | SIGNATURE\_PARTICIPANT\_EMPTY\_ADDITIONAL\_REQUEST\_INPUT   | 추가 발송 참여자와 값이 없는 경우                     |
| 400         | SIGNATURE\_PARTICIPANT\_INVALID\_ADDITIONAL\_REQUEST\_EMAIL | 추가 발송 참여자의 email 주소가 잘못된 경우             |
| 400         | SIGNATURE\_PARTICIPANT\_INVALID\_ADDITIONAL\_REQUEST\_PHONE | 추가 발송 참여자의 전화번호가 잘못된 경우                 |
| 400         | EXISTING\_CONTRACT\_KEY                                     | 계약서의 custom key가 이미 존재하는 경우             |
| 400         | FAILED\_USE\_SIGNATURE\_TEMPLATE                            | 전자서명 템플릿 사용중 알 수 없는 에러가 발생한 경우          |
| 403         | NOT\_ALLOWED\_PASS\_AUTH\_NOT\_ENOUGH                       | 휴대폰 본인인증을 위한 크레딧이 부족한 경우                |
| 404         | NOT\_FOUND\_SIGNATURE\_TEMPLATE                             | 전자서명 템플릿이 존재하지 않는 경우                    |
| 404         | NOT\_FOUND\_BUSINESS                                        | 전자서명 템플릿과 연결된 비즈니스가 존재하지 않는 경우          |
| 404         | NOT\_FOUND\_USER                                            | 전자서명 템플릿과 연결된 사용자가 존재하지 않는 경우           |
| 404         | SIGNATURE\_TEMPLATE\_NOT\_FOUND                             | 전자서명 템플릿이 존재하지 않는 경우                    |
| 500         | FAILED\_CREATE\_CONTRACT                                    | 계약서 생성 중 알 수 없는 에러가 발생한 경우              |
| 500         | FAILED\_CREATE\_SIGNATURE                                   | 전자서명 생성 중 알 수 없는 에러가 발생한 경우             |
| 500         | FAILED\_MERGE\_CONTRACT                                     | pdf 합본에 실패한 경우                          |

<br>