전자서명 API

패스 앱을 이용하여 이용자의 개인정보(이름, 생년월일, 휴대폰번호)로 각종 계약체결 및 금융거래 서명의 수단으로 사용되는 패스 전자서명 API 입니다. 개발하는 웹/앱 방식에 따라 패스 앱으로 푸시(Push) 인증 메시지를 전송하여 인증하는 “푸시(Push) 인증”과 이용기관 앱에서 패스 앱을 실행하여 패스 인증 메시지 전송없이 비밀번호 입력만으로 인증하는 “앱투앱 인증” 방식 중 선택하여 연동할 수 있습니다.

1. RequestSign - 전자서명 요청

  • 패스 이용자에게 문서의 전자서명을 요청합니다.

  • 앱투앱 인증 방식을 이용하는 이용기관은 [앱스킴 호출] 을 참고하여 주시기 바랍니다.

def requestSign(self, clientCode, sign) :

Parameter

순번 변수명 타입 길이 필수 설명
clientCode str 12 Y 이용기관 코드
sign Sign - Y 전자서명 요청 정보

Return SignReceipt Throws BarocertException

2. GetSignStatus - 전자서명 상태확인

  • 전자서명 요청 후 반환받은 접수아이디로 인증 진행 상태를 확인합니다.

  • 상태확인 함수는 전자서명 요청 함수를 호출한 당일 23시 59분 59초까지만 호출 가능합니다.

  • 전자서명 요청 함수를 호출한 당일 23시 59분 59초 이후 상태확인 함수를 호출할 경우 오류가 반환됩니다.

def getSignStatus(self, clientCode, receiptID) :

Parameter

순번 변수명 타입 길이 필수 설명
clientCode str 12 Y 이용기관 코드
receiptID str 32 Y 접수 아이디

Return SignStatus Throws BarocertException

3. VerifySign - 전자서명 검증

  • 완료된 전자서명을 검증하고 전자서명값(signedData)을 반환 받습니다.

  • 검증 함수는 전자서명 요청 함수를 호출한 당일 23시 59분 59초까지만 호출 가능합니다.

  • 전자서명 요청 함수를 호출한 당일 23시 59분 59초 이후 검증 함수를 호출할 경우 오류가 반환됩니다.

이용기관 서버에서는 전자서명 검증을 통해 반환받은 이용자정보(CI, 성명, 생년월일 등)와 전자서명 요청 이용자정보를 비교해 올바른 이용자인지 검증해야 합니다.
def verifySign(self, clientCode, receiptID, signVerify) :

Parameter

순번 변수명 타입 길이 필수 설명
clientCode str 12 Y 이용기관 코드
receiptID str 32 Y 접수 아이디
signVerify SignVerify - Y 전자서명 서명검증 요청정보

Return SignResult Throws BarocertException

4. 앱스킴 호출

4.1 Android

  • 전자서명을 요청하기 위하여 이용기관은 이용기관 App 에서 패스 App 앱스킴을 호출합니다.

  • 패스 App 앱스킴 호출시 입력한 callbackScheme으로 이용자의 전자서명 결과값 [ResponseCode]를 반환 받습니다.

{scheme}&callbackScheme={clientAppScheme}&packageName={clientPackageName}

Parameter

순번 변수명 타입 길이 필수 설명
scheme str - Y 전자서명 요청시 반환된 앱스킴
clientAppScheme str - Y 패스 앱 인증완료 후 호출될 이용기관 앱스킴
clientPackageName str - Y 패스 앱 인증완료 후 호출될 이용기관 앱패키지명

Return {clientAppScheme}://?code={ResponseCode}

4.2 iOS

  • 전자서명을 요청하기 위하여 이용기관은 이용기관 App 에서 패스 App 앱스킴을 호출합니다.

  • 패스 App 앱스킴 호출시 입력한 callbackScheme으로 이용자의 전자서명 결과값 [ResponseCode]를 반환 받습니다.

{scheme}&callbackScheme={clientAppScheme}

Parameter

순번 변수명 타입 길이 필수 설명
scheme str - Y 전자서명 요청시 반환된 앱스킴
clientAppScheme str - Y 패스 앱 인증완료 후 호출될 이용기관 앱스킴

Return {clientAppScheme}://?code={ResponseCode}

4.3 ResponseCode

순번 code 설명
E0000 성공
E3001 패스 서비스 미가입자
E3002 패스 인증서 미발급자
E3003 사용자 인증 시 취소 또는 서명 과정 중 취소
E3004 사용자 인증 시 인증 실패 (생체 인증 실패 등)
E3005 단말 네트워크 환경 등으로 인한 통신 실패
E3006 통신사 서버에서 에러 발생
E3007 인증서 Library 서명에서 에러 발생
E3999 기타 오류

