# 프릭스 전자서명 API 키트 API로 쉽고 빠르게 연동할 수 있는 프릭스 전자서명 키트의 가이드 문서입니다.\ 최소한의 리소스로 서비스와 연동하여 간편하게 전자서명 서비스를 이용해 보세요. 👉 [프릭스에 문의하기](https://37plx.channel.io/home) > 프릭스 API 키트는 다양한 맞춤 기능을 제공합니다.\ > 서명 알림과 페이지 내 브랜드 로고를 사용하는 것 뿐만 아니라, 계약 생성 및 체결 과정의 다양한 요소를 기업에 맞게 제공하는 등 서비스의 시나리오 및 회사 내 프로세스에 가장 적합한 방법을 함께 찾아 드립니다. # API 사용하기 프릭스 전자서명 키트 API를 통해 전자서명 기능을 간편하게 사용할 수 있습니다. 프릭스 API는 header의 x-api-key에 API key 값을 사용하여 호출할 수 있습니다.
## (1) 계정 생성하기 프릭스 전자서명 키트 API를 이용하기 위해서는 프릭스 계정 생성이 필요합니다. 👉 [프릭스에 문의하기](https://www.prix.im/?utm_source=kit-api\&utm_medium=pcmo_guide\&utm_campaign=240913_others\&utm_content=kit-api-guide_)
## (2) API Key 발급받기 프릭스 서비스에 가입 후 로그인하면 API key를 발급 받을 수 있습니다.\ 자세한 발급 방법 및 API url 경로는 가입 후 문의주시면 별도로 안내드립니다.
## (3) API 권한 연결하기 프릭스 API를 사용하기 위해서는 비즈니스에 등록된 멤버와의 권한 연결이 필요합니다.
프릭스 API 권한 설정
* 예를 들어 관리자 멤버와 권한을 연결하면 API는 관리자 권한을 갖고 요청을 수행하거나 목록을 조회할 수 있습니다. * 설정 > 멤버 관리 페이지의 멤버 목록에서 권한을 연결할 멤버의 ‘…’ 메뉴 > ‘편집’을 누르면 멤버 편집 모달이 나타납니다. * 나타나는 멤버 모달의 ‘API 권한 설정’ 섹션에서 ‘API 권한 연결’ 토글을 켭니다. 연결된 멤버 하나로 계약서, 전자서명, 영업문서, 프로젝트, 일정 등 모든 API를 사용할 수 있습니다. * API 권한은 비즈니스당 한 명의 멤버에게만 연결할 수 있으며, 목록 조회 API는 연결된 멤버가 속한 팀의 조회 권한 범위로 결과를 반환합니다. 전체 데이터를 조회하려면 모든 데이터를 볼 수 있는 팀(관리자 팀 등)의 멤버와 연결해 주세요.
## (4) API 호출하기 프릭스 API를 호출하기 위해서는 발급받은 key를 header에 넣어서 사용하면 됩니다. ## Request Header | Key | Description | Required | | --------- | ------------ | -------- | | x-api-key | 발급받은 API Key | yes | ## 공통 Error Codes | Status Code | Error Code | Description | | ----------- | ------------------------------ | ---------------------------------- | | 403 | FORBIDDEN\_BUSINESS | API Key에 권한이 없는 비즈니스에 접근하는 경우 | | 403 | NOT\_MATCHES\_PERMISSION\_USER | API Key에 권한을 가진 사용자가 연결되어 있지 않은 경우 | | 403 | FORBIDDEN\_BUSINESS\_KEY | API Key에 권한이 없는 경우 | | 404 | NOT\_FOUND\_BUSINESS | API Key에 연결된 비즈니스가 없는 경우 | | 500 | UNDEFINED\_ERROR\_CODE | 알 수 없는 에러가 발생한 경우 |
# 계약서/전자서명 사용하기 계약서/전자서명 기능을 자유롭게 활용할 수 있도록 다양한 API를 제공합니다. 계약서/전자서명 기능을 자유롭게 활용할 수 있도록 다양한 API를 제공합니다. # 계약서 등록/전자서명 요청 페이지 API 계약서를 등록하거나 전자서명을 요청할 수 있는 페이지를 반환하는 API를 제공합니다. 계약서를 등록하거나 전자서명을 요청할 수 있는 페이지의 url을 내려줍니다. 해당 경로를 새 창이나 새 탭으로 띄워서 전자계약을 생성할 수 있습니다. * 계약 문서를 등록하고 전자서명 정보(서명 참여자 및 서명 위치)를 입력하여 제출하면 전자서명이 시작됩니다. * 참여자 정보에 등록한 이메일이나 전화번호로 참여 링크가 포함된 이메일/카카오톡이 발송됩니다. * 계약서 등록/전자서명 요청 페이지에서 사용할 수 있는 기본 정보를 전달할 수 있습니다.
## `POST` kit-api/v1/contracts/form-url Method: POST Endpoint: kit-api/v1/contracts/form-url
## 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": "서명 입력 요청드립니다." } ] } } } } ```
## 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 |
## Response ```json { "ok": true, // api 성공 여부 "message": undefined, // Error가 존재하면 message(string)로 전달 "data": { "url": "https://www.prix.im/..." // 계약서 및 전자서명을 등록할 수 있는 페이지 주소 } } ```
| Status Code | Error Code | Description | | ----------- | -------------------------------------------- | -------------------------- | | 400 | CONTRACT\_FORM\_URL\_INVALID\_DISABLE\_QUERY | 사용할 수 없는 disable 값을 사용한 경우 |
# 계약서/전자서명 조회 API 계약서 및 전자계약에 대한 정보/현황을 조회할 수 있는 API를 제공합니다. 계약서 및 전자계약에 대한 정보/현황을 조회할 수 있는 API입니다.
## `GET` kit-api/v1/contracts/find Method: GET\ Endpoint: kit-api/v1/contracts/find
## Example ``` ...kit-api/v1/contracts/find?uuid=ed976505-bcbd-47bd-913d-f4cde05dea7a ```
## Request Query | Key | Description | Required | | ------------------------------ | ----------------------------------- | -------------------- | | uuid | 계약서 식별값으로 정보를 조회하는 경우 사용 | 조건부 yes (둘 중에 하나 필수) | | customKey | 별도 식별값으로 계약서(및 전자서명) 정보를 조회하는 경우 사용 | 조건부 yes (둘 중에 하나 필수) | | includeParticipantRequirements | 전자서명 참여자의 첨부파일 조회하는 경우 사용 | no |
## Response ```json { "ok": true, // api 성공 여부 "message": undefined, // Error가 존재하면 message(string)로 전달 "data": { // 계약 정보 (contract) "contract": { "id": "1", // 고유 id "uuid": "ed976505-bcbd-47bd-913d-f4cde05dea7a", // 문서 식별값(고유 식별 uuid) (uuid 값을 api에서 사용합니다) "concludedFile": "...concluded.pdf", // 체결된 계약 문서 url (nullable, 요청 후 10분만 유효합니다.) "title": "A컴퍼니 MOU", // 계약서 이름 "customers": [ { // contract에 연결된 고객 목록 "id": 1, "title": "파트너 고객사", "customKey": "A5-k159402" // 고객에게 할당된 40자 이하의 식별 key } ], // 계약 연결 고객 "file": "...contract.pdf", // 원본 계약 문서 url (요청 후 10분만 유효합니다.) "createdAt": "2024-07-05T00:00:00.000Z", // 생성일 "updatedAt": "2024-07-05T00:00:00.000Z", // 수정일 "customKey": "a4-k1234", // 커스텀 계약 ID - // 계약서 구분을 위한 key값을 사용한 경우, 해당 필드로 생성됨 "status": "CREATED", // 계약 상태 (CREATED, CONCLUDED, DELETED) "type": "NEW", // 계약서 유형 - 재계약 여부 (NEW, RENEWAL) "wordFile": "...contract.docx", // 계약 문서 url (word 파일로 계약서를 등록한 경우, 원본 word) "contractDate": { "concludedDate": "2024-07-05T00:00:00.000Z", // 계약 체결일 "startDate": "2024-07-05T00:00:00.000Z", // 계약 시작일 "endDate": "2024-07-05T00:00:00.000Z" // 계약 종료일 }, "managerNames": ["이용우"], // 계약서 담당자 이름 목록 "signature": { // 전자서명 정보 "uuid": "57139f5c-37d0-4c30-bdb6-ef6106040756", // 전자서명 식별값 "title": "A컴퍼니 MOU 전자서명", // 전자서명 제목 "expiredDate": "2024-10-15T00:00:00.000Z", // 전자서명 만료일 "status": "WAITING", // 전자서명 상태 (CREATED, WAITING, DONE, CANCELED) "createdAt": "2024-07-15T00:00:00.000Z", // 생성일 "participants": [], // 전자서명 참여자 정보 (uuid, name, status, auth, send, email, phone, role, language, requirements(includeParticipantRequirements가 true인 경우에만 응답 결과에 포함)) "objects": [ { // 전자서명 입력값 정보 "contents": "서울시 강남구 선릉로 551", // 내용 "type": "TEXT", // 종류 (TEXT, SIGNATURE, CHECKBOX) "category": "DEFAULT", // 유형 (DEFAULT, INPUT) "name": "주소", // 이름 "description": "상세 주소를 입력해 주세요." // 설명 } ] } } } } ```
| Status Code | Error Code | Description | | ----------- | ------------------------------ | --------------------- | | 400 | INVALID\_CUSTOMER\_CUSTOM\_KEY | 규칙을 벗어난 customKey인 경우 | | 404 | NOT\_FOUND\_CUSTOMER | 존재하지 않는 고객인 경우 |
# 계약서/전자서명 상세 페이지 API 계약 및 전자서명에 대한 상세 정보를 확인할 수 있는 페이지를 호출하는 API를 제공합니다. 응답으로 계약서/전자서명에 대한 상세 정보 페이지의 url을 내려줍니다. 해당 경로를 새 창이나 새 탭으로 띄워서 계약 및 전자서명에 대한 상세 정보를 확인할 수 있습니다.
## `GET` kit-api/v1/contracts/\[contract uuid]/url Method: GET\ Endpoint: kit-api/v1/contracts/\[contract uuid]/url
## Example ``` ...kit-api/v1/contracts/ed976505-bcbd-47bd-913d-f4cde05dea7a/url ```
## Response ```json { "ok": true, // api 성공 시 "data": { "url": "https://www.prix.im/..." // 계약서/전자서명에 대한 상세 정보 페이지 주소 } } ```
```json { "ok": false, // api 실패 시 "message": "유효하지 않은 API KEY 정보입니다.", // header에 x-api-key가 유효하지 않는 경우 "errorCode": "UNAUTHORIZED_API_KEY" } ```
```json { "ok": false, // api 실패 시 "message": "권한이 없는 유저입니다.", // 비즈니스에 등록된 API 멤버의 권한이 해당 계약서에 대한 권한이 없는 경우 "errorCode": "FORBIDDEN_USER" } ```
| Status Code | Error Code | Description | | ----------- | -------------------- | ----------------- | | 401 | FORBIDDEN\_BUSINESS | 헤당 계약서에 권한이 없는 경우 | | 404 | NOT\_FOUND\_CUSTOMER | 존재하지 않는 고객인 경우 |
# 계약서/전자서명 목록 조회 API 계약서 목록을 조회할 수 있는 API를 제공합니다. 계약서 목록을 조회할 수 있는 API입니다.
## `GET` kit-api/v1/contracts Method: GET\ Endpoint: kit-api/v1/contracts
## Example ``` ...kit-api/v1/contracts?limit=10&offset=0 ```
## Request Query | Key | Description | Required | | ------------------ | ------------------------------------------------------- | -------- | | customerCustomKeys | 해당 customKeys 속성을 가진 고객들과 연결된 계약서 목록을 조회 | no | | customerIds | 해당 id 속성을 가진 고객들과 연결된 계약서 목록을 조회 | no | | title | 제목으로 계약서 조회 (string) | no | | customer | 고객이름으로 계약서 조회 (string) | no | | participantName | 서명참여자 이름으로 계약서 조회 (string) | no | | participantEmail | 서명참여자 이메일로 계약서 조회 (string) | no | | participantPhone | 서명참여자 전화번호로 계약서 조회 (string) | no | | type | 해당 타입에 해당하는 계약서 조회 (NEW, RENEWAL) | no | | status | 계약 체결 여부에 따른 계약서 조회 (CREATED, CONCLUDED) | no | | tagIds | 해당 tagIds 속성을 가진 태그들과 연결된 계약서 목록을 조회 | no | | signature | 전자서명 존재 여부에 따라 계약서 조회 (included, excluded) | no | | periodStatus | 기간 상태에 해당하는 계약서 조회 (before, ongoing, after) | no | | createdAtAfter | 해당 날짜 이후 생성된 계약서 조회 (date) | no | | createdAtBefore | 해당 날짜 이전 생성된 계약서 조회 (date) | no | | endDateAfter | 종료일이 해당 날짜 이후인 계약서 조회 (date) | no | | endDateBefore | 종료일이 해당 날짜 이전인 계약서 조회 (date) | no | | limit | 한 번에 몇 개의 값을 받아올지 의미하는 숫자 (max 100) | no | | offset | offset 개수 이후만큼의 limit 개수를 조회 | no | | hasNoCustomer | 고객과 연결되지 않은 목록만 조회 (값: true) | no | | dealUuids | 해당 uuid 속성을 가진 프로젝트들과 연결된 계약서 목록을 조회 (콤마 구분) | no | | slugColumnKeys | 검색할 칼럼을 특정하기 위한 slug값 (string) | no | | slugColumnValues | 검색할 칼럼에 해당하는 검색값으로 slugColumnKeys 값이 존재하면 필수 (string) | no | | orderKey | 정렬 옵션 (값: endDate, startDate, createdAt, concludedDate) | no | | orderValue | 정렬의 내림차순/올림차순 여부 (값: ASC, DESC) | no |
## Response \*계약서 파일은 계약서 상세 조회 API를 이용해 주세요. * file, concludedFile의 url은 외부에서 사용할 수 없습니다. (프릭스 서비스에서만 열람이 가능합니다) * 계약서 파일을 사용(파일을 외부로 다운로드 등)하기 위해서는 계약서 상세 조회 API를 사용해야 합니다. ```json { "ok": true, // api 성공 "data": { "total": 1, "contracts": [ { // 계약서의 파일은 계약서 상세 조회 API에서 조회할 수 있습니다. "id": 1, "uuid": "ed976505-bcbd-47bd-913d-f4cde05dea7a", // 문서 식별값 (uuid 값을 api에서 사용합니다) "customKey": "a4-k1234", // 커스텀 계약 ID "title": "A컴퍼니 MOU", // 계약서 이름 "status": "CREATED", // 계약 상태 (CREATED, CONCLUDED) "type": "NEW", // 신규계약/재계약 여부 (NEW, RENEWAL) "createdAt": "2024-07-05T00:00:00.000Z", // 생성일 "updatedAt": "2024-10-15T00:00:00.000Z", // 변경일 "contractDate": { "startDate": "2024-10-01T00:00:00.000Z", // 시작일 "endDate": null, // 종료일 "concludedDate": null // 체결일 }, "signature": { // 전자서명 정보 "id": 1, "uuid": "57139f5c-37d0-4c30-bdb6-ef6106040756", // 전자서명 식별값 "title": "A컴퍼니 MOU 전자서명", // 전자서명 제목 "expiredDate": "2024-10-15T00:00:00.000Z", // 전자서명 만료일 "status": "WAITING", // 전자서명 상태 (CREATED, WAITING, DONE, CANCELED) "createdAt": "2024-07-15T00:00:00.000Z", // 생성일 "updatedAt": "2024-10-15T00:00:00.000Z", // 변경일 "participants": [], // 전자서명 참여자 정보 (uuid, name, status, auth, send, email, phone, role, language) "objects": [ { // 전자서명 입력값 정보 "id": 1, "contents": "서울시 강남구 선릉로 551", // 내용 "type": "TEXT", // 종류 (TEXT, SIGNATURE, CHECKBOX) "category": "DEFAULT", // 유형 (DEFAULT, INPUT) "name": "주소", // 이름 "description": "상세 주소를 입력해 주세요." // 설명 } ] }, "columnItems": [ // 별도 컬럼 { value: "ABCDE", slug: "service-key", name: "자체 구분값" } ] } ] } } ```
```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
| Status Code | Error Code | Description | | ----------- | ----------------------------------------- | ---------------------------------------------------- | | 400 | INVALID\_CUSTOMER\_CUSTOM\_KEY | 규칙을 벗어난 customKey인 경우 | | 400 | SLUG\_COLUMN\_KEYS\_AND\_VALUES\_MISMATCH | slugColumnKeys 값과 slugColumnValues 값 중에서 하나만 존재하는 경우 |
# 계약서/전자서명 목록 페이지 API 계약서 목록 페이지를 조회할 수 있는 API를 제공합니다. 계약서 목록 페이지를 조회할 수 있는 API입니다.
## `GET` kit-api/v1/contracts/url Method: GET\ Endpoint: kit-api/v1/contracts/url
## Example ``` ...kit-api/v1/contracts/url ```
## Request Query | Key | Description | Required | | ----------------- | -------------------------------------- | -------- | | customerCustomKey | 해당 customKey 속성을 가진 고객과 연결된 계약서 목록을 조회 | no | | customerId | 해당 id 속성을 가진 고객과 연결된 계약서 목록을 조회 | no | | hasNoCustomer | 고객과 연결되지 않은 목록만 조회 (값: true) | no |
## Response ```json { "ok": true, // api 성공 "data": { "url": "https://www.prix.im/..." // 계약서 목록 페이지 url } } ```
```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
| Status Code | Error Code | Description | | ----------- | ------------------------------ | --------------------- | | 400 | INVALID\_CUSTOMER\_CUSTOM\_KEY | 규칙을 벗어난 customKey인 경우 | | 404 | NOT\_FOUND\_CUSTOMER | 존재하지 않는 고객인 경우 |
# 체결된 계약서 및 감사추적 인증서 다운로드 URL 조회 API 체결된 계약서의 날인본과 감사추적 인증서 다운로드 URL을 조회하는 API를 제공합니다. 체결된 전자서명 계약서의 날인본과 감사추적 인증서 다운로드 URL을 조회할 수 있는 API입니다.
## `GET` kit-api/v1/contracts/download/concluded-contract-files-url Method: GET\ Endpoint: kit-api/v1/contracts/download/concluded-contract-files-url
## Example ``` ...kit-api/v1/contracts/download/concluded-contract-files-url?uuid=ed976505-bcbd-47bd-913d-f4cde05dea7a ``` ``` ...kit-api/v1/contracts/download/concluded-contract-files-url?customKey=CN-2025-001 ```
## Request Query | Key | Description | Required | | --------- | ---------------------------- | -------------------- | | uuid | 계약서 UUID로 체결 파일을 조회하는 경우 사용 | 조건부 yes (둘 중에 하나 필수) | | customKey | 계약서 커스텀 키로 체결 파일을 조회하는 경우 사용 | 조건부 yes (둘 중에 하나 필수) | **참고**: `uuid`와 `customKey`는 모두 계약서 기준 값입니다. 둘 중 하나만 전달해야 합니다.
## Response ```json { "ok": true, // api 성공 여부 "data": { "concludedFile": "https://...", // 체결된 계약서 날인본 다운로드 URL (요청 후 30분만 유효합니다.) "certificate": "https://..." // 감사추적 인증서 다운로드 URL (요청 후 30분만 유효합니다.) } } ``` 감사추적 인증서는 체결 직후 아직 생성 준비가 완료되지 않았을 수 있습니다. 이 경우 `SIGNATURE_CERTIFICATE_NOT_READY` 에러가 반환되며, 잠시 후 같은 요청을 다시 시도해 주세요.
```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
| Status Code | Error Code | Description | | ----------- | ------------------------------------- | ------------------------------------------ | | 400 | DELETED\_CONTRACT | 삭제된 계약서인 경우 | | 401 | UNAUTHORIZED\_API\_KEY | API Key가 전달되지 않은 경우 | | 403 | NOT\_MATCHES\_PERMISSION\_USER | API Key에 계약서 API 권한을 가진 사용자가 연결되어 있지 않은 경우 | | 403 | FORBIDDEN\_BUSINESS | 해당 계약서의 워크스페이스 권한이 없는 경우 | | 403 | FORBIDDEN\_PERMISSION | 현재 팀에 해당 계약서 접근 권한이 없는 경우 | | 404 | NOT\_FOUND\_BUSINESS | API Key에 연결된 워크스페이스가 없는 경우 | | 404 | NOT\_FOUND\_CONTRACT | 계약서를 조회할 수 없는 경우 | | 404 | CONTRACT\_CONCLUDED\_FILE\_NOT\_FOUND | 계약서 체결본이 없는 경우 | | 404 | NOT\_FOUND\_SIGNATURE | 계약서에 연결된 전자서명 정보가 없는 경우 | | 409 | SIGNATURE\_CERTIFICATE\_NOT\_READY | 감사추적 인증서 생성 준비가 아직 완료되지 않은 경우 |
# 전자서명 목록 조회 API 전자서명 목록을 조회할 수 있는 API를 제공합니다. 전자서명 목록을 조회할 수 있는 API를 제공합니다.
## `GET` kit-api/v1/signatures Method: GET\ Endpoint: kit-api/v1/signatures
## Example ``` ...kit-api/v1/signatures?createdAtAfter=2024-11-19T06:00:00.000Z ```
## Request Query | Key | Description | Required | | --------------- | ------------------------------------- | -------- | | createdAtAfter | 특정시간 이후의 사용량 목록 조회용 파라미터 (ISO UTC 포맷) | no | | createdAtBefore | 특정시간 이전의 사용량 목록 조회용 파라미터 (ISO UTC 포맷) | no | | limit | 목록 개수 (default 10, max 100) | no | | offset | 스킵할 목록 개수 | no |
## Response ```json { "ok": true, "data": { "total": 1, "data": [ { "uuid": "57139f5c-37d0-4c30-bdb6-ef6106040756", // 전자서명 식별값 "title": "A컴퍼니 MOU 전자서명", // 전자서명 제목 "expiredDate": "2024-10-15T00:00:00.000Z", // 전자서명 만료일 "status": "WAITING", // 전자서명 상태 (CREATED, WAITING, DONE, CANCELED) "createdAt": "2024-07-15T00:00:00.000Z" // 생성일 } ] } } ``` ```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
# 전자서명 사용량 조회 API 전자서명 사용량을 확인할 수 있는 API를 제공합니다. 전자서명 사용량을 조회할 수 있는 API를 제공합니다.
## `GET` kit-api/v1/signatures/usage Method: GET\ Endpoint: kit-api/v1/signatures/usage
## Example ``` ...kit-api/v1/signatures/usage?createdAtAfter=2024-11-19T06:00:00.000Z ```
## Request Query | Key | Description | Required | | --------------- | ------------------------------------- | -------- | | createdAtAfter | 특정시간 이후의 사용량 목록 조회용 파라미터 (ISO UTC 포맷) | no | | createdAtBefore | 특정시간 이전의 사용량 목록 조회용 파라미터 (ISO UTC 포맷) | no |
## Response ```json { "ok": true, "data": { "total": 15, // 전체 개수 "created": 4, // status: CREATED 경우 - 생성되었는데 요청되기 전 상태 (특수 상황) "done": 6, // status: DONE 경우 - 체결된 상태 "waiting": 3, // status: WAITING 경우 - 서명 요청 후 체결 전 상태 "canceled": 2 // status: CANCELED 경우 - 서명이 취소된 상태 } } ``` ```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
# 전자서명 알림 발송 API 전자서명 참여 및 완료에 대한 알림을 발송할 수 있도록 API를 제공합니다. 기본적으로 전자서명을 요청할 때 프릭스에서는 서명 참여자에게 알림을 발송합니다. 만약 추가적으로 다시 알림을 발송하고 싶은 경우에는 전자서명 알림 발송 API를 활용할 수 있습니다.
## `POST` kit-api/v1/signatures/\[signature uuid]/send Method: POST\ Endpoint: kit-api/v1/signatures/\[signature uuid]/send
## Example ``` ...kit-api/v1/signatures/57139f5c-37d0-4c30-bdb6-ef6106040756/send ``` ```json { "participantUuid": "e65664ca-bac4-4f94-81bc-bc1a2436543b", "type": "REQUEST", "sendInput": { "sendType": "EMAIL", // 발송 수단: EMAIL, PHONE "sendAddress": "test@prix.im" // 전화번호의 경우 '-' 포함 } } ```
## Request Body | Key | Description | Required | | --------------- | ----------------------------------------------------------- | -------- | | participantUuid | 해당 전자서명 참여자 중 알림을 발송하고자 하는 참여자에 대한 식별값 (string) | yes | | type | 발송하고자 하는 알림 종류 (REQUEST: 참여 요청, DONE: 완료 안내 / 기본값: REQUEST) | no | | sendInput | 발송 수단 및 연락처 (기본값: 전자서명 요청에 사용된 기본 발송 수단 및 연락처) | no |
## Response ```json { "ok": true, // api 성공 여부 "message": undefined, // Error가 존재하면 message(string)로 전달 "data": { "participantUuid": "e65664ca-bac4-4f94-81bc-bc1a2436543b", // 전자서명 참여자 식별값 "sendType": "EMAIL", // 발송 수단 (EMAIL, PHONE) "sendAddress": "test@prix.im" // 발송 번호 혹은 이메일 } } ``` # 전자서명 참여 페이지 조회 API 전자서명 참여 페이지를 조회할 수 있도록 API를 제공합니다. 전자서명 참여 페이지를 조회할 수 있도록 API를 제공합니다.
## `GET` kit-api/v1/signatures/\[signature uuid]/link Method: GET\ Endpoint: * kit-api/v1/signatures/\[signature uuid]/link?participantUuid=\[participant uuid] * kit-api/v1/signatures/\[signature uuid]/link?facilitatorUuid=\[facilitator uuid]
**참고**: `participantUuid` 또는 `facilitatorUuid` 중 하나는 반드시 제공해야 합니다.
## Request Query | Key | Type | Required | Description | | --------------- | ------ | -------- | ----------------------------------------------------------- | | participantUuid | string | 조건부 필수\* | 전자서명 참여자 UUID | | facilitatorUuid | string | 조건부 필수\* | 대면서명 진행자 UUID | | defaultValue | string | no | 인증 입력란에 채워둘 기본값 (인증 수단이 핸드폰일 경우 '-' 포함 / ex. 010-0000-0000) |
## Example ``` ...kit-api/v1/signatures/57139f5c-37d0-4c30-bdb6-ef6106040756/link?participantUuid=e65664ca-bac4-4f94-81bc-bc1a2436543b ``` ``` ...kit-api/v1/signatures/57139f5c-37d0-4c30-bdb6-ef6106040756/link?facilitatorUuid=57d8f64f-3dbb-4b70-b4f7-e95a9fd1f96e ```
## Response ```json { "ok": true, // api 성공 여부 "message": undefined, // Error가 존재하면 message(string)로 전달 "data": { "link": "https://www.prix.im/..." // 전자서명 참여 페이지 링크 } } ```
| Status Code | Error Code | Description | | ----------- | ----------------------------------------- | ----------------------------- | | 400 | INVALID\_SIGNATURE\_PARTICIPANT\_UUID | 올바른 서명 참여자 UUID가 아닌 경우 | | 400 | SIGNATURE\_INVALID\_FACILITATOR\_UUID | 올바른 서명 참여자 UUID가 아닌 경우 (대면서명) | | 400 | SIGNATURE\_INVALID\_DEFAULT\_VALUE\_INPUT | 인증수단에 맞는 올바른 인증값이 아닌 경우 |
# 전자서명 취소 API 요청된 전자서명을 취소하는 경우 사용할 수 있는 API입니다. 요청된 전자서명을 취소하는 경우 사용할 수 있는 API입니다. * 서명이 체결 완료되기 전에만 취소가 가능합니다. * 서명 참여자에게 전자서명 취소 메시지가 발송됩니다.
## `POST` kit-api/v1/signatures/\[signature uuid]/cancel Method: POST\ Endpoint: kit-api/v1/signatures/\[signature uuid]/cancel
## Example ``` .../kit-api/v1/signatures/57139f5c-37d0-4c30-bdb6-ef6106040756/cancel ```
## Response ```json { "ok": true, "message": undefined, // 실패하는 경우 메시지 (string) "data": { // 전자서명 정보 "uuid": "57139f5c-37d0-4c30-bdb6-ef6106040756", // 전자서명 식별값 "title": "A컴퍼니 MOU 전자서명", // 전자서명 제목 "expiredDate": "2024-10-15T00:00:00.000Z", // 전자서명 만료일 "status": "CANCELED", // 전자서명 상태 (CREATED, WAITING, DONE, CANCELED) "createdAt": "2024-10-01T00:00:00.000Z" // 생성일 } } ```
| Status Code | Error Code | Description | | ----------- | ------------------------- | ------------------- | | 404 | NOT\_FOUND\_SIGNATURE | 전자서명 정보가 존재하지 않는 경우 | | 500 | SIGNATURE\_CANCEL\_FAILED | 전자서명 취소를 실패한 경우 |
# 등록된 계약서로 전자서명 요청 페이지 API 등록된 계약서로 전자서명을 요청할 수 있는 페이지를 호출하는 API를 제공합니다. 응답으로 특정 계약서에 대한 전자서명 요청 페이지의 url을 내려줍니다. 해당 경로를 새 창이나 새 탭으로 띄워서 전자서명을 요청할 수 있습니다. * 이미 전자서명이 요청된 계약서에 대해서는 이용할 수 없습니다.
## `GET` kit-api/v1/contracts/\[contract uuid]/signature-url Method: GET\ Endpoint: kit-api/v1/contracts/\[contract uuid]/signature-url
## Example ``` ...kit-api/v1/contracts/ed976505-bcbd-47bd-913d-f4cde05dea7a/signature-url ```
## Response ```json { "ok": true, // api 성공 시 "data": { "url": "https://www.prix.im/..." // 전자서명 요청 페이지 주소 } } ```
```json { "ok": false, // api 실패 시 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
# (Deprecated) 계약서/전자서명 조회 API 계약서 및 전자계약에 대한 정보/현황을 조회할 수 있는 API를 제공합니다. **해당 API는 더 이상 업데이트를 제공하지 않습니다.** [**find API**](/signature/find)**를 사용해 주세요.** 계약서 및 전자계약에 대한 정보/현황을 조회할 수 있는 API입니다.
## `GET` kit-api/v1/contracts/\[contract uuid] Method: GET\ Endpoint: kit-api/v1/contracts/\[contract uuid]
## Example ``` ...kit-api/v1/contracts/ed976505-bcbd-47bd-913d-f4cde05dea7a ```
## Response ```json { "ok": true, // api 성공 여부 "message": undefined, // Error가 존재하면 message(string)로 전달 "data": { // 계약 정보 (contract) "contract": { "uuid": "ed976505-bcbd-47bd-913d-f4cde05dea7a", // 문서 식별값 (uuid 값을 api에서 사용합니다) "concludedFile": "...concluded.pdf", // 체결된 계약 문서 url (nullable, 요청 후 10분만 유효합니다.) "title": "A컴퍼니 MOU", // 계약서 이름 "file": "...contract.pdf", // 원본 계약 문서 url (요청 후 10분만 유효합니다.) "createdAt": "2024-07-05T00:00:00.000Z", // 생성일 "status": "CREATED", // 계약 상태 (CREATED, CONCLUDED) "signature": { // 전자서명 정보 "uuid": "57139f5c-37d0-4c30-bdb6-ef6106040756", // 전자서명 식별값 "title": "A컴퍼니 MOU 전자서명", // 전자서명 제목 "expiredDate": "2024-10-15T00:00:00.000Z", // 전자서명 만료일 "status": "WAITING", // 전자서명 상태 (CREATED, WAITING, DONE, CANCELED) "createdAt": "2024-07-15T00:00:00.000Z", // 생성일 "participants": [], // 전자서명 참여자 정보 "objects": [ { // 전자서명 입력값 정보 "contents": "서울시 강남구 선릉로 551", // 내용 "type": "TEXT", // 종류 (TEXT, SIGNATURE, CHECKBOX) "category": "DEFAULT", // 유형 (DEFAULT, INPUT) "name": "주소", // 이름 "description": "상세 주소를 입력해 주세요." // 설명 } ] } } } } ```
| Status Code | Error Code | Description | | ----------- | ------------------------------ | --------------------- | | 400 | INVALID\_CUSTOMER\_CUSTOM\_KEY | 규칙을 벗어난 customKey인 경우 | | 404 | NOT\_FOUND\_CUSTOMER | 존재하지 않는 고객인 경우 |
# (Deprecated) 계약서 등록/전자서명 요청 페이지 API 계약서를 등록하거나 전자서명을 요청할 수 있는 페이지를 반환하는 API를 제공합니다. **해당 API는 더 이상 업데이트를 제공하지 않습니다. POST API를 사용해 주세요.** 계약서를 등록하거나 전자서명을 요청할 수 있는 페이지의 url을 내려줍니다. 해당 경로를 새 창이나 새 탭으로 띄워서 전자계약을 생성할 수 있습니다. * 계약 문서를 등록하고 전자서명 정보(서명 참여자 및 서명 위치)를 입력하여 제출하면 전자서명이 시작됩니다. * 참여자 정보에 등록한 이메일이나 전화번호로 참여 링크가 포함된 이메일/카카오톡이 발송됩니다.
## `GET` kit-api/v1/contracts/form-url Method: GET\ Endpoint: kit-api/v1/contracts/form-url
## Example ``` ...kit-api/v1/contracts/form-url ```
## Request Query | Key | Description | Required | | ----------------- | --------------------------------------------------------------------- | -------- | | successUrl | 서명 생성을 완료한 이후 이동되는 url. encode된 url값 사용 (default로 생성된 계약서 상세 화면으로 이동) | no | | customerId | 계약서 등록/전자서명 요청 시 해당 고객 정보를 연결 | no | | customerCustomKey | 계약서 등록/전자서명 요청 시 해당 고객 정보를 연결 | no | | disable | 사용하지 않을 인풋 (현재 가능한 값: customer) | no |
## Response ```json { "ok": true, // api 성공 여부 "message": undefined, // Error가 존재하면 message(string)로 전달 "data": { "url": "https://www.prix.im/..." // 계약서 및 전자서명을 등록할 수 있는 페이지 주소 } } ```
| Status Code | Error Code | Description | | ----------- | -------------------------------------------- | -------------------------- | | 400 | CONTRACT\_FORM\_URL\_INVALID\_DISABLE\_QUERY | 사용할 수 없는 disable 값을 사용한 경우 |
# 전자서명 템플릿 사용하기 전자서명 템플릿 기능을 통해 계약을 간편하게 요청할 수 있도록 제공합니다. 전자서명 템플릿이란 계약서 파일과 서명 위치 등을 지정해 둔 일종의 전자서명 서식을 의미하며, 프릭스는 동일한 형태의 계약을 빠르고 편리하게 체결할 수 있도록 다양한 템플릿 관련 기능을 제공합니다. # 전자서명 템플릿 등록/편집 페이지 API 전자서명 템플릿을 등록하거나 편집할 수 있는 API를 제공합니다. 전자서명 템플릿은 기본적으로 프릭스 서비스를 통해 등록할 수 있지만, API를 통해서 페이지를 조회하여 사용할 수도 있습니다. API 응답으로 전자서명 템플릿을 등록 및 편집할 수 있는 페이지의 url을 내려주며, 해당 경로를 새 창이나 새 탭으로 띄워서 템플릿을 등록/편집할 수 있습니다. * 계약 문서를 등록하고 전자서명 정보(서명 참여자 역할 및 서명 위치)와 변경될 입력값에 대한 내용을 입력하면 전자서명 템플릿이 등록됩니다. * 추후 등록한 전자서명 템플릿을 이용하여 간편하게 서명을 요청할 수 있습니다.
## `GET` kit-api/v1/signature-templates/form-url Method: GET\ Endpoint: kit-api/v1/signature-templates/form-url
## Example ``` ...kit-api/v1/signature-templates/form-url?disabledInputs=SLUG,MANAGER&contractSampleDisabledInputs=PERMISSION&disabledFeatures=CONTRACT_SAMPLE_CREATION&participantRoles=서명자,검토자 ``` 템플릿 편집 페이지를 호출하는 경우 templateId를 query로 전달합니다. ``` ...kit-api/v1/signature-templates/form-url?templateId=123&disabledInputs=SLUG,MANAGER ```
## Request Query | Key | Description | Required | | ---------------------------- | ------------------------------------------------------------- | -------- | | successUrl | 템플릿 등록을 완료한 이후 이동되는 url (encode된 url값 사용) | no | | templateId | 편집할 템플릿의 id를 등록하여 편집 페이지 호출 | no | | tagIds | 템플릿 생성 시 태그 input의 기본값 (쉼표로 구분: ex. tagIds=2,3) | no | | slug | 템플릿 생성 시 slug input의 기본값 (string) | no | | participantRoles | 템플릿 생성 시 서명 참여자 역할 기본값 (쉼표로 구분: ex. participantRoles=서명자,검토자) | no | | disabledInputs | 템플릿 등록/편집 페이지에서 사용하지 않을 input 목록 | no | | contractSampleDisabledInputs | 양식 생성/편집 페이지에서 사용하지 않을 input 목록 | no | | disabledFeatures | 템플릿 등록/편집 페이지에서 사용하지 않을 기능 목록 | no | tagIds, slug, participantRoles는 템플릿 생성 페이지에서만 기본값으로 적용됩니다. templateId를 전달한 편집 페이지에서는 적용되지 않습니다. disabledInputs, contractSampleDisabledInputs, disabledFeatures는 템플릿 등록/편집 페이지 모두에 적용됩니다. ## Request Query : disabledInputs disabledInputs으로 전달할 수 있는 value 목록 (쉼표로 구분) | Key | Description | Required | | ----------- | ----------- | -------- | | PERMISSION | 권한 인풋 | no | | TAG | 태그 인풋 | no | | SLUG | Slug 인풋 | no | | MANAGER | 담당자 인풋 | no | | ATTACHMENT | 서명 참고자료 인풋 | no | | CC\_EMAIL | 참조자 인풋 | no | | OPTION | 상세설정 토글 | no | | PARTICIPANT | 서명 참여자 섹션 | no |
## Request Query : contractSampleDisabledInputs contractSampleDisabledInputs으로 전달할 수 있는 value 목록 (쉼표로 구분) | Key | Description | Required | | ---------- | ------------------ | -------- | | PERMISSION | 양식 생성/편집 페이지 권한 인풋 | no |
## Request Query : disabledFeatures disabledFeatures로 전달할 수 있는 value 목록 (쉼표로 구분) | Key | Description | Required | | -------------------------- | ----------- | -------- | | CONTRACT\_EDITOR\_OPTION | 에디터 옵션 버튼 | no | | CONTRACT\_SAMPLE\_CREATION | 양식 생성하기 버튼 | no |
## Response ```json { "ok": true, // api 성공 여부 "message": undefined, // Error가 존재하면 message(string)로 전달 "data": { "url": "https://www.prix.im/..." // 전자서명 템플릿을 등록/편집할 수 있는 페이지 주소 } } ```
| Status Code | Error Code | Description | | ----------- | ------------------------------------------ | --------------------------------------- | | 401 | INVALID\_BUSINESS | 전자서명 템플릿에 권한이 없는 경우 | | 404 | NOT\_FOUND\_SIGNATURE\_TEMPLATE | 전자서명 템플릿이 존재하지 않는 경우 | | 404 | NOT\_FOUND\_BUSINESS\_TAG | 비즈니스에 등록하지 않은 태그가 포함되어 있는 경우 | | 400 | SIGNATURE\_TEMPLATE\_SLUG\_ALREADY\_EXISTS | 이미 존재하는 템플릿 slug인 경우 (템플릿 간 slug 중복 불가) |
# 전자서명 템플릿 목록 조회 API 비즈니스에 등록된 전자서명 템플릿 목록을 조회할 수 있는 API를 제공합니다. 현재 비즈니스에 등록된 전자서명 템플릿 목록을 확인할 수 있습니다.
## `GET` kit-api/v1/signature-templates Method: GET\ Endpoint: kit-api/v1/signature-templates
## Example ``` ...kit-api/v1/signature-templates?limit=10&offset=0 ```
## Request Query | Key | Description | Required | | -------------- | --------------------------------------- | -------- | | limit | 목록 개수 (default 10, max 100) | no | | offset | 스킵할 목록 개수 | no | | title | 전자서명 템플릿 이름으로 필터 (string) | no | | tagIds | 연결된 계약서 태그로 필터 (쉼표로 구분: ex. tagIds=2,3) | no | | signatureCount | 연결된 서명 개수도 함께 조회할지 여부 (true, false) | no | | slug | 템플릿의 slug 값으로 필터 (string) | no |
## Response ```json { "ok": true, // api 성공 여부 "message": undefined, // Error가 존재하면 message(string)로 전달 "data": { "templates": [ // 전자서명 템플릿 목록 (계약서의 파일은 계약서 상세 조회 API에서 조회할 수 있습니다.) { "id": 12345, // 고유 식별 id "name": "MOU 템플릿", // 전자서명 템플릿 이름 "participantType": "TOGETHER", // 서명 타입 (순서대로 서명 여부 - TOGETHER, ORDER) "slug": "test_slug_03232", // slug(문자) "ccEmails": ["cc@prix.im"], // 워크플로우 이메일 참조자 "createdAt": "2024-07-15T00:00:00.000Z", // 생성일 "updatedAt": "2024-07-15T00:00:00.000Z", // 수정일 "managerNames": ["이용우"], // 계약서 담당자 이름 목록 "signatureCount": 3, // signatureCount=true로 넘긴 경우에만 확인 가능 "participants": [ { // 전자서명 참여자 "id": 987, // 고유 식별 id "order": 1, // 전자서명 참여 순서 "role": "고객" // 역할 이름 (ex. 갑, 고객, 등) } ] } ], "total": 1 } } ```
# 전자서명 템플릿 상세 조회 API 전자서명 템플릿 정보를 조회할 수 있는 API를 제공합니다. 전자서명 템플릿에 대한 정보를 확인할 수 있습니다.
## `GET` kit-api/v1/signature-templates/\[key] Method: GET Endpoint: kit-api/v1/signature-templates/\[key] Param: key는 전자서명 템플릿의 id(숫자) 혹은 slug(문자)를 의미
## Example ``` ...kit-api/v1/signature-templates/4231 ```
## Response ```json { "ok": true, // api 성공 여부 "message": undefined, // Error가 존재하면 message(string)로 전달 "data": { // 전자서명 템플릿 정보 "id": 12345, // 고유 식별 id "name": "MOU 템플릿", // 전자서명 템플릿 이름 "contractFile": "....pdf", // 전자서명 템플릿으로 등록한 계약 문서 url (요청 후 10분만 유효합니다.) "participantType": "TOGETHER", // 서명 타입 (순서대로 서명 여부 - TOGETHER, ORDER) "createdAt": "2024-07-15T00:00:00.000Z", // 생성일 "updatedAt": "2024-07-15T00:00:00.000Z", // 수정일 "slug": "test_slug_03232", // slug(문자) "ccEmails": ["cc@prix.im"], // 워크플로우 이메일 참조자 "managerNames": ["이용우"], // 계약서 담당자 이름 목록 "signatureCount": 3, // 템플릿으로 생성한 전자서명 개수 "objects": [ { // 전자서명 입력값 "id": 123, // 고유 식별 id "type": "TEXT", // 종류 (TEXT, SIGNATURE, CHECKBOX) "category": "DEFAULT", // 유형 (DEFAULT, INPUT) "name": "주소", // 이름 "description": "상세 주소를 입력해 주세요." // 설명 } ], "tags": [ // 태그 목록 { "id": 1, "name": "태그이름" } ], "participants": [ { // 전자서명 참여자 "id": 987, // 고유 식별 id "order": 1, // 전자서명 참여 순서 "role": "고객" // 역할 이름 (ex. 갑, 고객, 등) } ] } } ```
| Status Code | Error Code | Description | | ----------- | ------------------------------- | -------------------- | | 401 | FORBIDDEN\_BUSINESS | 전자서명 템플릿에 권한이 없는 경우 | | 404 | NOT\_FOUND\_SIGNATURE\_TEMPLATE | 전자서명 템플릿이 존재하지 않는 경우 |
# 전자서명 템플릿으로 서명 요청 API 전자서명 템플릿을 이용하여 계약서를 생성하고 서명을 요청할 수 있는 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 합본에 실패한 경우 |
# 전자서명 템플릿 대량계약 페이지 API 전자서명 템플릿을 사용하여 대량계약을 생성할 수 있는 페이지 URL을 제공합니다. 전자서명 템플릿 대량계약 기능은 기본적으로 프릭스 서비스를 통해 사용할 수 있지만, API를 통해서 페이지 URL을 얻어 사용할 수도 있습니다. API 응답으로 대량계약 페이지의 url을 내려주며, 해당 경로를 새 창이나 새 탭으로 띄워서 대량계약을 진행할 수 있습니다. * 참여자가 한 명인 템플릿으로만 대량계약을 이용할 수 있습니다.
## `POST` kit-api/v1/signature-templates/\[key]/bulk-url Method: POST\ Endpoint: kit-api/v1/signature-templates/\[key]/bulk-url\ Param: key는 전자서명 템플릿의 id(숫자) 혹은 slug(문자)를 의미
## 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_NAME", "REQUESTER_EMAIL"], "disabledFeatures": ["LOGO", "DETAIL_SECTION"], "readonlyInputs": ["PARTICIPANTS_TABLE"], "skipSend": false // 알림 발송 스킵 여부 (선택, true 인 경우 서명 참여 알림을 발송하지 않음) }, "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": "이래티스" } ] } ] } } ```
## 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 | | disabledFeatures | 대량계약 페이지에서 사용하지 않을 UI 또는 기능 (array / ex. \["LOGO"]) | no | | readonlyInputs | 대량계약 페이지에서 읽기 전용으로 표시할 인풋 영역 (array / ex. \["PARTICIPANTS\_TABLE"]) | no | | skipSend | 알림 발송 스킵 여부 (true 시 알림 발송 안함) | no | ### disabledInputs disabledInputs으로 전달할 수 있는 value 목록 | Value | Description | | ---------------- | -------------- | | REQUESTER\_NAME | 요청자 이름 인풋을 제거 | | REQUESTER\_EMAIL | 요청자 이메일 인풋을 제거 | ### disabledFeatures disabledFeatures로 전달할 수 있는 value 목록 | Value | Description | | --------------- | ---------------------- | | LOGO | 헤더 및 완료 화면의 프릭스 로고를 제거 | | DETAIL\_SECTION | 상세 설정 영역을 제거 | ### readonlyInputs readonlyInputs으로 전달할 수 있는 value 목록 | Value | Description | | ------------------- | -------------------------------------------------------------- | | PARTICIPANTS\_TABLE | input.items로 전달한 서명 참여자 값을 화면에서 수정/추가/삭제할 수 없도록 읽기 전용으로 표시합니다. | ## 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. 암호 인증
## Response ```json { "ok": true, // api 성공 여부 "message": undefined, // Error가 존재하면 message(string)로 전달 "data": { "url": "https://www.prix.im/..." // 대량계약을 생성할 수 있는 페이지 주소 } } ```
| Status Code | Error Code | Description | | ----------- | --------------------------------------------- | --------------------------------------- | | 400 | SIGNATURE\_TEMPLATE\_BULK\_PARTICIPANT\_COUNT | 대량서명을 이용할 수 없는 템플릿인 경우 (참여자가 1명이 아닌 경우) | | 401 | INVALID\_BUSINESS | 전자서명 템플릿에 권한이 없는 경우 | | 404 | SIGNATURE\_TEMPLATE\_NOT\_FOUND | 전자서명 템플릿이 존재하지 않는 경우 | | 404 | NOT\_FOUND\_CUSTOMER | 존재하지 않는 고객인 경우 |
# 전자서명 템플릿 미리보기 페이지 API 전자서명 템플릿 미리보기 페이지를 제공합니다. 전자서명 템플릿 미리보기 페이지를 제공합니다. API 응답으로 미리보기 페이지의 URL 을 내려주며, 해당 URL에 쿼리파라미터를 추가하여 사전입력값이 포함된 미리보기를 확인할 수도 있습니다. * 미리보기 페이지에서는 계약 문서와 사전입력값이 적용된 상태를 확인할 수 있습니다. * URL에 쿼리 파라미터를 추가하여 사전입력값을 포함시킬 수 있습니다.
## `GET` kit-api/v1/signature-templates/\[key]/preview-url Method: GET\ Endpoint: kit-api/v1/signature-templates/\[key]/preview-url\ Param: key는 전자서명 템플릿의 id(숫자) 혹은 slug(문자)를 의미
## Example ``` ...kit-api/v1/signature-templates/ABC1234/preview-url?input=%7B%22324%22%3A%22value1%22%2C%22325%22%3A%22value2%22%7D ```
## Request Query | Key | Description | Required | | ---------- | ----------------------------------------------------------------------------------------------------------------- | -------------------- | | mode | 미리보기 화면의 사전입력값 부분에 라벨을 기준으로 표시할지 실제 등록한 값을 기준으로 표시할지 설정하는 옵션 (LABEL, CONTENTS) | no (default LABEL) | | permission | iframe 등 미리보기 화면을 서비스 내부에 포함하고 싶은 경우에 대한 권한 설정 (PUBLIC, PRIVATE) | no (default PRIVATE) | | input | 미리보기 페이지에 사전입력값을 포함하고 보여주고 싶은 경우, JSON 형태의 사전입력값을 문자열로 변경한 후 encode하여 사용 가능. key는 템플릿에 등록된 object의 id 또는 slug만 허용 | no | | inputType | input 필드 사용 시 key의 타입을 설정 ('id', 'slug') | no (default 'id') | ```json // inputType이 'id'인 경우 { // id: 324, id: 325의 입력값의 내용이 채워진 상태로 미리보기 페이지를 조회하는 경우 // json을 string으로 변환 후, encode하여 사용 "324": "value1", "325": "value2", "326": "true" // 체크박스 타입의 사전입력값은 'true' 값을 이용 } // inputType이 'slug'인 경우 { // slug: slug-324, slug: slug-325의 입력값의 내용이 채워진 상태로 미리보기 페이지를 조회하는 경우 // json을 string으로 변환 후, encode하여 사용 "slug-324": "value1", "slug-325": "value2", "slug-326": "true" // 체크박스 타입의 사전입력값은 'true' 값을 이용 } ```
## Response ```json { "ok": true, // api 성공 여부 "data": { "url": "https://prix.im/..." // 전자서명 템플릿 미리보기 페이지로 이동되는 주소 } } ```
| Status Code | Error Code | Description | | ----------- | ------------------------------------------ | ----------------------------------------------------------------------------- | | 400 | INVALID\_JSON\_PARSING | input 필드의 JSON 파싱 과정에서 에러가 발생한 경우 | | 400 | SIGNATURE\_TEMPLATE\_OBJECT\_NOT\_FOUND | input 필드에 전달한 key 중 해당 템플릿에 등록된 사전입력값 object의 id 또는 slug와 일치하지 않는 key가 포함된 경우 | | 400 | CONFIGURATION\_CONTRACT\_PREVIEW\_DISABLED | permission이 PUBLIC인 경우, 해당 계정의 미리보기가 허용되지 않은 경우 | | 404 | NOT\_FOUND\_SIGNATURE\_TEMPLATE | 전자서명 템플릿이 존재하지 않는 경우 |
# 전자서명 템플릿 사용 페이지 API 전자서명 템플릿을 사용하여 계약서를 생성하고 전자서명을 요청할 수 있는 페이지 URL을 제공합니다. 전자서명 템플릿을 사용 기능은 기본적으로 프릭스 서비스를 통해 사용할 수 있지만, API를 통해서 페이지 URL을 얻어 사용할 수도 있습니다. API 응답으로 전자서명 템플릿을 사용해 계약서를 생성하고 전자서명을 요청할 수 있는 페이지의 url을 내려주며, 해당 경로를 새 창이나 새 탭으로 띄워서 전자서명 템플릿을 사용할 수 있습니다.
## `POST` kit-api/v1/signature-templates/\[key]/use-template-url Method: POST\ Endpoint: kit-api/v1/signature-templates/\[key]/use-template-url Param: key는 전자서명 템플릿의 id(숫자) 혹은 slug(문자)를 의미
## Example ``` ...kit-api/v1/signature-templates/4328/use-template-url ``` ```json { // body input은 선택 값으로 body 없이 요청 가능 "input": { "option": { "successUrl": "https://..." }, "defaultValue": { "customer": { "id": 3 }, "contract": { "title": "계약서 이름", "startDate": "2025-03-10T11:02:05.759Z", // Date.toISOString "endDate": "2025-03-10T11:02:05.759Z" // Date.toISOString }, "signature": { "participants": [ { "role": "갑", // 템플릿 생성 시 등록한 참여자 역할 "name": "홍길동", "send": "EMAIL", // EMAIL 또는 PHONE "email": "test@prix.im", "phone": undefined, "message": "서명 입력 요청드립니다.", "extraAuthList": [ { // 휴대폰 본인인증이 필요한 경우 해당 값 사용 "type": "MOBILE_IDENTIFICATION", "phoneName": "김실명", "phoneNumber": "010-1234-1234" }, { // 암호 인증이 필요한 경우 해당 값 사용 "type": "CODE", "code": "1234", "codeHint": "암호는 1234" } ] } ] } } } } ```
## Request Body | Key | Description | Required | | ------------------ | ------------------------- | -------- | | input.option | 전자서명 템플릿 사용 페이지에 대한 옵션 | no | | input.defaultValue | 전자서명 템플릿 사용 페이지에 채워둘 기본 값 | no | ### Request Body : input.option | Key | Description | Required | | ---------- | ---------------------------------------------- | -------- | | successUrl | 템플릿 사용(계약서 생성 및 전자서명 요청) 완료 시 이동될 페이지 (string) | 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 | | signature.participants | 템플릿 사용 시 생성할 계약서에 기본적으로 입력될 전자서명 참여자 정보 (array) | no | ### Request Body : input.defaultValue.signature.participants | Key | Description | Required | | ------------- | --------------------------------------------------------------- | -------- | | role | 템플릿 사용 시 요청할 전자서명 참여자의 역할 (string) | yes | | name | 템플릿 사용 시 요청할 전자서명 참여자의 이름 (string) | no | | send | 템플릿 사용 시 요청할 전자서명 참여 알림 발송 수단 (string / PHONE or EMAIL) | no | | email | 템플릿 사용 시 요청할 전자서명 참여자의 이메일 (string) | no | | phone | 템플릿 사용 시 요청할 전자서명 참여자의 전화번호 (string / - 포함 / ex. 010-0000-0000) | no | | message | 템플릿 사용 시 요청할 전자서명 참여자 안내 메시지 (string) | no | | extraAuthList | 추가 인증 정보 목록 | no |
\*참여자 추가 인증은 2가지 방식을 사용할 수 있습니다. 1. 휴대폰 본인 인증 휴대폰 본인 인증 시, 서명 참여자 이름(participant.name)이 실명이어야 하며, 본인 명의의 휴대폰 번호를 입력해야 합니다. 2. 암호 인증 ## Response ```json { "ok": true, // api 성공 여부 "message": undefined, // Error가 존재하면 message(string)로 전달 "data": { "url": "https://www.prix.im/..." // 대량계약을 생성할 수 있는 페이지 주소 } } ```
| Status Code | Error Code | Description | | ----------- | ------------------------------------------------- | ---------------------------------------------- | | 404 | NOT\_FOUND\_CUSTOMER | 전자서명 템플릿 사용 시, 계약서에 연결할 고객이 존재하지 않는 경우 | | 400 | SIGNATURE\_TEMPLATE\_FILE\_INVALID | 형식에 맞지 않은 파일인 경우(pdf 형식이 아닌 경우) | | 500 | SIGNATURE\_TEMPLATE\_FILE\_SAVED\_FAILED | 파일 저장에 실패한 경우 | | 404 | NOT\_FOUND\_SIGNATURE\_TEMPLATE | 존재하지 않는 전자서명 템플릿인 경우 | | 403 | FORBIDDEN\_BUSINESS | 비즈니스 접근 권한이 없는 경우 | | 400 | SIGNATURE\_TEMPLATE\_PARTICIPANT\_COUNT\_MISMATCH | 기본값으로 전달 받은 참여자의 수와 템플릿에 등록된 참여자 수가 일치하지 않는 경우 |
# 전자서명 템플릿 삭제 API 전자서명 템플릿을 삭제할 수 있는 API를 제공합니다. 전자서명 템플릿을 삭제할 수 있는 API를 제공합니다.
## `DELETE` kit-api/v1/signature-templates/\[key] * Method: DELETE * Endpoint: kit-api/v1/signature-templates/\[key] * Param: key는 전자서명 템플릿의 id(숫자) 혹은 slug(문자)를 의미
## Example ``` ...kit-api/v1/signature-templates/4328 ```
## Request Path 파라미터 | Key | Description | Required | | --- | ------------------------------------ | -------- | | key | 삭제할 전자서명 템플릿의 id(숫자) 혹은 slug(문자) 식별값 | yes |
## Response ```json { "ok": true, // api 성공 여부 "data": { "id": 4328, // 고유 식별 id "name": "MOU 템플릿", // 전자서명 템플릿 이름 "slug": "template-slug" // slug(문자) } } ``` ```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
## Webhook 전자서명 템플릿이 삭제되면 `SIGNATURE_TEMPLATE_DELETED` 웹훅 이벤트가 발송됩니다. 이 이벤트는 계약서 태그 필터와 상관없이, 해당 이벤트를 구독한 웹훅에 발송됩니다.
| Status Code | Error Code | Description | | ----------- | ------------------------------- | ------------------------------ | | 403 | FORBIDDEN\_USER | 전자서명 템플릿 편집 권한이 없어 삭제할 수 없는 경우 | | 404 | NOT\_FOUND\_SIGNATURE\_TEMPLATE | 전자서명 템플릿이 존재하지 않는 경우 |
# 계약서 태그 활용하기 태그를 활용하여 계약서 기능을 체계적으로 관리할 수 있도록 다양한 API를 제공합니다. 태그를 활용하여 계약서 기능을 체계적으로 관리할 수 있도록 다양한 API를 제공합니다. # 계약서 태그 목록 조회 API 계약서 목록을 조회할 수 있는 API를 제공합니다. 계약서 태그 목록을 조회할 수 있는 API입니다.
## `GET` kit-api/v1/contracts/tags Method: GET\ Endpoint: kit-api/v1/contracts/tags
## Example ``` ...kit-api/v1/contracts/tags ```
## Response ```json { "ok": true, // api 성공 "data": [ { "id": 3135, "name": "MOU", "colorCode": "RED", // RED, ORANGE, YELLOW, GREEN, BLUE, GRAY 존재 "order": 1 }, { "id": 1462, "name": "근로계약서", "colorCode": "ORANGE", "order": 2 }, { "id": 4393, "name": "영업계약서", "colorCode": "GREEN", "order": 3 } ] } ```
```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
# 계약서 태그 생성 API 계약서 태그를 생성할 수 있는 API를 제공합니다. 계약서 태그를 생성할 수 있는 API를 제공합니다.
## `POST` kit-api/v1/contracts/tags Method: POST\ Endpoint: kit-api/v1/contracts/tags
## Example ``` ...kit-api/v1/contracts/tags ``` ```json { "input": { "name": "근로계약서", "order": 12, "colorCode": "RED" // RED, ORANGE, YELLOW, GREEN, BLUE, GRAY 존재 } } ```
## Request Body | Key | Type | Description | Required | | --------------- | ------ | ---------------------------------------------- | -------- | | input.name | string | 태그 이름 | yes | | input.order | number | 태그 순서 | no | | input.colorCode | string | 태그 색상 (RED, ORANGE, YELLOW, GREEN, BLUE, GRAY) | no |
## Response ```json { "ok": true, // api 성공 시 "data": { "id": 1462, "name": "근로계약서", "colorCode": "RED", "order": 12 } } ```
```json { "ok": false, // api 실패 시 "message": "error message", "errorCode": "ERROR_CODE" } ```
# 계약서 태그 변경 API 계약서 태그를 업데이트할 수 있는 API를 제공합니다. 계약서 태그를 업데이트할 수 있는 API를 제공합니다.
## `PATCH` kit-api/v1/contracts/tags/\[tag id] Method: PATCH\ Endpoint: kit-api/v1/contracts/tags/\[tag id]
## Example ``` ...kit-api/v1/contracts/tags/1462 ``` ```json { "input": { "name": "근로계약서(정규직)", "order": 12, "colorCode": "RED" // RED, ORANGE, YELLOW, GREEN, BLUE, GRAY 존재 } } ```
## Request Body | Key | Type | Description | Required | | --------------- | ------ | ---------------------------------------------- | -------- | | input.name | string | 태그 이름 | no | | input.order | number | 태그 순서 | no | | input.colorCode | string | 태그 색상 (RED, ORANGE, YELLOW, GREEN, BLUE, GRAY) | no |
## Response ```json { "ok": true, // api 성공 시 "data": { "id": 1462, "name": "근로계약서(정규직)", "colorCode": "RED", "order": 12 } } ```
```json { "ok": false, // api 실패 시 "message": "error message", "errorCode": "ERROR_CODE" } ```
# 계약서 태그 삭제 API 계약서 태그를 삭제할 수 있는 API를 제공합니다. 계약서 태그를 삭제할 수 있는 API를 제공합니다.
## `DELETE` kit-api/v1/contracts/tags Method: DELETE\ Endpoint: kit-api/v1/contracts/tags
## Example ``` ...kit-api/v1/contracts/tags/1462 ```
## Response ```json { "ok": true // api 성공 시 } ```
```json { "ok": false, // api 실패 시 "message": "error message", "errorCode": "ERROR_CODE" } ```
# 계약서에 태그 연결 API 계약서 정보를 업데이트할 수 있는 API를 제공합니다. 계약서에 연결된 태그를 업데이트할 수 있는 API를 제공합니다.
## `PATCH` kit-api/v1/contracts/\[contract uuid] Method: PATCH\ Endpoint: kit-api/v1/contracts/\[contract uuid]\ Param: contract uuid는 계약서의 식별값을 의미
## Example ``` ...kit-api/v1/contracts/ed976505-bcbd-47bd-913d-f4cde05dea7a ``` ```json { "input": { "tagIds": [12345, 12346] } } ```
## Request Body | Key | Type | Description | Required | | ------------ | ------------ | ---------------- | -------- | | input.tagIds | number array | 연결할 계약서 태그 ID 목록 | yes |
## Response ```json { "ok": true // api 성공 시 } ```
```json { "ok": false, // api 실패 시 "message": "error message", "errorCode": "ERROR_CODE" } ```
# 비즈니스 관리하기 자신의 비즈니스 정보를 관리할 수 있는 API를 제공합니다. 자신의 비즈니스 정보를 관리할 수 있는 API를 제공합니다. # 비즈니스 정보 변경 API 플랫폼 서비스에서 생성한 비즈니스 정보를 수정할 수 있도록 API를 제공합니다. 플랫폼 서비스에서 생성한 비즈니스 정보를 수정할 수 있도록 API를 제공합니다.
## `PATCH` kit-api/v1/business Method: PATCH\ Endpoint: kit-api/v1/business
## Example ``` ...kit-api/v1/business ``` ```json { "input": { "profile": { "name": "홍길동 컴퍼니", "registrationNumber": "123-12-12345", "ceo": "홍길동", "address": "서울특별시 강남구" }, "configuration": { "customerCustomName": "매장" } } } ```
## Request Body ### 1. input.profile | Key | Type | Description | Required | | ------------------ | ------ | ----------- | -------- | | name | string | 비즈니스 이름 | yes | | registrationNumber | string | 사업자등록번호 | no | | ceo | string | 대표자 이름 | no | | address | string | 회사 주소 | no |
### 2. input.configuration | Key | Type | Description | Required | | ------------------ | ------ | ----------- | -------- | | customerCustomName | string | 커스텀할 고객명 | no |
## Response ### Success Response ```json { "ok": true, "data": { "profile": { // profile 또는 configuration 개별 업데이트 가능 "name": "홍길동 컴퍼니", "registrationNumber": "123-12-12345", "ceo": "홍길동", "address": "서울특별시 강남구" }, "configuration": { "customerCustomName": "매장" } } } ``` ### Error Response ```json { "ok": false, "message": "error message", "errorCode": "ERROR_CODE" } ```
## Error Codes | Status Code | Error Code | Description | | ----------- | ------------------------- | --------------------------- | | 400 | MISSING\_PROFILE\_NAME | 프로필의 필수값인 비즈니스 이름이 누락 됐을 경우 | | 500 | FAILED\_UPDATE\_PROFILE | 프로필 업데이트 과정에서 에러가 발생했을 경우 | | 404 | NOT\_FOUND\_CONFIGURATION | 설정 정보가 존재하지 않는 경우 | # 인감/명판 조회 API 비즈니스의 인감/명판 데이터를 조회할 수 있는 API를 제공합니다. 비즈니스의 인감/명판 데이터를 조회할 수 있는 API를 제공합니다.
## `GET` kit-api/v1/business/seals Method: GET\ Endpoint: kit-api/v1/business/seals
## Example ``` ...kit-api/v1/business/seals ```
## Response ```json { "ok": true, "data": { "corporateItems": [ // 법인 서명/인감 "https://lattice-prix-public.s3.ap-northeast-2.amazonaws.com/..." ], "items": [ // 서명/인감 "https://lattice-prix-public.s3.ap-northeast-2.amazonaws.com/...", "https://lattice-prix-public.s3.ap-northeast-2.amazonaws.com/...", "https://lattice-prix-public.s3.ap-northeast-2.amazonaws.com/..." ], "stamps": [ // 명판 "https://lattice-prix-public.s3.ap-northeast-2.amazonaws.com/...", "https://lattice-prix-public.s3.ap-northeast-2.amazonaws.com/..." ] } } ``` ```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
# 인감/명판 관리 페이지 API 비즈니스의 인감/명판 데이터를 관리할 수 있는 프릭스 웹 URL API를 제공합니다. 비즈니스의 인감/명판 관리는 기본적으로 프릭스 서비스를 통해 할 수 있지만, API를 통해서 웹 URL을 조회하여 사용할 수도 있습니다.
## `GET` kit-api/v1/business/seals/url Method: GET\ Endpoint: kit-api/v1/business/seals/url
## Example ``` ...kit-api/v1/business/seals/url ```
## Response ```json { "ok": true, "data": { "url": "https://prix.im/..." } } ``` ```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
# 크레딧 사용량/내역 조회 API 비즈니스의 크레딧 사용 목록을 조회할 수 있는 API를 제공합니다. 비즈니스의 크레딧 사용 내역을 조회할 수 있는 API를 제공합니다.
## `GET` kit-api/v1/credit-usages Method: GET\ Endpoint: kit-api/v1/credit-usages
## Example ``` ...kit-api/v1/credit-usages?createdAtAfter=2024-11-19T06:00:00.000Z ```
## Request Query | Key | Description | Required | | --------------- | ------------------------------------- | -------- | | createdAtAfter | 특정시간 이후의 사용량 목록 조회용 파라미터 (ISO UTC 포맷) | no | | createdAtBefore | 특정시간 이전의 사용량 목록 조회용 파라미터 (ISO UTC 포맷) | no | | limit | 목록 개수 (default 10, max 100) | no | | offset | 스킵할 목록 개수 | no |
## Response ```json { "ok": true, "data": { "total": 2, "creditUsages": [ { "id": 10, "case": "SIGNATURE_IDENTIFICATION", "user": { "id": 1, "uuid": "08f450cb-87ef-4cda-9ebe-48665d35a677", "name": "test1234", "role": "USER", "email": "test1234@lattice.im", "language": "KOREAN", "phone": null, "createdAt": "2024-11-08T05:54:24.016Z", "updatedAt": "2024-11-15T00:36:52.046Z" }, "createdAt": "2024-11-19T06:57:24.477Z", "updatedAt": "2024-11-19T06:57:24.477Z" }, { "id": 9, "case": "TAX_BILL", "user": { "id": 1, "uuid": "08f450cb-87ef-4cda-9ebe-48665d35a677", "name": "test1234", "role": "USER", "email": "test1234@lattice.im", "language": "KOREAN", "phone": null, "createdAt": "2024-11-08T05:54:24.016Z", "updatedAt": "2024-11-15T00:36:52.046Z" }, "createdAt": "2024-11-19T06:57:24.477Z", "updatedAt": "2024-11-19T06:57:24.477Z" } ] } } ``` ```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
# 크레딧 현황 조회 API 비즈니스의 크레딧 사용량을 조회할 수 있는 API를 제공합니다. 비즈니스의 크레딧 사용량을 조회할 수 있는 API를 제공합니다.
## `GET` kit-api/v1/credit-usages/status Method: GET\ Endpoint: kit-api/v1/credit-usages/status
## Example ``` ...kit-api/v1/credit-usages/status ```
## Response ```json { "ok": true, "data": { "renewalDate": "2024-12-08T15:00:00.000Z", "credit": { "defaultCount": 5, // 기본 무료 크레딧 "remainingDefaultCount": 3, // 잔여 무료 크레딧 "paidCreditCount": 0, // 구매한 크레딧 "remainingCount": 3 // 남은 전체 크레딧 } } } ``` ```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
## Error Codes | Status Code | Error Code | Description | | ----------- | ------------------- | ------------------------- | | 500 | FAILED\_GET\_CREDIT | 조회 과정에서 알 수 없는 에러가 발생한 경우 |
# 플랫폼에서 사용하기 플랫폼 서비스에서 전자계약 기능을 이용할 수 있도록 다양한 API를 제공합니다. 플랫폼 서비스에서 전자계약 기능을 이용할 수 있도록 다양한 API를 제공합니다. # 신규 비즈니스 생성 API 플랫폼 서비스에서 개별 유저가 전자서명을 생성하고 관리할 수 있도록 비즈니스 계정 생성 API를 제공합니다. 플랫폼 서비스에서 개별 유저가 전자서명을 생성하고 관리할 수 있도록 비즈니스 계정 생성 API를 제공합니다.
## `POST` kit-api/v1/business Method: POST\ Endpoint: kit-api/v1/business
## Example ``` .../kit-api/v1/business ``` ```json { "input": { "user": { "email": "test@prix.im", "password": "thisistestpassword" }, "profile": { "name": "ABC 컴퍼니" }, "customConfig": { "customerCustomName": "매장" } } } ```
## Request Body ### 1. input.user | Key | Description | Required | | -------- | ----------------------------------------------------------- | -------- | | email | 새로 생성할 비즈니스의 이메일. 추후 해당 비즈니스로 서명을 요청하는 경우 서명 요청자의 이메일로 적용됨. | yes | | password | 영문과 숫자를 포함한 8자리 이상의 값 | yes | ### 2. input.profile | Key | Description | Required | | ------------------ | ----------- | -------- | | name | 기업명 | yes | | registrationNumber | 사업자등록번호 | no | | ceo | 대표자명 | no | | address | 사업자주소 | no | ### 3. input.customConfig | Key | Description | Required | | ------------------ | ----------- | -------- | | customerCustomName | 커스텀할 고객명 | no |
## Response ```json { "ok": true, "data": { "apiKey": "API_KEY_STRING", // API key 값을 저장해서 사용해 주세요. "uuid": "686961a8-3975-4ad5-bf4e-134706efee15" // 비즈니스 식별값 } } ``` ```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
## Error Codes | Status Code | Error Code | Description | | ----------- | ---------------------------------- | --------------------------------- | | 400 | INVALID\_REQUEST\_INPUT | 파라미터가 잘못된 경우 | | 400 | INVALID\_PASSWORD\_MINIMUM\_LENGTH | password가 최소 길이 미만인 경우 | | 400 | INVALID\_REQUEST\_PARAM | 프로필에 이름이 누락된 경우 | | 400 | INVALID\_CUSTOMER\_CUSTOM\_NAME | customerCustomName이 생성 규칙을 벗어난 경우 | | 400 | EXISTING\_EMAIL | email이 이미 존재하는 경우 | | 500 | FAILED\_CREATE\_SIGNUP | 사용자 생성 과정에서 알 수 없는 에러가 발생한 경우 | | 500 | FAILED\_CREATE\_BUSINESS | 비즈니스 생성 과정에서 알 수 없는 에러가 발생한 경우 |
# 생성한 비즈니스 목록 조회 API 플랫폼 서비스에서 생성한 비즈니스 목록을 조회할 수 있도록 API를 제공합니다. 플랫폼 서비스에서 생성한 비즈니스 목록을 조회할 수 있도록 API를 제공합니다.
## `GET` kit-api/v1/business/managing Method: GET\ Endpoint: kit-api/v1/business/managing
## Example ``` .../kit-api/v1/business/managing?limit=10&offset=0 ```
## Request Query | Key | Description | Required | | ------ | --------------------------- | -------- | | limit | 목록 개수 (default 10, max 100) | no | | offset | 스킵할 목록 개수 | no |
## Response ```json { "ok": true, "data": { "total": 2, "businessList": [ { "uuid": "686961a8-3975-4ad5-bf4e-134706efee15", "name": "홍길동 컴퍼니", "registrationNumber": "123-12-12345", "ceo": "홍길등", "address": null, "createdAt": "2024-11-16T04:40:26.298Z", "apiKey": "...", // api key "customerCustomName": "거래처", // 커스텀 '고객' 명칭 "users": [ { "name": "홍길동", "email": "gildong@prix.im" } ] }, { "uuid": "e790e9a8-a47e-4029-9d6c-e3dfc13fdf74", "name": "A에이전시", "registrationNumber": null, "ceo": null, "address": null, "createdAt": "2024-09-01T02:42:08.760Z", "apiKey": "...", // api key "customerCustomName": null, "users": [ { "name": "김담당", "email": "damdang.kim@prix.im" } ] } ] } } ``` ```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
# 생성한 비즈니스 삭제 API 플랫폼 서비스에서 생성한 비즈니스 계정을 삭제할 수 있도록 API를 제공합니다. 플랫폼 서비스에서 생성한 비즈니스 계정을 삭제할 수 있도록 API를 제공합니다.
## `DELETE` kit-api/v1/business/managing/\[managedBusinessUuid] Method: DELETE\ Endpoint: kit-api/v1/business/managing/\[managedBusinessUuid]
## Example ``` .../kit-api/v1/business/managing/686961a8-3975-4ad5-bf4e-134706efee15 ```
## Request Path 파라미터 | Key | Description | Required | | ------------------- | ------------------ | -------- | | managedBusinessUuid | 삭제할 비즈니스의 식별값 UUID | yes |
## Response ```json { "ok": true } ``` ```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
## Error Codes | Status Code | Error Code | Description | | ----------- | ------------------------ | ----------------------------------------- | | 401 | UNAUTHORIZED\_API\_KEY | API Key가 유효하지 않은 경우 | | 403 | FORBIDDEN\_BUSINESS\_KEY | API Key에 이 API를 사용할 권한이 존재하지 않는 경우 | | 403 | FORBIDDEN\_BUSINESS | 해당 API Key로 생성한 비즈니스가 아닌 경우 | | 404 | NOT\_FOUND\_BUSINESS | API Key에 연결된 비즈니스 또는 삭제할 비즈니스가 존재하지 않는 경우 |
# 신규 고객 생성 API 플랫폼 서비스에서 특정 비즈니스에 고객을 생성할 수 있는 API를 제공합니다. 플랫폼 서비스에서 특정 비즈니스에 고객을 생성할 수 있는 API를 제공합니다.
## `POST` kit-api/v1/customers Method: POST\ Endpoint: kit-api/v1/customers
## Example ``` .../kit-api/v1/customers ``` ```json { "input": { "title": "김철수", "customKey": "A5-k159402", "ceo": "김대표", "registrationNumber": "789-30-01467", "address": "서울특별시 서초구 프릭스로 551", "industry": "정보통신업", "category": "응용 소프트웨어 개발 및 공급업", "managers": [ { "name": "이담당자", "email": "prix-customer-manager@email.com", "position": "이담당자 직책", "note": "이담당자 메모", "contact": "이담당자 연락처", "roles": ["TAX_BILL", "SUB_TAX_BILL", "CONTRACT"] // 담당자 역할 } ] } } ```
## Request Body | Key | Description | Required | | ------------------------ | ----------------------------------------------------------------------- | -------- | | input.title | 한글, 영어 대소문자, 숫자, -, , \_, 등으로 구성된 40자 이하의 새로 생성할 고객 이름 (같은 비즈니스 내 중복불가) | yes | | input.customKey | 새로 생성할 고객에게 할당하고 싶은 영어 대소문자, 숫자, -, \_로 구성된 40자 이하의 키 (같은 비즈니스 내 중복불가) | no | | input.ceo | 새로 생성할 고객 정보 - 대표자명 | no | | input.registrationNumber | 새로 생성할 고객 정보 - 사업자등록번호 (10자리 숫자, 해외기업은 15자리까지) | no | | input.address | 새로 생성할 고객 정보 - 사업장 주소 | no | | input.industry | 새로 생성할 고객 정보 - 업태 | no | | input.category | 새로 생성할 고객 정보 - 업종 | no | | input.managers | 새로 생성할 고객 정보 - 고객사 담당자 목록 | no | ### Request Body : input.managers | Key | Description | Required | | -------- | -------------------------------------------------- | -------- | | name | 고객사 담당자 이름 | yes | | email | 고객사 담당자 이메일 | no | | position | 고객사 담당자 직책 | no | | note | 고객사 담당자 노트 | no | | contact | 고객사 담당자 연락처 | no | | roles | 고객사 담당자 역할 목록 (세금계산서 기본 담당자, 세금계산서 추가 담당자, 계약 담당자) | no |
## Response ```json { "ok": true, "message": undefined, // 실패하는 경우 메시지 "data": { "id": 1, "title": "김철수", "customKey": "A5-k159402", "ceo": "김대표", "registrationNumber": "789-30-01467", "address": "서울특별시 서초구 프릭스로 551", "industry": "정보통신업", "category": "응용 소프트웨어 개발 및 공급업", "managers": [ { "name": "이담당자", "email": "prix-customer-manager@email.com", "position": "이담당자 직책", "note": "이담당자 메모", "contact": "이담당자 연락처", "roles": ["TAX_BILL", "SUB_TAX_BILL", "CONTRACT"] // 담당자 역할 } ] } } ```
## Error Codes | Status Code | Error Code | Description | | ----------- | --------------------------------- | ------------------------------- | | 400 | INVALID\_CUSTOMER\_TITLE | title이 생성 규칙을 벗어난 경우 | | 400 | INVALID\_CUSTOMER\_CUSTOM\_KEY | customKey가 생성 규칙을 벗어난 경우 | | 409 | DUPLICATED\_CUSTOMER\_TITLE | 해당 title을 가진 고객이 이미 존재하는 경우 | | 409 | DUPLICATED\_CUSTOMER\_CUSTOM\_KEY | 해당 customKey를 가진 고객이 이미 존재하는 경우 | | 500 | FAILED\_CREATE\_CUSTOMER | 고객 생성 과정에서 알 수 없는 에러가 발생한 경우 | | 400 | CUSTOMER\_MANAGER\_NAME\_REQUIRED | 고객사 담당자 이름이 누락된 경우 | | 400 | CUSTOMER\_INVALID\_MANAGER\_ROLE | 유효하지 않은 고객사 담당자 역할 | | 400 | CUSTOMER\_MANAGER\_MAX\_COUNT | 최대 고객사 담당자 수를 초과한 경우 |
# 고객 정보 조회 API 플랫폼 서비스에서 특정 비즈니스의 고객 정보를 조회할 수 있는 API를 제공합니다. 플랫폼 서비스에서 특정 비즈니스의 고객 정보를 조회할 수 있는 API를 제공합니다.
## `GET` kit-api/v1/customers/\[customerId] Method: GET\ Endpoint: kit-api/v1/customers/\[customerId]
## Example ``` ...kit-api/v1/customers/1 ```
## Request Path 파라미터 | Key | Description | Required | | ---------- | ----------- | -------- | | customerId | 조회할 고객 ID | yes | ## Response ```json { "ok": true, "data": { "id": 1, "title": "김철수", "customKey": "A5-k159402", "ceo": "김대표", "registrationNumber": "789-30-01467", "address": "서울특별시 서초구 프릭스로 551", "industry": "정보통신업", "category": "응용 소프트웨어 개발 및 공급업" } } ``` ```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
## Error Codes | Status Code | Error Code | Description | | ----------- | -------------------- | -------------- | | 404 | NOT\_FOUND\_CUSTOMER | 존재하지 않는 고객인 경우 |
# 고객 목록 조회 API 플랫폼 서비스에서 특정 비즈니스의 고객 목록을 조회할 수 있는 API를 제공합니다. 플랫폼 서비스에서 특정 비즈니스의 고객 목록을 조회할 수 있는 API를 제공합니다.
## `GET` kit-api/v1/customers Method: GET\ Endpoint: kit-api/v1/customers
## Example ``` ...kit-api/v1/customers?offset=0&limit=10 ``` ``` ...kit-api/v1/customers?customKey=A5-k159402 ```
## Request Query | Key | Description | Required | | --------- | --------------------------- | -------- | | limit | 목록 개수 (default 10, max 100) | no | | offset | 스킵할 목록 개수 | no | | customKey | 검색할 custom key (단건 검색) | no |
## Response ```json { "ok": true, "data": { "total": 2, "customers": [ { "id": 1, "title": "김철수", "customKey": "A5-k159402", "ceo": "김대표", "registrationNumber": "789-30-01467", "address": "서울특별시 서초구 프릭스로 551", "industry": "정보통신업", "category": "응용 소프트웨어 개발 및 공급업", "managers": [ { "name": "이담당자", "email": "customerManager@email.com", "position": "이담당자 직책", "note": "이담당자 메모", "contact": "이담당자 연락처", "roles": ["TAX_BILL", "SUB_TAX_BILL", "CONTRACT"] // 담당자 역할 } ] }, { "id": 2, "title": "김영희", "customKey": null } ] } } ``` ```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
## Error Codes | Status Code | Error Code | Description | | ----------- | ------------------------------ | --------------------- | | 400 | INVALID\_CUSTOMER\_CUSTOM\_KEY | 규칙을 벗어난 customKey인 경우 | | 404 | NOT\_FOUND\_CUSTOMER | 존재하지 않는 고객인 경우 |
# 고객 정보 변경 API 플랫폼 서비스에서 특정 비즈니스의 고객 정보를 변경할 수 있는 API를 제공합니다. 플랫폼 서비스에서 특정 비즈니스의 고객 정보를 변경할 수 있는 API를 제공합니다.
## `PATCH` kit-api/v1/customers/\[customerId] Method: PATCH\ Endpoint: kit-api/v1/customers/\[customerId] Param: customerId는 변경할 고객의 id(숫자) 값을 의미
## Example ``` ...kit-api/v1/customers/1 ``` ```json { "input": { "title": "김철수 매니저", "customKey": "B5-k159402", "ceo": "김대표", "registrationNumber": "789-30-01467", "address": "서울특별시 서초구 프릭스로 551", "industry": "정보통신업", "category": "응용 소프트웨어 개발 및 공급업", "managers": [ { "name": "이담당자", "email": "prix-customer-manager@email.com", "position": "이담당자 직책", "note": "이담당자 메모", "contact": "이담당자 연락처", "roles": ["TAX_BILL", "SUB_TAX_BILL", "CONTRACT"] // 담당자 역할 } ] } } ```
## Request Body | Key | Description | Required | | ------------------------ | ----------------------------------------------------------------------- | -------- | | input.title | 한글, 영어 대소문자, 숫자, -, , \_, 등으로 구성된 40자 이하의 새로 생성할 고객 이름 (같은 비즈니스 내 중복불가) | no | | input.customKey | 영어 대소문자, 숫자, -, \_로 구성된 40자 이하의 변경할 키 (같은 비즈니스 내 중복불가) | no | | input.ceo | 대표자명 | no | | input.registrationNumber | 사업자등록번호 (10자리 숫자, 해외기업은 15자리까지) | no | | input.address | 사업장 주소 | no | | input.industry | 업태 | no | | input.category | 업종 | no | | input.managers | 새로 생성할 고객 정보 - 고객사 담당자 목록 | no | ### Request Body : input.managers | Key | Description | Required | | -------- | -------------------------------------------------- | -------- | | name | 고객사 담당자 이름 | yes | | email | 고객사 담당자 이메일 | no | | position | 고객사 담당자 직책 | no | | note | 고객사 담당자 노트 | no | | contact | 고객사 담당자 연락처 | no | | roles | 고객사 담당자 역할 목록 (세금계산서 기본 담당자, 세금계산서 추가 담당자, 계약 담당자) | no |
## Response ```json { "ok": true, "data": { "id": 1, "title": "김철수 매니저", "customKey": "B5-k159402", "ceo": "김대표", "registrationNumber": "789-30-01467", "address": "서울특별시 서초구 프릭스로 551", "industry": "정보통신업", "category": "응용 소프트웨어 개발 및 공급업", "managers": [ { "name": "이담당자", "email": "prix-customer-manager@email.com", "position": "이담당자 직책", "note": "이담당자 메모", "contact": "이담당자 연락처", "roles": ["TAX_BILL", "SUB_TAX_BILL", "CONTRACT"] // 담당자 역할 } ] } } ``` ```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
## Error Codes | Status Code | Error Code | Description | | ----------- | --------------------------------- | ---------------------------------------- | | 404 | NOT\_FOUND\_CUSTOMER | 존재하지 않는 고객인 경우 | | 409 | ALREADY\_CUSTOMER\_EXISTS | 해당 title 또는 customKey를 가진 고객이 이미 존재하는 경우 | | 400 | CUSTOMER\_MANAGER\_NAME\_REQUIRED | 고객사 담당자 이름이 누락된 경우 | | 400 | CUSTOMER\_INVALID\_MANAGER\_ROLE | 유효하지 않은 고객사 담당자 역할 | | 400 | CUSTOMER\_MANAGER\_MAX\_COUNT | 최대 고객사 담당자 수를 초과한 경우 |
# 고객 삭제 API 플랫폼 서비스에서 특정 비즈니스의 고객을 삭제할 수 있는 API를 제공합니다. 플랫폼 서비스에서 특정 비즈니스의 고객 정보를 삭제할 수 있는 API를 제공합니다.
## `DELETE` kit-api/v1/customers/\[customerId] Method: DELETE\ Endpoint: kit-api/v1/customers/\[customerId]
## Example ``` ...kit-api/v1/customers/1 ```
## Request Path 파라미터 | Key | Description | Required | | ---------- | ----------- | -------- | | customerId | 삭제할 고객 ID | yes |
## Response ```json { "ok": true, "data": { "id": 1, "title": "김철수", "customKey": "A5-k159402", "ceo": "김대표", "registrationNumber": "789-30-01467", "address": "서울특별시 서초구 프릭스로 551", "industry": "정보통신업", "category": "응용 소프트웨어 개발 및 공급업" } } ``` ```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
| Status Code | Error Code | Description | | ----------- | -------------------- | -------------- | | 404 | NOT\_FOUND\_CUSTOMER | 존재하지 않는 고객인 경우 |
# 영업문서 생성 페이지 조회 API 플랫폼 서비스에서 영업문서(인보이스/견적서)를 생성할 수 있는 페이지를 반환하는 API를 제공합니다. 영업문서를 생성할 수 있는 페이지의 url을 응답으로 내려줍니다.\ 해당 경로를 새 창이나 새 탭으로 띄워서 영업문서를 생성할 수 있습니다. * 영업문서 생성에 필요한 정보를 입력하면 영업문서를 생성할 수 있습니다.
## `POST` kit-api/v1/documents/form-url Method: POST\ Endpoint: kit-api/v1/documents/form-url
## Example ``` ...kit-api/v1/documents/form-url ``` ```json { "input": { "documentType": "ESTIMATE" // 'ESTIMATE' | 'INVOICE' } } ```
## Request Body | Key | Description | Required | | ------------------ | ---------------------- | -------- | | input.documentType | 생성할 영업문서 종류(견적서, 인보이스) | yes |
## Response ```json { "ok": true, // api 성공 여부 "message": undefined, // Error가 존재하면 message(string)로 전달 "data": { "url": "https://www.prix.im/..." // 영업문서를 생성할 수 있는 페이지 주소 } } ``` # 영업문서 목록 조회 API 플랫폼 서비스에서 특정 비즈니스의 영업문서(인보이스/견적서) 목록을 조회할 수 있는 API를 제공합니다. 플랫폼 서비스에서 특정 비즈니스의 영업문서 목록을 조회할 수 있는 API를 제공합니다.
## `GET` kit-api/v1/documents Method: GET\ Endpoint: kit-api/v1/documents
## Example ``` ...kit-api/v1/documents?offset=0&limit=10&documentType=ESTIMATE&customerIds=8,9 ```
## Request Query | Key | Description | Required | | ------------ | ---------------------------------- | -------- | | limit | 목록 개수 (default 10, max 100) | no | | offset | 스킵할 목록 개수 | no | | documentType | 검색할 영업문서 종류(인보이스, 견적서) | yes | | customerIds | 검색할 영업문서에 연결된 고객 id 목록 | no | | dealUuids | 검색할 영업문서에 연결된 프로젝트 uuid 목록 (콤마 구분) | no |
## Response ```json { "ok": true, "data": { "total": 2, "documents": [ { "uuid": "ecd7d29c-6aab-481f-8939-e3ca3e1a37cf", "title": "견적서 제목", "status": "CREATED", // 영업문서 상태 (CREATED, SENT, APPROVED, DELETED) "createdAt": "2024-07-05T00:00:00.000Z", // 생성일 "updatedAt": "2024-10-15T00:00:00.000Z", // 변경일 "documentType": "ESTIMATE" // 영업문서 타입 (ESTIMATE, INVOICE) } ] } } ``` ```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
## Error Codes | Status Code | Error Code | Description | | ----------- | ------------------------ | --------------------- | | 403 | DOCUMENT\_ACCESS\_DENIED | 조회할 수 없는 영업문서가 포함된 경우 |
# 영업문서 상세 페이지 조회 API 플랫폼 서비스에서 특정 비즈니스의 영업문서(인보이스/견적서) 상세 페이지를 조회할 수 있는 API를 제공합니다. 응답으로 영업문서에 대한 상세 정보 페이지의 url을 내려줍니다.\ 해당 경로를 새 창이나 새 탭으로 띄워서 영업문서에 대한 상세 정보를 확인할 수 있습니다.
## `GET` kit-api/v1/documents/\[document uuid]/manage-url Method: GET\ Endpoint: kit-api/v1/documents/\[document uuid]/manage-url
## Example ``` ...kit-api/v1/documents/ed976505-bcbd-47bd-913d-f4cde05dea7a/manage-url ```
## Response ```json { "ok": true, // api 성공 시 "data": { "url": "https://www.prix.im/..." // 영업문서에 대한 상세 정보 페이지 주소 } } ```
```json { "ok": false, // api 실패 시 "message": "유효하지 않은 API KEY 정보입니다.", // header에 x-api-key가 유효하지 않는 경우 "errorCode": "UNAUTHORIZED_API_KEY" } ```
```json { "ok": false, // api 실패 시 "message": "권한이 없는 유저입니다.", // 비즈니스에 등록된 API 멤버의 권한이 해당 영업문서에 대한 권한이 없는 경우 "errorCode": "FORBIDDEN_USER" } ```
| Status Code | Error Code | Description | | ----------- | ------------------- | ------------------ | | 401 | FORBIDDEN\_BUSINESS | 헤당 영업문서에 권한이 없는 경우 |
# 프로젝트 목록 조회 API 프로젝트 목록을 조회할 수 있는 API를 제공합니다. 프로젝트 목록을 조회할 수 있는 API입니다. * API 권한이 연결된 멤버가 속한 팀의 프로젝트 조회 권한 범위로 결과를 반환합니다. * 프로젝트에 연결된 계약서, 영업문서, 세금계산서, 커스텀테이블 데이터는 각 목록 조회 API의 `dealUuids` 파라미터로 조회할 수 있습니다. * `updatedAtAfter` 파라미터로 마지막 동기화 이후 변경된 데이터만 조회할 수 있습니다. 프로젝트의 `updatedAt`은 프로젝트 정보와 별도 컬럼 값이 변경될 때 갱신되며, 연결된 일정·재무정보·계약서·영업문서의 변경은 각 데이터의 `updatedAt`으로 추적해 주세요.
## `GET` kit-api/v1/deals Method: GET\ Endpoint: kit-api/v1/deals
## Example ``` ...kit-api/v1/deals?limit=10&offset=0&status=ACTIVE&updatedAtAfter=2026-08-01T00:00:00.000Z ```
## Request Query | Key | Description | Required | | ------------------ | ----------------------------------------------------------- | -------- | | limit | 목록 개수 (default 10, max 100) | no | | offset | 스킵할 목록 개수 | no | | name | 프로젝트명으로 조회 (부분 일치) | no | | customKeys | 프로젝트 커스텀 ID 목록으로 조회 (콤마 구분) | no | | customerIds | 해당 id 속성을 가진 고객들과 연결된 프로젝트 조회 (콤마 구분) | no | | customerCustomKeys | 해당 customKey 속성을 가진 고객들과 연결된 프로젝트 조회 (콤마 구분) | no | | tagIds | 해당 태그들과 연결된 프로젝트 조회 (콤마 구분) | no | | status | 프로젝트 상태로 조회 (ACTIVE, CANCELED). 미지정 시 삭제된 프로젝트를 제외한 전체 | no | | periodStatus | 기간 상태에 해당하는 프로젝트 조회 (before, ongoing, after) | no | | startDateAfter | 시작일이 해당 날짜 이후인 프로젝트 조회 (date) | no | | endDateAfter | 종료일이 해당 날짜 이후인 프로젝트 조회 (date) | no | | endDateBefore | 종료일이 해당 날짜 이전인 프로젝트 조회 (date) | no | | createdAtAfter | 해당 날짜 이후 생성된 프로젝트 조회 (date) | no | | createdAtBefore | 해당 날짜 이전 생성된 프로젝트 조회 (date) | no | | updatedAtAfter | 해당 날짜 이후 변경된 프로젝트 조회 (date, 증분 동기화용) | no | | updatedAtBefore | 해당 날짜 이전 변경된 프로젝트 조회 (date) | no | | orderKey | 정렬 기준 (값: startDate, endDate, createdAt. default createdAt) | no | | orderValue | 정렬 방향 (값: ASC, DESC. default DESC) | no |
## Response \*재무정보는 프로젝트 상세 조회 API에서 조회할 수 있습니다. ```json { "ok": true, // api 성공 "data": { "total": 1, "deals": [ { "id": 1, "uuid": "38432ad8-a21f-43b3-9912-44295e3ecca1", // 프로젝트 식별값 (상세 조회, 다른 API의 dealUuids 파라미터에 사용) "customKey": "P-2026-001", // 프로젝트 커스텀 ID (없으면 null) "name": "A사 법률 자문", // 프로젝트명 "status": "ACTIVE", // 프로젝트 상태 (ACTIVE, CANCELED) "memo": "메모", // 프로젝트 메모 (없으면 null) "startDate": "2026-01-01T00:00:00.000Z", // 시작일 (없으면 null) "endDate": null, // 종료일 (없으면 null) "customers": [{ "id": 1, "title": "A컴퍼니", "customKey": "A5-k159402" }], // 연결된 고객 "managers": [{ "id": 3, "name": "홍길동", "email": "hong@example.com" }], // 담당자 "tags": [{ "id": 7, "name": "자문" }], // 프로젝트 태그 "columnItems": [ // 별도 컬럼 (컬럼 타입별 value: STRING 문자열, NUMBER 숫자, BOOLEAN 불리언, DATE 날짜, TAG [{ id, name }], LOOKUP 문자열) { "columnId": 11, "name": "담당 변호사", "slug": "lawyer", "value": "김변호사" }, { "columnId": 12, "name": "분야", "slug": "field", "value": [{ "id": 5, "name": "기업법무" }] } ], "createdAt": "2026-01-01T00:00:00.000Z", // 생성일 "updatedAt": "2026-08-01T00:00:00.000Z" // 변경일 } ] } } ```
```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
## Error Codes | Status Code | Error Code | Description | | ----------- | ------------------------------ | --------------------- | | 400 | INVALID\_CUSTOMER\_CUSTOM\_KEY | 규칙을 벗어난 customKey인 경우 |
# 프로젝트 상세 조회 API 프로젝트 상세 정보(재무정보 포함)를 조회할 수 있는 API를 제공합니다. 프로젝트 상세 정보를 조회할 수 있는 API입니다. 목록 조회 응답에 재무정보가 추가됩니다.
## `GET` kit-api/v1/deals/{deal uuid} Method: GET\ Endpoint: kit-api/v1/deals/{deal uuid}
## Example ``` ...kit-api/v1/deals/38432ad8-a21f-43b3-9912-44295e3ecca1 ```
## Response * `accountingRecords`의 `supplyAmount`(공급가액), `taxAmount`(세액)는 총액과 VAT 유형으로 계산된 값입니다. * 계약서, 영업문서, 세금계산서, 커스텀테이블, 일정은 각 목록 조회 API의 `dealUuids` 파라미터로 조회해 주세요. ```json { "ok": true, // api 성공 "data": { "deal": { // ...프로젝트 목록 조회 응답과 동일한 필드 (id, uuid, customKey, name, status, memo, startDate, endDate, customers, managers, tags, columnItems, createdAt, updatedAt) "accountingRecords": [ // 재무정보 { "id": 11, "name": "1차 자문료", // 항목명 "type": "REVENUE", // 매출(REVENUE), 매입(COST) "currency": "WON", // 통화 (WON, USD, EUR, JPY) "vat": "EXCLUSIVE", // VAT 유형 (EXCLUSIVE 별도, TAX_FREE 면세) "amount": 1100000, // 총액 (VAT 포함) "supplyAmount": 1000000, // 공급가액 "taxAmount": 100000, // 세액 "doneAmount": 1100000, // 입금/수금액 (없으면 null) "accrualDate": null, // 인식일 (없으면 null) "note": null, // 메모 "counterpart": { "id": 1, "title": "A컴퍼니", "customKey": "A5-k159402" }, // 거래처 "schedule": { // 연결된 일정 (없으면 null) "id": 21, "title": "1차 청구", "scheduleTime": "2026-02-01T00:00:00.000Z", // 일정일 "isDone": true, // 완료 여부 "doneDate": "2026-02-03T00:00:00.000Z" // 완료일 (입금일로 활용) } } ] } } } ```
```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
## Error Codes | Status Code | Error Code | Description | | ----------- | ---------------- | -------------------------------------- | | 404 | NOT\_FOUND\_DEAL | 프로젝트가 없거나 삭제되었거나 연결된 멤버에게 조회 권한이 없는 경우 |
# 일정 목록 조회 API 프로젝트 일정과 재무일정 목록을 조회할 수 있는 API를 제공합니다. 프로젝트 일정과 재무일정(재무정보가 연결된 일정)을 함께 조회할 수 있는 API입니다. * 프로젝트에 연결된 일정은 API 권한이 연결된 멤버에게 해당 프로젝트 조회 권한이 있을 때만 포함되며, 프로젝트가 없는 일정은 항상 포함됩니다. * 매출/매입 구분은 `accountingRecord.type`으로, 입금일은 일정의 완료일(`doneDate`)과 입금액(`accountingRecord.doneAmount`)으로 확인할 수 있습니다. * 매출/매입 합계는 응답에 포함되지 않으므로 행 데이터를 합산해 주세요.
## `GET` kit-api/v1/schedules Method: GET\ Endpoint: kit-api/v1/schedules
## Example ``` ...kit-api/v1/schedules?scheduleTimeAfter=2026-01-01T00:00:00.000Z&scheduleTimeBefore=2026-12-31T23:59:59.999Z&hasAccounting=true&limit=100 ```
## Request Query | Key | Description | Required | | ------------------ | ---------------------------------------------------------------- | -------- | | limit | 목록 개수 (default 10, max 100) | no | | offset | 스킵할 목록 개수 | no | | scheduleTimeAfter | 기준일이 해당 날짜 이후인 일정 조회 (date) | no | | scheduleTimeBefore | 기준일이 해당 날짜 이전인 일정 조회 (date) | no | | dateBasis | 기간 필터 기준일 (값: CASH 일정일, ACCRUAL 인식일(인식일이 없으면 일정일). default CASH) | no | | dealUuid | 특정 프로젝트의 일정만 조회 | no | | customerId | 재무정보 거래처 고객 id로 조회 | no | | isDone | 완료 여부로 조회 (true, false) | no | | hasAccounting | 재무정보 유무로 조회 (true: 재무일정만, false: 일반 일정만, 미지정: 전체) | no | | accountingType | 매출/매입 구분으로 조회 (REVENUE, COST) | no | | tagIds | 해당 일정 태그들과 연결된 일정 조회 (콤마 구분) | no | | orderValue | 일정일 기준 정렬 방향 (값: ASC, DESC. default ASC) | no |
## Response ```json { "ok": true, // api 성공 "data": { "total": 1, "schedules": [ { "id": 21, "title": "1차 청구", // 일정명 "scheduleTime": "2026-02-01T00:00:00.000Z", // 일정일 "isDone": true, // 완료 여부 "doneDate": "2026-02-03T00:00:00.000Z", // 완료일 (재무일정의 입금일로 활용, 없으면 null) "dueDate": null, // 마감일 (없으면 null) "tags": [{ "id": 9, "name": "청구" }], // 일정 태그 "deal": { "uuid": "38432ad8-a21f-43b3-9912-44295e3ecca1", "name": "A사 법률 자문", "customKey": "P-2026-001" }, // 연결된 프로젝트 (없으면 null) "accountingRecord": { // 재무정보 (일반 일정은 null) "id": 11, "name": "1차 자문료", // 항목명 "type": "REVENUE", // 매출(REVENUE), 매입(COST) "currency": "WON", // 통화 (WON, USD, EUR, JPY) "vat": "EXCLUSIVE", // VAT 유형 (EXCLUSIVE 별도, TAX_FREE 면세) "amount": 1100000, // 총액 (VAT 포함) "supplyAmount": 1000000, // 공급가액 "taxAmount": 100000, // 세액 "doneAmount": 1100000, // 입금/수금액 (없으면 null) "accrualDate": null, // 인식일 (없으면 null) "note": null, // 메모 "counterpart": { "id": 1, "title": "A컴퍼니", "customKey": "A5-k159402" } // 거래처 }, "createdAt": "2026-01-15T00:00:00.000Z", // 생성일 "updatedAt": "2026-02-03T00:00:00.000Z" // 변경일 } ] } } ```
```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
# 커스텀테이블 목록 조회 API 커스텀테이블 목록과 각 테이블의 컬럼 정의를 조회할 수 있는 API를 제공합니다. 타임시트, 연차/휴가 등 비즈니스별로 구성한 커스텀테이블 목록과 각 테이블의 컬럼 정의를 조회할 수 있는 API입니다. * 테이블은 프릭스 어드민에서 설정한 `slug` 또는 테이블 `uuid`로 식별합니다. slug는 프릭스 팀에 요청해 설정할 수 있습니다. * 테이블과 컬럼은 API 권한이 연결된 멤버가 속한 팀의 조회 권한 범위로 반환됩니다.
## `GET` kit-api/v1/custom-tables Method: GET\ Endpoint: kit-api/v1/custom-tables
## Example ``` ...kit-api/v1/custom-tables ```
## Response ```json { "ok": true, // api 성공 "data": { "customTables": [ { "uuid": "706a317d-5fbb-4870-930b-eade57f4f955", // 테이블 식별값 "slug": "timesheet", // 테이블 slug (설정되지 않았으면 null) "title": "타임시트", // 테이블명 "option": { "hasUsers": true, // 담당자 컬럼 사용 여부 "hasCustomers": false, // 고객 컬럼 사용 여부 "hasDeals": true // 프로젝트 컬럼 사용 여부 }, "columns": [ // 컬럼 정의 (order 순) { "id": 101, "name": "근무일", "slug": "work-date", "type": "DATE", "required": true, "order": 1 }, { "id": 102, "name": "업무 구분", "slug": "work-type", "type": "TAG", "required": false, "order": 2, "tags": [{ "id": 5, "name": "자문" }, { "id": 6, "name": "소송" }] // TAG 타입만: 선택 가능한 태그 목록 }, { "id": 103, "name": "시간(분)", "slug": "minutes", "type": "NUMBER", "required": true, "order": 3 }, { "id": 104, "name": "관련 안건", "slug": "matter", "type": "RELATION", "required": false, "order": 4, "relation": { // RELATION 타입만: 참조 대상 정보 "targetEntityType": "CUSTOM_TABLE", // CUSTOM_TABLE, CUSTOMER "customTableSlug": "matters", // 대상이 커스텀테이블일 때 (없으면 null) "customTableUuid": "a3c1..." // 대상이 커스텀테이블일 때 (없으면 null) } }, { "id": 105, "name": "안건 담당자", "slug": "matter-owner", "type": "LOOKUP", "required": false, "order": 5 } ] } ] } } ```
```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
# 커스텀테이블 행 목록 조회 API 커스텀테이블의 행 데이터를 조회할 수 있는 API를 제공합니다. 커스텀테이블의 행 데이터를 조회할 수 있는 API입니다. * 테이블은 프릭스 어드민에서 설정한 `slug` 또는 테이블 `uuid`로 식별합니다. * 행은 API 권한이 연결된 멤버가 속한 팀의 조회 권한 범위로 반환됩니다. * 셀 값(`columnItems[].value`)은 컬럼 타입에 따라 아래 형식으로 제공됩니다. | 컬럼 타입 | value 형식 | | -------- | ------------------------------------------------------------------- | | STRING | 문자열 | | NUMBER | 숫자 | | BOOLEAN | true / false | | DATE | ISO 8601 날짜 문자열 | | TAG | `[{ "id": 5, "name": "자문" }]` 형태의 배열 | | RELATION | 대상이 커스텀테이블이면 `[{ "uuid", "title" }]`, 고객이면 `[{ "id", "title" }]` 배열 | | LOOKUP | 문자열 (참조한 값의 표시 문구) |
## `GET` kit-api/v1/custom-tables/{key}/rows Method: GET\ Endpoint: kit-api/v1/custom-tables/{key}/rows * `key`에는 테이블 `slug` 또는 `uuid`를 사용할 수 있습니다.
## Example ``` ...kit-api/v1/custom-tables/timesheet/rows?limit=100&updatedAtAfter=2026-08-01T00:00:00.000Z ``` ``` ...kit-api/v1/custom-tables/706a317d-5fbb-4870-930b-eade57f4f955/rows?slugColumnKeys=work-type&slugColumnValues=자문 ```
## Request Query | Key | Description | Required | | ---------------- | --------------------------------------------------- | -------- | | limit | 목록 개수 (default 10, max 100) | no | | offset | 스킵할 목록 개수 | no | | title | 행 제목으로 조회 (부분 일치) | no | | dealUuids | 해당 uuid 속성을 가진 프로젝트들과 연결된 행 조회 (콤마 구분) | no | | customerIds | 해당 id 속성을 가진 고객들과 연결된 행 조회 (콤마 구분) | no | | createdAtAfter | 해당 날짜 이후 생성된 행 조회 (date) | no | | createdAtBefore | 해당 날짜 이전 생성된 행 조회 (date) | no | | updatedAtAfter | 해당 날짜 이후 변경된 행 조회 (date, 증분 동기화용) | no | | updatedAtBefore | 해당 날짜 이전 변경된 행 조회 (date) | no | | slugColumnKeys | 검색할 컬럼의 slug 목록 (콤마 구분) | no | | slugColumnValues | 검색할 컬럼별 값 목록 (콤마 구분). slugColumnKeys가 있으면 필수, 개수 일치 | no |
## Response * 목록은 생성일 내림차순으로 정렬됩니다. * `users`, `customers`, `deals`는 테이블 설정(option)에서 사용하는 항목만 값이 채워지고, 사용하지 않는 항목은 빈 배열입니다. * 히스토리 기능을 사용하는 테이블은 현재 값만 반환됩니다. ```json { "ok": true, // api 성공 "data": { "total": 1, "rows": [ { "id": 501, "uuid": "c1f3a2d4-1b2c-4d5e-8f90-123456789abc", // 행 식별값 "title": "2026-08-01 홍길동", // 행 제목 "users": [{ "id": 3, "name": "홍길동" }], // 담당자 "customers": [], // 고객 "deals": [{ "uuid": "38432ad8-a21f-43b3-9912-44295e3ecca1", "name": "A사 법률 자문", "customKey": "P-2026-001" }], // 프로젝트 "columnItems": [ // 셀 값. columnId는 커스텀테이블 목록 조회 API의 columns[].id (컬럼 타입별 value 형식은 상단 표 참고) { "columnId": 101, "name": "근무일", "slug": "work-date", "value": "2026-08-01T00:00:00.000Z" }, { "columnId": 102, "name": "업무 구분", "slug": "work-type", "value": [{ "id": 5, "name": "자문" }] }, { "columnId": 103, "name": "시간(분)", "slug": "minutes", "value": 90 }, { "columnId": 104, "name": "관련 안건", "slug": "matter", "value": [{ "uuid": "a3c1...", "title": "A사 계약검토" }] }, { "columnId": 105, "name": "안건 담당자", "slug": "matter-owner", "value": "김변호사" } ], "createdBy": { "id": 3, "name": "홍길동" }, // 생성자 (없으면 null) "createdAt": "2026-08-01T09:00:00.000Z", // 생성일 "updatedAt": "2026-08-01T09:00:00.000Z" // 변경일 } ] } } ```
```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
## Error Codes | Status Code | Error Code | Description | | ----------- | ----------------------------------------- | ----------------------------------------------- | | 400 | SLUG\_COLUMN\_KEYS\_AND\_VALUES\_MISMATCH | slugColumnKeys 값과 slugColumnValues 값의 개수가 다른 경우 | | 403 | CUSTOM\_TABLE\_ACCESS\_DENIED | 연결된 멤버에게 테이블 조회 권한이 없는 경우 | | 404 | NOT\_FOUND\_CUSTOM\_TABLE | slug 또는 uuid에 해당하는 테이블이 없는 경우 | | 404 | NOT\_FOUND\_CUSTOM\_COLUMN | slugColumnKeys에 존재하지 않는 컬럼 slug가 포함된 경우 |
# 세금계산서 목록 조회 API 세금계산서 목록을 조회할 수 있는 API를 제공합니다. 프릭스에서 발행한 세금계산서 목록을 조회할 수 있는 API입니다. * API 권한이 연결된 멤버가 속한 팀에 세금계산서 권한이 있어야 합니다. * 프릭스에 저장된 발행 정보를 제공하며, 발행 이후의 국세청 전송·취소 등 실시간 상태는 포함되지 않습니다.
## `GET` kit-api/v1/tax-bills Method: GET\ Endpoint: kit-api/v1/tax-bills
## Example ``` ...kit-api/v1/tax-bills?issueDateAfter=2026-08-01&issueDateBefore=2026-08-31&limit=100 ```
## Request Query | Key | Description | Required | | --------------- | ------------------------------------------ | -------- | | limit | 목록 개수 (default 10, max 100) | no | | offset | 스킵할 목록 개수 | no | | issueDateAfter | 발행일이 해당 날짜 이후인 세금계산서 조회 (date) | no | | issueDateBefore | 발행일이 해당 날짜 이전인 세금계산서 조회 (date, 해당 일자 포함) | no | | customerIds | 해당 id 속성을 가진 고객들과 연결된 세금계산서 조회 (콤마 구분) | no | | dealUuids | 해당 uuid 속성을 가진 프로젝트들과 연결된 세금계산서 조회 (콤마 구분) | no | | hasSchedule | 일정 연결 여부로 조회 (true, false) | no | | createdAtAfter | 해당 날짜 이후 생성된 세금계산서 조회 (date) | no | | createdAtBefore | 해당 날짜 이전 생성된 세금계산서 조회 (date) | no |
## Response * 목록은 생성일 내림차순으로 정렬됩니다. * 연결된 멤버에게 조회 권한이 없는 프로젝트는 `deal`이 null로 제공됩니다. ```json { "ok": true, // api 성공 "data": { "total": 1, "taxBills": [ { "id": 31, "managementKey": "PRIX-20260801-0001", // 바로빌 관리번호 "ntsSendKey": "20260801410000000001", // 국세청 승인번호 (없으면 null) "status": "CREATED", // CREATED(발행), MODIFIED(수정세금계산서) "issueDate": "2026-08-01T00:00:00.000Z", // 발행일(작성일) "purposeType": "INVOICE", // RECEIVED(영수), INVOICE(청구) "modifyCode": null, // 수정 사유 (MISTAKE, AMOUNT_CHANGED, REFUND, CONTRACT_CANCELATION, LETTER_OF_CREDIT, DOUBLE_ISSUANCE. 없으면 null) "amount": 1100000, // 합계 "supplyAmount": 1000000, // 공급가액 "taxAmount": 100000, // 세액 "remark": "8월 자문료", // 비고 (없으면 null) "customer": { "id": 1, "title": "A컴퍼니", "customKey": "A5-k159402" }, // 연결된 고객 (없으면 null) "taxBillCustomer": { // 발행 시점의 공급받는자 정보 "title": "A컴퍼니", "registrationNumber": "123-45-67890", "ceo": "김대표", "address": "서울특별시 서초구 프릭스로 551" }, "deal": { "uuid": "38432ad8-a21f-43b3-9912-44295e3ecca1", "name": "A사 법률 자문", "customKey": "P-2026-001" }, // 연결된 프로젝트 (없거나 권한 없으면 null) "scheduleId": 21, // 연결된 일정 id (없으면 null) "parentTaxBillId": null, // 수정세금계산서의 원본 세금계산서 id (없으면 null) "createdAt": "2026-08-01T09:00:00.000Z", // 생성일 "updatedAt": "2026-08-01T09:00:00.000Z" // 변경일 } ] } } ```
```json { "ok": false, // api 실패 "message": "error message", // Error가 존재하면 message(string)로 전달 "errorCode": "ERROR_CODE" } ```
## Error Codes | Status Code | Error Code | Description | | ----------- | --------------------- | -------------------------- | | 403 | FORBIDDEN\_PERMISSION | 연결된 멤버의 팀에 세금계산서 권한이 없는 경우 |
# 웹훅 이용하기 프릭스에서 제공하는 웹훅 이벤트 목록입니다. 프릭스에서 제공하는 웹훅 이벤트 목록입니다. 워크스페이스 내 "설정 메뉴 > 웹훅 관리"에서 웹훅을 관리할 수 있습니다. * 직접 원하는 이벤트에 맞게 웹훅을 추가할 수 있습니다. * 원하는 계약 태그를 선택하여 해당 태그가 붙은 계약서 이벤트에만 웹훅을 발송할 수 있습니다. (태그 필터 미등록 시 모든 이벤트 발송) * 웹훅 로그 목록을 확인할 수 있습니다.
## 웹훅 태그 필터 **계약서 이벤트**( 계약서 생성, 전자서명 요청/체결/참여/만료 이벤트)에 대해 특정 계약 태그를 선택하여 웹훅을 등록할 수 있습니다. ### 태그 필터의 동작 방식 * **태그 미등록**: 웹훅이 모든 계약서 이벤트를 수신합니다. * **태그 등록**: 해당 태그가 붙은 계약서 이벤트에만 웹훅이 발송됩니다. * **다중 태그 등록**: 등록된 태그 중 **하나 이상**이 계약서에 붙어있으면 웹훅이 발송됩니다 ### 태그 필터 제약사항 * **영업문서 이벤트**(`DOCUMENT_*`)와 태그 필터는 함께 사용할 수 없습니다. * 영업문서에는 태그가 없기 때문에, 웹훅 UI에서 영업문서 이벤트를 선택하면 태그 입력 필드가 자동으로 숨겨집니다. * 계약서 이벤트와 영업문서 이벤트를 함께 선택한 경우, 혼합된 상태에서도 태그 필터링이 불가능합니다. * **전자서명 템플릿 삭제 이벤트**(`SIGNATURE_TEMPLATE_DELETED`)는 계약서 태그 필터 대상이 아닙니다. * 해당 이벤트를 구독한 웹훅에는 태그 설정과 상관없이 이벤트가 발송됩니다.
## (1) 웹훅 이벤트 타입 웹훅으로 등록할 수 있는 이벤트 타입은 아래와 같습니다. | 이벤트 타입 | 설명 | 카테고리 | | ---------------------------- | ---------------------------------------------------------- | -------- | | CONTRACT\_CREATED | 계약서 등록 이벤트입니다. | 계약서 | | SIGNATURE\_CREATED | 전자서명 생성 이벤트입니다. | 전자서명 | | SIGNATURE\_CONCLUDED | 모든 참여자가 서명을 완료하여 계약이 체결되는 이벤트입니다. | 전자서명 | | SIGNATURE\_PARTICIPATED | 개별 전자서명 참여자의 서명 완료 이벤트입니다. | 전자서명 | | SIGNATURE\_EXPIRED | 전자서명이 체결되지 않고 만료된 경우, 만료일 다음날 오전 11시에 호출되는 전자서명 만료 이벤트입니다. | 전자서명 | | SIGNATURE\_TEMPLATE\_DELETED | 전자서명 템플릿이 삭제되는 이벤트입니다. | 전자서명 템플릿 | | DOCUMENT\_CREATED | 영업문서 생성 완료 이벤트입니다. | 영업문서 |
## (2) 계약서 카테고리 웹훅 이벤트 본문 계약서 카테고리의 웹훅 요청의 Body 예시입니다. ```json { "eventType": "CONTRACT_CREATED", "createdAt": "2024-11-15T00:00:00.000Z", "contract": { "uuid": "ed976505-bcbd-47bd-913d-f4cde05dea7a", // 문서 식별값 (uuid 값을 api에서 사용) "title": "A컴퍼니 MOU", // 계약서 이름 "status": "CREATED", // 계약 상태 (CREATED, CONCLUDED) "createdAt": "2024-11-15T00:00:00.000Z", "tagIds": [1, 3], // 계약서에 붙은 태그 ID 목록 (태그 필터 등록 시에만 포함) "tagNames": ["production", "important"] // 계약서에 붙은 태그 이름 목록 (태그 필터 등록 시에만 포함) } } ``` > **참고**: `tagIds`와 `tagNames`는 웹훅 등록 시 태그를 선택한 경우에만 payload에 포함됩니다.
## (3) 전자서명 카테고리 웹훅 이벤트 본문 전자서명 카테고리의 웹훅 요청의 Body 예시입니다. ```json { "eventType": "SIGNATURE_CREATED", "createdAt": "2024-11-15T00:00:00.000Z", "contract": { "uuid": "ed976505-bcbd-47bd-913d-f4cde05dea7a", // 문서 식별값 (uuid 값을 api에서 사용) "title": "A컴퍼니 MOU", // 계약서 이름 "status": "CREATED", // 계약 상태 (CREATED, CONCLUDED) "createdAt": "2024-11-01T00:00:00.000Z", "tagIds": [1, 3], // 계약서에 붙은 태그 ID 목록 (태그 필터 등록 시에만 포함) "tagNames": ["production", "important"] // 계약서에 붙은 태그 이름 목록 (태그 필터 등록 시에만 포함) }, "signature": { "uuid": "57139f5c-37d0-4c30-bdb6-ef6106040756", // 전자서명 식별자 "title": "A컴퍼니 MOU 서명 요청", // 전자서명 이름 "status": "WAITING", // 상태 (WAITING, DONE, CANCELED / WAITING은 서명 요청 후 대기 상태를 의미) "createdAt": "2024-11-15T00:00:00.000Z" } } ```
## (4) 전자서명 템플릿 카테고리 웹훅 이벤트 본문 전자서명 템플릿 카테고리의 웹훅 요청의 Body 예시입니다. ```json { "eventType": "SIGNATURE_TEMPLATE_DELETED", "createdAt": "2024-11-15T00:00:00.000Z", "signatureTemplate": { "id": 4328, // 전자서명 템플릿 식별값 "name": "MOU 템플릿", // 전자서명 템플릿 이름 "slug": "template-slug" // slug(문자) } } ``` > **참고**: `SIGNATURE_TEMPLATE_DELETED` 이벤트는 계약서 태그 필터와 상관없이 발송됩니다.
## (5) 영업문서 카테고리 웹훅 이벤트 본문 영업문서 카테고리의 웹훅 요청의 Body 예시입니다. ```json { "eventType": "DOCUMENT_CREATED", "createdAt": "2024-11-15T00:00:00.000Z", "document": { "id": 1, "uuid": "ed976505-bcbd-47bd-913d-f4cde05dea7a", // 문서 식별값 (uuid 값을 api에서 사용) "title": "A컴퍼니 영업문서", // 영업문서 이름 "status": "CREATED", // 영업문서 상태 (CREATED, SENT, APPROVED, DELETED) "createdAt": "2024-11-01T00:00:00.000Z", "updatedAt": "2024-11-01T00:00:00.000Z" } } ```