멀티계정 기관별 준비물

이 페이지는 빠른 시작의 설치와 catalog 확인을 마친 뒤, 개발 규격의 고객 연결 단계 직전에 봅니다. 사용할 기관을 찾아 연결에 넣을 재료와 로그인 작업에 넘길 값을 준비하세요. 표의 값은 서버가 SDK 계약으로 내보내는 기관별 입력 계약에서 그대로 옮겼습니다.

고객사 프로그램이 이미 보관 중인 자격증명을 사용합니다. 고객사 DB, 파일 저장소, 인증 모듈에서 읽은 값을 SDK 연결 함수에 넣는 것이 정상 경로입니다. 아래에서 기관을 찾아 필요한 재료와 로그인 입력을 먼저 준비하세요. 인증서 파일을 갖고 있다는 것, XBOSS 에 연결했다는 것, 기관 로그인이 성공했다는 것은 각각 다른 단계입니다. 회사 키의 환경과 상품 권한, 그리고 고객의 자격증명을 대신 연결해도 된다는 고객의 사용 동의도 먼저 확인합니다.

연결할 때 선택한 인증서와 짝이 맞는 random_enc 를 함께 보내야 하는 기관은 홈택스 · 국민연금공단 EDI 입니다. random_enc 는 임의 난수가 아니라 그 인증서에서 얻은 VID 보조값의 원문 문자열이고, RSA 로 암호화하기 전 값을 넘기면 SDK 가 암호화합니다. 서버는 연결 요청에 random_enc 가 있는지만 확인하고 그 값이 이 인증서의 것인지는 확인하지 않습니다. 연결이 만들어졌다는 것은 기관 로그인이 성공했다는 뜻이 아니므로, 짝이 맞는 값을 준비하고 로그인 작업의 결과로 확인하세요.

고객사는 연결(link) 직전에 그 인증서 bytes 에 대한 VID 를 얻고, 같은 요청에 인증서, 개인키, 비밀번호, random_enc 를 함께 보냅니다. 준비 경로는 둘이며 회사 환경에 맞는 하나를 구현합니다. 어느 경로도 준비되지 않았다면 홈택스 · 국민연금공단 EDI 연결을 진행하지 않습니다.

XBOSS 연결 API 는 최종적으로 DER 형식의 인증서와 개인키 bytes 에 비밀번호(필요하면 random_enc)를 요구합니다. 고객사 내부 저장 형식(DER 파일 경로, PKCS#12, 암호화 blob, {cert_file,key_file,cert_password} JSON 등)은 자유입니다. 연결 함수를 부르기 직전에 bytes 로 풀어 같은 인증서 쌍을 넣으면 됩니다. 파일을 다시 올리는 화면은 필수가 아닙니다.

은행 번호와 비밀번호는 앞의 0 이 사라지지 않도록 문자열로 처리합니다. 계좌번호의 하이픈과 공백은 서버 규격에 따라 정규화됩니다. 복합 입력(계좌 비밀번호, 본인확인 번호, version)을 비밀번호 문자열 하나로 대신하지 마세요. SDK 의 encode_login_secret(.NET 은 EncodeLoginSecret)이 version 1 을 붙여 JSON 을 만들고, 실행 예제는 항목을 따로 입력받아 공개 스키마대로 구성합니다. 세부 필수값과 형식은 connect.py catalog 가 보여 주는 기관 목록의 input_contract.secret_schema 에서 확인합니다.

국민연금공단 EDI의 사업장관리번호와 근로복지공단, 고용24의 사업자등록번호는 인증서 등록 필드가 아니라 로그인 작업의 params 입니다(위 표의 로그인 작업에 함께 넘기는 값). 고용24에서는 일반사업자면 member_type_code=BE904, 사무대행기관이면 BE902 를 쓰고, 후자는 isoa_no 와 business_management_no 를 기관 계정에 맞춰 준비합니다. 신한은행 간편조회 거래내역에는 로그인 연결 외에 별도로 만든 계좌 자격증명의 bank_account_credential_id 가 필요합니다. 다른 은행도 연결 응답에 계좌 ID 가 있으면 고객, 기관, 환경과 함께 저장합니다.

멀티계정 키는 기관을 명시해 연결합니다. 한 기관의 account_link_id 를 다른 기관에 재사용하거나 콘솔의 자동 다기관 등록과 섞어 쓰지 마세요. 자료 조회와 신고에는 로그인 params 외에 조회 기간, 대상, 상품 권한이 필요할 수 있습니다. 위 표의 로그인 입력을 모든 상품의 입력 규격으로 쓰지 말고 해당 상품 API 의 provider, action, params, 응답을 확인하세요.