개발자 문서
개발자 문서

멀티계정 기관별 준비물

연결할 기관을 고른 뒤 필요한 인증서, VID 보조값, 계좌 입력을 확인합니다.

사용할 기관을 찾아 연결에 넣을 재료와 로그인 작업에 넘길 값을 준비하세요.

표의 값은 서버가 SDK 계약으로 내보내는 기관별 입력 계약에서 그대로 옮겼습니다.

연결 전에: 사용할 기관의 준비물

고객사 프로그램이 이미 보관 중인 자격증명을 사용합니다. 고객사 DB, 파일 저장소, 인증 모듈에서 읽은 값을 SDK 연결 함수에 넣는 것이 정상 경로입니다.

아래에서 기관을 찾아 필요한 재료와 로그인 입력을 준비하고, 다음도 먼저 확인하세요.

  • 회사 키의 환경과 상품 권한
  • 고객 자격증명을 대신 연결해도 된다는 고객의 사용 동의

인증서 파일 보유, XBOSS 연결, 기관 로그인 성공은 각각 다른 단계입니다.

인증서로 연결하는 기관

기관 / provider연결 요청에 넣는 재료로그인 작업로그인 작업에 함께 넘기는 값
홈택스 / hometax인증서(DER), 개인키(DER), 인증서 비밀번호hometax.session.login없음
국민건강보험공단 EDI / nhis_edi인증서(DER), 개인키(DER), 인증서 비밀번호nhis_edi.session.login없음
국민연금공단 EDI / nps_edi인증서(DER), 개인키(DER), 인증서 비밀번호nps_edi.auth.npki_session.login사업장관리번호(business_management_no) 필수: 숫자 11자리입니다. 하이픈을 넣어 보내도 숫자만 남겨 씁니다.
4대보험 / fourinsure인증서(DER), 개인키(DER), 인증서 비밀번호fourinsure.session.login없음
근로복지공단 / comwel인증서(DER), 개인키(DER), 인증서 비밀번호comwel.auth.npki_session.login사업장관리번호(business_management_no) 선택: 사업자등록번호에 사업장이 둘 이상일 때 로그인할 사업장의 관리번호입니다. 숫자 11자리이고 하이픈을 넣어 보내도 숫자만 남겨 씁니다. 사업장이 하나면 비워 둡니다.; 사업자등록번호(business_registration_no) 필수: 숫자 10자리입니다. 하이픈을 넣어 보내도 숫자만 남겨 씁니다.
고용24 / work24인증서(DER), 개인키(DER), 인증서 비밀번호work24.auth.npki_session.login사업장관리번호(business_management_no) 선택: 사무대행기관 로그인에 함께 넘깁니다.; 사업자등록번호(business_registration_no) 필수: 숫자 10자리입니다. 하이픈을 넣어 보내도 숫자만 남겨 씁니다.; 사무대행기관번호(isoa_no) 선택: 회원유형이 사무대행기관일 때 넘깁니다.; 회원유형(member_type_code) 선택: 일반사업자 또는 사무대행기관. 로그인 화면이 유형마다 다릅니다. BE904 또는 BE902 중 하나(기본값 BE904)
사회보험통합징수포털 / si4n인증서(DER), 개인키(DER), 인증서 비밀번호si4n.session.login사업자등록번호(business_registration_no) 필수: 숫자 10자리; 회원 아이디(member_id) 선택:
정부24 / gov24인증서(DER), 개인키(DER), 인증서 비밀번호gov24.session.login회원 유형(member_type) 선택: 회원 유형입니다. 지금은 corporate(법인)만 받고, 보내지 않으면 corporate 로 씁니다. corporate 중 하나(기본값 corporate)
교통민원24 / efine인증서(DER), 개인키(DER), 인증서 비밀번호efine.session.login사업자등록번호(business_registration_no) 필수: 숫자 10자리; 상호(법인명)(company_name) 필수: 형식 \S
KB국민카드 기업카드 / kb_biz_card인증서(DER), 개인키(DER), 인증서 비밀번호kb_biz_card.session.login없음
위택스 / wetax인증서(DER), 개인키(DER), 인증서 비밀번호wetax.session.login없음

아이디와 비밀번호로 연결하는 기관