5. 객체정보

5.1. BarocertException

순번 변수명 타입 길이 필수 설명
Code Long - Y API 처리에 대한 응답코드
message str - Y API 처리에 대한 응답메시지

5.2. Sign

순번 변수명 타입 길이 필수 설명
clientCode str 12 Y 이용기관 코드
receiverHP str 11 Y 수신자 휴대폰번호
→ 하이픈(-) 제외하고 입력
receiverName str 80 Y 수신자 성명
receiverBirthday str 8 N 수신자 생년월일
→ 형식: yyyyMMdd
reqTitle str 40 Y 인증요청 메시지 제목
reqMessage str 500 Y 인증요청 메시지 내용
callCenterNum str 12 Y 고객센터 연락처
expireIn int 4 Y 요청 만료시간
→ 최대: 1000초(s) / 권장: 300초(s)
token str 2800 Y 원문
tokenType str 4 Y 원문 유형
  • TEXT원문 텍스트 데이터
  • HASH원문을 해쉬한 데이터
  • URL원문 URL 주소
originalTypeCode str 2 조건부 원본유형코드
  • AG동의서
  • AP신청서
  • CT계약서
  • GD안내서
  • NT통지서
  • TR약관

tokenType="HASH" or "URL" 경우 필수

originalURL str - 조건부 원본조회URL

tokenType="HASH" or "URL" 경우 필수

originalFormatCode str 17 조건부 원본형태코드
  • TEXT원문 텍스트 데이터
  • HTMLHTML 데이터
  • DOWNLOAD_IMAGE이미지 다운로드
  • DOWNLOAD_DOCUMENT문서 다운로드

tokenType="HASH" or "URL" 경우 필수

userAgreementYN bool - N 사용자 동의 필요 여부
  • True필요
  • False불필요 : 기본값
receiverInfoYN bool - N 사용자 정보 포함 여부
  • True포함 : 기본값
  • False불포함
appUseYN bool - N 앱투앱 인증 방식 이용 여부
telcoType str 3 조건부 통신사 유형
  • SKT
  • KT
  • LGU

appUseYN=True 경우 필수

deviceOSType str 7 조건부 모바일장비 운영체제
  • ANDROID
  • IOS

appUseYN=True 경우 필수

5.3. SignVerify

순번 변수명 타입 길이 필수 설명
receiverHP str 11 Y 수신자 휴대폰번호
→ 하이픈(-) 제외하고 입력
receiverName str 80 Y 수신자 성명

5.4. SignReceipt

순번 변수명 타입 길이 필수 설명
receiptID str 32 Y 접수아이디
scheme str 100 N 앱스킴

appUseYN=True 경우 반환

marketUrl str - N 앱 다운로드 URL

appUseYN=True 경우 반환

5.5. SignStatus

순번 변수명 타입 길이 필수 설명
receiptID str 32 Y 접수아이디
clientCode str 12 Y 이용기관 코드
state int 1 Y 상태
  • 0대기
  • 1완료
  • 2만료
  • 3거절
  • 4실패
  • 5미처리
requestDT str 14 Y 전자서명 요청일시
→ 형식: yyyyMMddHHmmss
completeDT str 14 N 전자서명 완료일시
→ 형식: yyyyMMddHHmmss
expireDT str 14 Y 전자서명 만료일시
→ 형식: yyyyMMddHHmmss
rejectDT str 14 N 전자서명 거절일시
→ 형식: yyyyMMddHHmmss

5.6. SignResult

순번 변수명 타입 길이 필수 설명
receiptID str 32 Y 접수아이디
state int 1 Y 상태
  • 0대기
  • 1완료
  • 2만료
  • 3거절
  • 4실패
  • 5미처리
receiverHP str 11 N RSA 암호화 수신자 휴대폰번호
→ 하이픈(-) 제외하고 입력

receiverInfoYN=True 경우 반환

receiverName str 80 N RSA 암호화 수신자 성명

receiverInfoYN=True 경우 반환

receiverYear str 4 N RSA 암호화 수신자 출생년도
→ 형식 : yyyy

receiverInfoYN=True 경우 반환

receiverDay str 4 N RSA 암호화 수신자 출생월일
→ 형식 : MMdd

receiverInfoYN=True 경우 반환

receiverGender str 1 N RSA 암호화 수신자 성별
  • M남성
  • F여성

receiverInfoYN=True 경우 반환

receiverForeign str 1 N RSA 암호화 외국인 여부
  • Y외국인
  • N내국인

receiverInfoYN=True 경우 반환

receiverTelcoType str 3 N RSA 암호화 통신사 유형
  • SKT
  • KT
  • LGU

receiverInfoYN=True 경우 반환

signedData str - Y 전자서명값
ci str - Y RSA 암호화 CI