Search
Duplicate

프릭스 Open API 문서

연동 방법

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
복사