기관 / provider아이디 칸비밀번호 칸본인확인 번호가 뜻하는 것
신한은행 간편조회 / shinhan_easy기관 로그인 ID(login_id)기관 로그인 비밀번호: 글자 그대로-
IBK기업은행 빠른조회 / ibk_fast_account계좌번호(login_id): 숫자 14자리계좌 비밀번호(account_password): 숫자 4자리, 사업자등록번호 뒷자리 7자리 (개인은 생년월일 6자리)(identity_verification_value): 숫자 6자리 또는 7자리사업자등록번호 뒷자리 7자리 (개인은 생년월일 6자리)
KB국민은행 빠른조회 / kb_fast_account계좌번호(login_id): 숫자 10~16자리계좌 비밀번호(account_password): 숫자 4자리, 사업자등록번호 10자리 (개인은 생년월일 6자리)(identity_verification_value): 숫자 6자리 또는 10자리사업자등록번호 10자리 (개인은 생년월일 6자리)
우리은행 빠른조회 / woori_bank계좌번호(login_id): 숫자 1~20자리계좌 비밀번호(account_password): 숫자 4자리, 사업자등록번호 뒷자리 5자리(identity_suffix): 숫자 5자리사업자등록번호 뒷자리 5자리
하나은행 빠른조회 / hana_fast_account계좌번호(login_id): 숫자 11~14자리계좌 비밀번호(account_password): 숫자 4자리, 사업자등록번호 뒷자리 5자리 (개인은 생년월일 6자리)(identity_verification_value): 숫자 5자리 또는 6자리사업자등록번호 뒷자리 5자리 (개인은 생년월일 6자리)
NH농협은행 빠른조회 / nh_fast_account계좌번호(login_id): 숫자 1~17자리계좌 비밀번호(account_password): 숫자 4자리, 사업자등록번호(business_number): 숫자 10자리사업자등록번호
네이버 검색광고 / naver_searchad광고계정 번호(Customer ID)(login_id): 숫자 1~20자리API 라이선스 키(api_key): 글자 그대로, 비밀키(secret_key): 글자 그대로-

동의 화면으로 연결하는 기관

기관 / provider연결 방법
Google 마케팅 / google콘솔에서 동의 화면을 왕복해 발급합니다. 인증서 파일이나 아이디·비밀번호 연결 API 로는 등록하지 않습니다.

로그인 화면으로 연결하는 기관

기관 / provider연결 방법
티스토리 / tistory콘솔의 「연동하기」 로 제공사 로그인 화면을 거쳐 연결합니다. 따로 준비할 것은 없습니다.
네이버 마케팅 / naver콘솔의 「연동하기」 로 제공사 로그인 화면을 거쳐 연결합니다. 따로 준비할 것은 없습니다.

인증서의 VID 보조값(random_enc)

홈택스 · 국민연금공단 EDI 연결에는 인증서에서 얻는 VID 보조값(random_enc)이 쓰이지만 보내지 않아도 됩니다. 서버가 받은 개인키에서 이 인증서의 값을 직접 읽습니다.

  • random_enc 는 임의 난수가 아니라 그 인증서에서 얻은 VID 보조값의 원문 문자열입니다. 보낼 때는 RSA 로 암호화하기 전 값을 넘기면 SDK 가 암호화합니다.
  • 서버가 읽은 값이 있으면 그 값을 씁니다. 함께 보낸 값이 달라도 서버가 읽은 값이 우선합니다.
  • 서버가 개인키를 열지 못한 경우(키 형식을 해석할 수 없거나, 키에 해당 값이 없거나, 비밀번호가 맞지 않는 경우)에만 보낸 random_enc 를 씁니다.
  • 연결이 만들어졌다는 것은 기관 로그인이 성공했다는 뜻이 아니므로, 짝이 맞는 값을 준비하고 로그인 작업의 결과로 확인하세요.

고객사는 연결(link) 요청에 인증서, 개인키, 비밀번호를 함께 보냅니다.

그 값을 얻는 준비 경로는 둘이며 회사 환경에 맞는 하나를 구현합니다.

경로언제 쓰나VID 준비
1. XBOSS 연결 프로그램(코드의 이름은 PKI Agent)Windows 인증서 PC 에서 XBOSS 연결 프로그램으로 인증서를 스캔하고 고르는 화면을 쓸 때XBOSS 연결 프로그램 1.2.3 이상을 실행하고 candidate_id 를 골라 certificate-agent --candidate-id ...(SDK 함수 link_certificate_from_pki_agent)를 씁니다. SDK 가 VID 를 먼저 얻은 뒤 같은 인증서 파일을 읽어 등록합니다. 연결 프로그램이 응답했지만 VID 를 주지 못하면 SDK 는 random_enc 없이 등록을 시도하고, 서버가 개인키에서도 읽지 못하면 위 오류로 거부됩니다.
2. 고객사 인증 모듈XBOSS 연결 프로그램을 쓸 수 없는 환경(인증서 PC 가 아닌 서버 등) 또는 자체 인증 모듈이 있을 때고객사 인증 모듈이 그 인증서에서 얻은 RSA 암호화 전 VID 문자열을 link_certificate 의 random_enc 에 그대로 전달합니다.

