이 기능은 웍스 결재 상품 신청 후 사용 가능합니다.

개발자 도구

개발자 도구를 사용하여 결재 정보와 고객사 기업 정보 시스템을 연동할 수 있습니다. 결재 정보를 연동하면 서식별 결재 상태를 회사의 기업 정보 시스템으로 자동 발송할 수 있으며, 회사 기업 정보 시스템에서 다양하게 활용할 수 있습니다.

결재 연동 설정 및 처리 흐름:

발송 설정
- '결재 관리 > 개발자 도구'에서 발송 서식 추가/수정
- 발송 대상 서식 및 상태 선택
- 서식별 Callback URL 입력
결재 이벤트 발생
- '결재 > 문서 작성'에서 문서 기안, 수정, 승인, 자동 동의, 반려 등 이벤트 발생
- 발송 대상으로 설정한 상태의 이벤트만 전송
이벤트 메시지 등록 및 처리
- 이벤트 메시지를 시스템 내부 대기열에 등록
- 등록된 순서대로 순차 처리하고, 설정된 Callback URL 호출
Callback URL 처리
- 고객사 서버에서 전달받은 이벤트 정보 처리
- 필요한 경우 docDataUrl로 결재 문서 데이터 조회
발송 내역 조회
- '결재 관리 > 개발자 도구 > 발송 내역 조회'에서 발송 결과 확인
- 실패 건 재발송 가능

발송 설정

회사 기업 정보 시스템으로 발송할 결재 문서의 서식, 결재 상태, 지정한 URL을 설정합니다.

발송 서식 추가/수정

Admin에서 '서비스 > 결재 관리 > 개발자 도구 > 발송 설정'으로 이동합니다.
발송 서식을 추가하거나 수정합니다.
- 추가 시: 발송 서식 추가를 선택합니다.
- 수정 시: 변경할 서식의 를 선택합니다.
발송 서식 추가 팝업창에서 연동 설정할 서식을 선택합니다.
서식별 전송받을 정보를 설정합니다.
- Callback URL 입력: 서식의 Callback URL을 입력합니다. 입력 방법은 'Callback URL 입력'을 참고해 주세요.(이벤트 처리 참조)
- 결재 상태 선택: 전송받을 상태를 선택합니다. 결재 관리자의 명칭 관리 설정에 따라 명칭이 다르게 보일 수 있습니다.
'추가' 또는 '수정'을 클릭하여 설정을 완료합니다.

Callback URL 입력

서식별 발생되는 이벤트에 대해 전송받을 Callback URL을 입력합니다.

서식별 이벤트를 전송받고자 할 경우 Callback을 받는 URL을 각각 설정합니다. 만약 같은 URL로 사용하려면 다음 예시와 같이 dfmId를 get 파라미터로 설정해 사용할 수 있습니다.

이벤트 Callback 시 전달하는 객체 구조는 아래와 같으며, 이는 2024년 하반기에 배포한 신규 API 기준입니다.

필드	설명
docDataUrl	미사용
aprvDocId	문서의 내부 PK, 문서 상세 조회 API 호출 시 approvalDocumentId를 의미
processYmdt	이벤트 발생 일시, 문서의 생성 시간이 아니라 이벤트의 발송 일시를 의미
docNo	문서 번호, 문서 상세 조회 API 호출 시 documentNumber를 의미
sendTpCd	이벤트 상태, 발송한 이벤트의 종류를 의미
dfmId	서식ID, 문서 상세 조회 API 호출 시 documentFormId를 의미

전송 가능한 이벤트(sendTpCd)는 다음 표를 참고해 주세요.

sendTpCd	설명	상세
DRAFT	작성	작성자가 문서를 저장하는 이벤트
APPROVE	동의(결재)	결재자가 문서를 동의 방식으로 승인하는 이벤트
AUTO_APPROVE	자동 동의(참조)	결재자가 문서를 자동 동의 방식으로 승인하는 이벤트
COOPERATION	합의(합의 결재)	결재자가 문서를 합의 방식으로 승인하는 이벤트
PARARELL_APPROVE	병렬 결재	결재자가 문서를 병렬 결재 방식으로 승인하는 이벤트
PARARELL_COOPERATION	병렬 합의	결재자가 문서를 병렬 합의 방식으로 승인하는 이벤트
FORWARD	회송	결재자가 문서 수정을 요청하여 작성자에게 되돌리는 이벤트
DELEGATE	위임	결재자가 다른 사람에게 결재 위임하는 이벤트
REJECT	거절(반려)	결재자가 문서를 반려하는 이벤트
POSTPONE	보류	결재자가 문서 결재를 보류하는 이벤트
APPROVED	완료(승인함)	문서가 완결되었을 때 발생하는 이벤트
CANCELED	취소(승인 취소된)	관리자가 승인된 문서를 승인 취소했을 때 발생하는 이벤트
CANCEL_APPROVE	승인 취소	결재자가 승인한 문서를 승인 취소했을 때 발생하는 이벤트
DELETED	삭제	관리자가 문서를 삭제했을 때 발생하는 이벤트
RETRIEVE	회수	작성자가 문서를 회수하는 이벤트

