연동 방법
header에 x-api-key 값을 포함하여 API를 호출합니다.
•
API 주소는 다음과 같습니다.
◦
실서비스 API 주소: https://api.prix.im
◦
테스트 API 주소: https://api-qa.prix.im
•
API 외의 웹 서비스 이용에 대한 부분은 서비스 가이드를 참조해 주세요.
◦
서비스 내에서 생성한 계약서와 전자서명 정보를 확인하고 관리할 수 있습니다.
(1) API Key 발급받기
프릭스 서비스에 회원가입 후 로그인하면 API key를 발급 받을 수 있습니다.
•
서비스 좌측 메뉴의 비즈니스 페이지에 들어가서 ‘API 관리’ 버튼을 누르면 API Key를 발급할 수 있는 페이지로 이동됩니다.
•
기본적으로는 API 관리 기능을 사용할 수 없으며, API 관리 버튼을 사용하기 위해서는 프릭스 담당자에게 문의해 주세요.
(2) API 권한 연결하기
계약서/전자서명 API를 사용하기 위해서는 비즈니스에 등록된 멤버와의 권한 연결이 필요합니다.
•
예를 들어 관리자 멤버와 권한을 연결하면 API는 관리자 권한을 갖고 요청을 수행하거나 목록을 조회할 수 있습니다.
•
비즈니스 페이지 팀/멤버 탭에서 권한을 연결할 멤버에 해당하는 ‘편집’ 버튼을 누르면 멤버 모달이 나타납니다.
•
나타나는 멤버 모달에서 ‘API 권한’에 ‘계약서’를 체크합니다.
프릭스 API
데이터 타입
프릭스 API에서 사용하는 응답에 대한 데이터 타입 명세입니다.
워크플로우
계약/전자계약
1. 전자서명 진행 관련 API
(1) 전자서명 입력 Form Url API
API URL | GET api/v1/contracts/form-url |
기능 설명 | 계약서 및 전자서명을 생성할 수 있는 url을 반환하는 API입니다. |
•
반환된 url을 새로운 탭이나 창으로 띄워서 계약서를 생성하거나 전자서명까지 시작할 수 있습니다.
◦
페이지에 진입하면 서명 유형을 선택하는 화면이 나오는데, 해당 화면은 니즈에 따라 일부 커스텀 제공이 가능합니다.
◦
페이지의 유형에 따라 전자계약을 진행하지 않고 계약서만 생성할 수도 있습니다.
◦
계약 문서를 등록하고 전자서명 정보(서명 참여자 및 서명 위치)를 입력하여 제출하면 전자서명이 시작됩니다.
▪
참여자 정보에 등록한 이메일이나 전화번호로 참여 링크가 포함된 이메일/카카오톡이 발송됩니다.
◦
successUrl 쿼리파라미터 값을 사용하여 계약서/서명 생성 완료 후 이동되는 페이지를 지정할 수 있습니다.
•
응답 예시
{
"ok": true, // api 성공 여부
"message": undefined, // Error가 존재하면 message(string)로 전달
"data": {
"url": "https://www.prix.im/..." // 계약서 및 전자서명을 등록할 수 있는 페이지 주소
}
}
TypeScript
복사
2. 워크플로우를 이용한 전자서명 진행 관련 API
워크플로우란 전자서명에 사용될 문서와 서명 위치를 미리 지정하고, 변동되는 값만 입력하여 전자서명을 요청할 수 있는 기능을 의미합니다. 워크플로우 API를 이용하기 위해서는 미리 워크플로우를 등록해야 하며, 해당 기능은 관련 가이드를 참조해 주세요.
•
관련 가이드 페이지: https://docs.prix.im/contracts/5
(1) 워크플로우 목록 조회 API
API URL | GET api/v1/signature-templates/ |
기능 설명 | 등록된 워크플로우 목록을 확인할 수 있는 API입니다. |
•
목록을 조회하여 사용할 워크플로우 id를 확인할 수 있습니다.
•
응답 예시
{
"ok": true, // api 성공 여부
"message": undefined, // Error가 존재하면 message(string)로 전달
"data": {
"templates": [{signature template data}], // 상단의 SignatureTemplate 타입 명세 참조
"total": 0, // 워크플로우 총 개수
}
}
TypeScript
복사
(2) 워크플로우 정보(입력값) 조회 API
API URL | GET api/v1/signature-templates/[template id] |
기능 설명 | 특정 워크플로우로 전자서명을 요청하는데 필요한 입력값을 확인할 수 있는 API입니다. |
•
워크플로우 사용을 위한 입력값(SigantureTemplateObject) 및 참여자(SignatureTemplateParticipant) 정보를 확인할 수 있습니다.
•
응답 예시
{
"ok": true, // api 성공 여부
"message": undefined, // Error가 존재하면 message(string)로 전달
"data": {signature template data} // 상단의 SignatureTemplate 타입 명세 참조
}
TypeScript
복사
(3) 워크플로우 사용 API
API URL | POST api/v1/signature-templates/[template id]/use-template |
기능 설명 | 워크플로우를 사용하여 계약서를 생성하고 전자서명을 발송하는 API입니다. |
•
워크플로우 정보 조회 API를 통해 확인한 내용을 기반으로 필요한 정보를 포함하여 전자서명을 생성합니다.
◦
서명 만료일 지정이 필요하며, 만료일이 지나면 서명 참여가 불가합니다.
◦
참여자 이메일 혹은 전화번호로 요청이 가능하며, 사용하지 않는 값은 빈 문자열로 입력합니다.
◦
참조자 메일을 설정할 수 있습니다. (참조자는 서명 시작과 완료 시 이메일을 받게 됩니다)
•
Request Body
{
input: {
title: '근로계약서_김프릭', // 전자서명 이름
expiredDate: '2024-08-20T15:00:00.000Z', // 서명 만료일 (현재보다 이후 시간이어야 함)
type: "NEW", // 재계약 여부 (NEW, RENEWAL 존재)
participants: [{ // 서명 참여자 정보
role: '기업', // 참여자 역할 (워크플로우의 참여자와 매칭)
input: {
name: '김사장', // 참여자 이름
email: 'test@prix.im', // 참여자 이메일 (이메일, 전화번호 중에 하나 필요)
phone: '', // 참여자 전화번호 (이메일, 전화번호 중에 하나 필요)
auth: "EMAIL", // 인증 수단 (EMAIL, PHONE 존재 / send와 동일한 값으로 입력)
send: "EMAIL", // 발송 수단 (EMAIL, PHONE 존재)
}
}, { // 서명 참여자 정보
role: '근로자', // 참여자 역할 (워크플로우의 참여자와 매칭)
input: {
name: '이멤버', // 참여자 이름
email: '', // 참여자 이메일 (이메일, 전화번호 중에 하나 필요)
phone: '010-1234-1234', // 참여자 전화번호 (이메일, 전화번호 중에 하나 필요)
auth: "PHONE", // 인증 수단 (EMAIL, PHONE 존재 / send와 동일한 값으로 입력)
send: "PHONE", // 발송 수단 (EMAIL, PHONE 존재)
}
}],
items: [{ // 추가 입력값 내용 추가를 위해 사용
id: -1, // 서명 입력값 구분 id (ex. '금액' 추가 입력값의 id가 -1이라면)
contents: '2,000,000', // 서명 입력값 내용
}, {
id: -2, // (ex. '주소' 추가 입력값의 id가 -2라면)
contents: '선릉로 551 새롬아파트 101-204',
}],
contractDate: { // 계약 관련 일자 (선택)
startDate: '2024-06-20T15:00:00.000Z' // 시작일 (선택)
endDate: '2024-12-20T15:00:00.000Z' // 종료일 (선택)
},
ccEmails: [], // 참조자 이메일 목록 (선택)
}
}
TypeScript
복사
•
응답 예시
{
"ok": true, // api 성공 여부
"message": undefined, // Error가 존재하면 message(string)로 전달
"data": {
"contract": {contract data}, // 상단의 Contract 타입 명세 참조
"signature": {signature data} /// 상단의 Signature 타입 명세 참조
}
}
TypeScript
복사
3. 계약서/전자서명 API
(1) 계약서(전자서명) 정보 조회 API
API URL | GET api/v1/contracts/[contract uuid] |
개발 현황 | 실서비스 사용 가능 |
기능 설명 | 계약서 및 전자계약에 대한 정보/현황을 조회할 수 있는 API입니다. |
•
응답 예시
{
"ok": true, // api 성공 여부
"message": undefined, // Error가 존재하면 message(string)로 전달
"data": {contract data} // 상단의 Contract 타입 명세 참조
}
TypeScript
복사
(2) 전자서명 취소 API
API URL | POST api/v1/signatures/[signature uuid]/cancel |
개발 현황 | 실서비스 사용 가능 |
기능 설명 | 진행 중인 전자계약을 취소할 수 있는 API입니다. |
•
서명이 체결 완료되기 전에만 취소가 가능합니다.
◦
서명 참여자에게 전자서명 취소 메시지가 발송됩니다.
•
응답 예시
{
"ok": true, // api 성공 여부
"message": undefined, // Error가 존재하면 message(string)로 전달
"data": {signature data} // 상단의 Signature 타입 명세 참조
}
TypeScript
복사