어떤 경로든 화면에서 고른 인증서 = VID 를 얻은 인증서 = 연결에 넣은 인증서(bytes) 가 같아야 합니다.

  • 표시 이름, 발급자, 만료일만 보고 자동으로 짝을 맞추지 마세요. serial, sha256, DER bytes 로 같은 인증서를 식별합니다.
  • XBOSS 연결 프로그램은 인증서가 있는 PC 에서 따로 실행해 두어야 합니다.
  • 연결이 HTTP 400 VALIDATION_INVALID_FIELD 로 거부되면(HTTP 로 직접 부르면 메시지가 「인증서에서 본인 확인 정보를 읽지 못했습니다」 로 시작합니다. SDK 예외에는 메시지가 없고 code, http_status, trace_id 같은 식별값만 실립니다)홈택스 · 국민연금공단 EDI 연결 성공을 안내하지 마세요.

인증서 선택 시 확인 항목

항목용도주의
DER cert bytes / sha256연결, VID, 재연결 때 같은 인증서인지 판단화면에 보이는 이름과 1:1 이 아님
인증서 serial목록 중복과 만료본 구분같은 이름의 다른 인증서가 있을 수 있음
만료일사용 가능 여부만료되거나 폐기된 인증서는 연결 전에 제외
random_enc 출처(보낼 때)XBOSS 연결 프로그램이 준비했는지, 고객사 모듈이 준비했는지서버가 개인키에서 읽지 못할 때만 쓰이는 값입니다. 보낼 때는 그 인증서 bytes 에서 얻은 값만 씁니다. 다른 인증서의 VID 를 재사용하지 않습니다

인증서 저장 형식 (고객사 자유, 연결 시 bytes 필요)

연결 함수를 부르기 직전에 bytes 로 풀어 같은 인증서 쌍을 넣으면 됩니다.

XBOSS 연결 API 는 최종적으로 DER 형식의 인증서와 개인키 bytes 에 비밀번호(필요하면 random_enc)를 요구합니다. 파일을 다시 올리는 화면은 필수가 아닙니다.

은행 빠른조회 입력

은행 번호와 비밀번호는 앞의 0 이 사라지지 않도록 문자열로 처리합니다. 계좌번호의 하이픈과 공백은 서버 규격에 따라 정규화됩니다.

복합 입력(계좌 비밀번호, 본인확인 번호, version)을 비밀번호 문자열 하나로 대신하지 마세요.

  • SDK 의 encode_login_secret(.NET 은 EncodeLoginSecret)이 version 1 을 붙여 JSON 을 만듭니다.
  • 실행 예제는 항목을 따로 입력받아 공개 스키마대로 구성합니다.

세부 필수값과 형식은 connect.py catalog 기관 목록의 input_contract.secret_schema 에서 확인합니다.

로그인과 계좌 선택의 선행 조건

국민연금공단 EDI의 사업장관리번호와 근로복지공단, 고용24, 사회보험통합징수포털의 사업자등록번호, 교통민원24의 사업자등록번호와 상호는 인증서 등록 필드가 아니라 로그인 작업의 params 입니다(위 표의 로그인 작업에 함께 넘기는 값).

  • 근로복지공단에서는 한 사업자등록번호에 사업장이 둘 이상이면 로그인할 사업장의 business_management_no 도 함께 넘깁니다. 사업장이 하나면 보내지 않아도 됩니다.
  • 고용24에서는 일반사업자면 member_type_code=BE904, 사무대행기관이면 BE902 를 쓰고, 후자는 isoa_no 와 business_management_no 를 기관 계정에 맞춰 준비합니다.
  • 신한은행 간편조회 거래내역에는 로그인 연결 외에 별도로 만든 계좌 자격증명의 bank_account_credential_id 가 필요합니다.
  • SDK 0.1.2 에는 그 계좌 자격증명을 만드는 함수가 없으니, 이 거래내역이 필요하면 서비스문의로 먼저 알려 주세요.
  • 다른 은행도 연결 응답에 계좌 ID 가 있으면 고객, 기관, 환경과 함께 저장합니다.

멀티계정 키는 기관을 명시해 연결합니다. 한 기관의 account_link_id 를 다른 기관에 재사용하거나 콘솔의 자동 다기관 등록과 섞어 쓰지 마세요.

위 표의 로그인 입력을 모든 상품의 입력 규격으로 쓰지 마세요.