# 전자서명 템플릿으로 서명 요청 API 전자서명 템플릿을 이용하여 계약서를 생성하고 서명을 요청할 수 있습니다.
## `POST` kit-api/v1/signature-templates/\[key]/signatures Method: POST\ Endpoint: kit-api/v1/signature-templates/\[key]/signatures\ Param: key는 전자서명 템플릿의 id(숫자) 혹은 slug(문자) 값을 의미
## 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 인 경우 서명 참여 알림을 발송하지 않음) } } } ```
## 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 |
## 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 } } } } ```
| 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 합본에 실패한 경우 |
--- # 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/create-signature.md?ask= ``` 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.