이벤트 처리

등록된 Callback URL을 PUT 메소드를 이용해 호출하여 결재 문서에서 발생하는 이벤트를 실시간으로 처리합니다. 처리 방법은 다음과 같습니다.

Method: PUT
Media Type: application/json

PUT 메소드 호출 결과의 응답 코드에 따라 다음과 같이 처리합니다.

응답 코드가 200번대로 리턴된 경우: 발송 성공으로 기록.
응답 코드가 400번대, 500번대로 리턴될 경우: 발송 실패로 기록.

처리 결과는 Admin의 Developers에 기록됩니다. 발송 상세 내역은 '발송 내역 조회'를 참고해 주세요.

발송 내역 조회

회사의 기업 정보 시스템에 발송한 결재 정보의 성공 및 실패 내역을 조회하고 실패 내역을 재발송할 수 있습니다. 또한 API를 이용하여 전송받은 문서의 상세 내용을 조회할 수 있습니다.

발송 내역 조회 화면은 다음과 같이 구성되어 있습니다.

영역	설명
검색	서식, 문서 번호, 발송일, 제목을 입력해 검색
재발송	발송 실패 내역 재발송
다운로드	발송 내역 다운로드
발송 내역 목록	발송 내역 확인

실패 내역 재발송

발송 실패한 내역을 재발송할 수 있습니다.

Admin에서 '서비스 > 결재 관리 > 개발자 도구 > 발송 내역 조회'으로 이동합니다.
발송 성공 및 실패 내역을 선택합니다.
'재발송'을 클릭합니다.

API를 이용한 문서 상세 조회

제공 API를 호출하면 전송받은 문서의 상세 내용을 조회할 수 있습니다.

이벤트로 제공받은 aprvDocId를 이용한 조회가 가능합니다.

API 호출 예시: https://www.worksapis.com/v1.0/business-support/approval/documents/12345

컴포넌트 연동 설정

서식에 포함된 특정 컴포넌트에 대해 회사 고유 컴포넌트 Key를 설정하도록 연동할 수 있습니다. 설정된 컴포넌트 Key 는 오픈 API를 이용한 문서 상세 조회 시 파라미터로 활용할 수 있습니다.

컴포넌트 Key 설정 및 활용의 흐름:

서식 생성

'결재 관리 > 서식 관리 > 서식 만들기'에서 서식 생성
서식 '사용' 설정 필수

서식 연동 설정

'결재 관리 > 개발자 도구 > 컴포넌트 연동 설정'에서 서식 선택

컴포넌트 연동

'결재 관리 > 서식 관리 > 연동 설정한 서식 > '서식 만들기' 탭 > '서식 편집기'에서 컴포넌트 선택 후 오른쪽 패널에서 '사용자 지정 ID' 옵션 입력

서식 정보 조회 API 호출

입력한 '사용자 지정 ID'는 API를 이용한 문서 상세 조회 시, 파라미터로 활용 가능

컴포넌트 Key를 설정할 서식을 추가할 수 있습니다.

Admin에서 '서비스 > 결재 관리 > 개발자 도구 > 컴포넌트 연동 설정'으로 이동합니다.
'연동 서식 추가'를 클릭합니다.
카테고리와 서식을 선택합니다.
- 서식의 사용 여부가 표시됩니다. '서식 편집기'로 생성한 서식은 '사용'으로 설정된 서식만 선택할 수 있습니다.
'저장'을 클릭합니다.
연동된 서식에서 컴포넌트 '사용자 지정 ID'를 설정합니다.
- 자세한 내용은 '사용자 지정 ID 설정'을 참고해 주세요.

사용자 지정 ID 설정

연동된 서식은 서식 상세의 옵션 영역에 '컴포넌트 연동 설정' 옵션이 노출됩니다.

연동한 서식의 컴포넌트 사용자 지정 ID를 설정할 수 있습니다.

Admin에서 '서비스 > 결재 관리 > 서식 > 서식 관리'로 이동합니다.
연동 설정한 서식의 을 클릭합니다.
'서식 만들기' 탭에서 서식 편집기를 엽니다.
컴포넌트 연동 설정 영역에 '사용자 지정 ID'를 입력합니다.
- 연동된 서식의 모든 컴포넌트에 입력할 수 있습니다.
'서식 저장'을 클릭해 저장합니다.
- 입력한 사용자 지정 ID는 서식 정보 조회 API 호출 시 파라미터로 활용할 수 있습니다.