멀티계정 SDK 빠른 시작
키로 첫 요청을 확인한 뒤, 선택한 환경에 맞춰 고객 연결과 업무 실행을 진행합니다.
이 페이지에서 할 일
- 1~3단계(준비물, 설치, catalog): 키와 SDK가 동작하는지 Python 실습으로 확인합니다.
- 고객 연결과 업무 실행: 3단계가 성공하면 개발 규격의 고객 연결로 이동합니다.환경은 데모(real_test)와 정식(production)입니다.
연결 전 기관별 재료는 기관별 준비물에서 확인하세요.
- STEP 01키 준비
발급받은 멀티계정 키의 환경을 확인하고 SDK를 준비합니다.
- STEP 02고객 연결
고객별 기관 자격증명을 연결합니다.
- STEP 03연결 ID 저장
고객 ID와 account_link_id를 매핑합니다.
- STEP 04업무 실행
해당 고객의 연결 ID로 작업을 실행합니다.
한 회사의 키로 여러 고객 단위의 기관 계정을 연결합니다. 고객 단위(거래처, 회원, 사업장 등)는 고객사가 정합니다.
- 고객사 프로그램은 고객 단위마다 account_link_id를 저장하고, 업무마다 그 값을 지정합니다.
- 고객이 새로 받은 인증서를 다시 등록하면 같은 연결이 새 인증서로 바뀌기도(outcome UPDATED, 같은 account_link_id) 하고 새 연결이 생기기도(201, 새 account_link_id) 합니다.등록 응답의 account_link_id 로 그 고객 단위의 값을 덮어씁니다(다시 등록 규칙).
- 로그인, DB, 업무 화면, 자격증명 저장소는 고객사가 구현합니다. XBOSS는 연결 API, SDK, 키 설정 UI를 제공합니다.
아래 실습은 ZIP 예제로 키와 SDK 설치를 확인합니다. 특정 샘플 앱을 설치할 필요는 없습니다.
| 지금 할 일 | 읽을 안내 |
|---|---|
| 키와 SDK 설치 확인 | 이 페이지: Python + PowerShell 실습 (1~3단계) |
| 내 언어·프로그램에 코드 붙이기 | 개발 규격과 예제 — .NET·HTTP·키 UI·고객사 함수 |
| 연결 전 기관별 재료 확인 | 기관별 준비물 |
| 오류·응답 유실·키 교체 처리 | 오류와 운영 |
| 데모에서 홈택스 등 로그인 확인 | 개발 규격의 session.login 워크플로 — probe만으로 성공 안내 금지 |
| 사용자 화면에서 업무 실행과 진행 표시 | 개발 규격 7. UI 예시 — 거래처 연동, 업무 카드, 실행 내역 |
0.1.2 개발 검증본(미리보기)이라 정식 배포와 서명, 실제 키와 실제 기관 연결을 사용한 전체 연동 검증이 끝나지 않았습니다.
1. 준비물 확인
콘솔 멀티계정 연동에서 승인된 키를 준비하세요.
- 일반 키 관리에서 만든 키와 다릅니다. 이미 발급받았다면 다시 신청할 필요가 없습니다.
- 멀티계정 연동 화면의 발급 키와 키 관리의 환경을 확인하세요.
- API 계약에서는 이 전용 키 유형을 desktop_agent라고 부르지만 Python 서버에서도 사용할 수 있습니다.
| 준비물 | 확인 방법 |
|---|---|
| API 서버 주소 | 아래 코드에 기본 주소 https://api.xdata.kr가 들어 있습니다. 콘솔이나 고객사 프로그램 주소가 아닙니다. /v1을 덧붙이지 마세요. |
| client_id / client_secret | 사용하려는 환경이 허용된 멀티계정 키. secret은 승인할 때 한 번만 발급되고 콘솔에서는 다시 볼 수 없습니다. XBOSS 담당자에게 전달받아 안전하게 보관하고, 분실하면 재발급을 신청합니다. |
| 실습 환경 | Python 3.11 이상 + PowerShell. 명령 예시는 Windows 기준이며 다른 셸에 그대로 붙이지 않습니다. |
2. 다운로드하고 설치
- Python SDK와 예제 ZIP을 받으세요.
- ZIP을 파일 탐색기에서 우클릭하여 모두 압축 풀기를 선택하세요.
- 압축을 푼 폴더 중 README.md와 python 폴더가 함께 보이는 곳에 SDK(.whl) 파일을 복사하세요.
- 그 폴더를 연 파일 탐색기의 주소 표시줄에 powershell을 입력하고 Enter를 누르세요.
- 아래 명령을 이 위치에서 한 줄씩 실행하세요. 파일 이름의 밑줄(_) 앞에 역슬래시를 붙이지 않습니다.
키 설정 UI는 이 실습에 필요하지 않습니다. .NET, 웹 UI 선택은 개발 규격에 있습니다.
Get-Location
if (!(Test-Path './python/examples/connect.py')) { throw '예제 ZIP의 README.md와 python 폴더가 있는 위치에서 실행하세요.' }
if (!(Test-Path './xboss_multi_account-0.1.2-py3-none-any.whl')) { throw 'SDK 파일을 현재 폴더로 복사하세요.' }
python --version
# Python 3.11 이상인지 확인한 뒤 계속하세요.
python -m venv .venv
if ($LASTEXITCODE -ne 0) { throw 'Python 실행 또는 가상환경 생성 실패' }
./.venv/Scripts/python.exe -m pip install ./xboss_multi_account-0.1.2-py3-none-any.whl
if ($LASTEXITCODE -ne 0) { throw 'SDK 설치 실패. 아래 설치 오류 안내를 확인하세요.' }
./.venv/Scripts/python.exe -c "from xboss_multi_account import XbossClient; print('SDK 설치 확인 완료')"
./.venv/Scripts/python.exe ./python/examples/connect.py --helpcatalog, certificate, probe 등의 도움말이 나오면 설치 확인이 끝납니다.
pip 실패 시 다음 단계로 넘어가지 마세요.
- 파일 없음: Get-Location과 Test-Path로 위치를 확인하세요.
- python을 찾지 못함: Python 3.11 이상 설치와 PATH 설정을 확인하고 새 창을 여세요.
- 다운로드 오류: 네트워크와 회사 프록시 설정을 확인하세요.
- 권한 오류: 쓰기 가능한 개인 폴더에서 진행하세요.
- 설치 확인은 성공, import 실패: 같은 .venv/Scripts/python.exe를 사용했는지 확인하세요.
기존 프로그램에 붙일 때는 그 서버를 실행하는 Python 경로로 설치해야 합니다.
3. 키로 기관 목록 조회
다음 공통 설정은 같은 PowerShell 창에서 사용합니다. 새 창을 열었다면 이 설정부터 다시 실행하세요. secret은 각 명령의 숨김 입력으로 받으며 파일·명령문에 넣지 않습니다.
$python = './.venv/Scripts/python.exe'
$apiBase = 'https://api.xdata.kr'
$environment = Read-Host '발급받은 환경 입력: real_test / production'
if ($environment -notin @('real_test', 'production')) { throw '환경 이름을 확인하세요.' }
$clientId = Read-Host '발급받은 client_id'
$connectionArgs = @(
'--base-url', $apiBase,
'--env', $environment,
'--client-id', $clientId
)
& $python ./python/examples/connect.py catalog @connectionArgs성공 확인: 기관마다 provider 코드와 input_contract가 담긴 JSON이 들여쓴 형태로 차례로 출력됩니다.예를 들어 nhis_edi 항목에서 등록에 필요한 입력을 확인할 수 있습니다.
목록 조회 성공은 고객 등록, 상품 권한, 기관 로그인 성공과는 다릅니다.
목록이 없거나 오류이면 오류 안내를 확인하세요.
환경은 데모가 real_test, 정식이 production입니다. Secret 입력 시 글자나 별표가 표시되지 않아도 정상이니 입력하고 Enter를 누르세요.
다음 단계
연결하기 전에 사용할 기관의 재료를 기관별 준비물에서 확인합니다.
고객 연결과 업무 실행은 데모(real_test)와 정식(production)에서 실제 기관 자격증명으로 합니다.
4. 내 프로그램에 붙이기
3단계 catalog 확인 후 개발 규격과 예제로 이동하세요.
회사 키 설정, 고객 단위별 연결, account_link_id 매핑, 작업 실행 순서로 기존 서비스 코드에 연결합니다.
- catalog의 login_contract.action(예: hometax.session.login)으로 로그인 확인 작업을 실행해 연결을 검증하세요.
- 화면에서 작업을 다시 실행할 때는 새 업무마다 새 요청 키를 만듭니다.
- 네트워크 오류로 같은 업무를 재전송할 때는 같은 키와 같은 본문으로 그대로 요청해 주세요.같은 키에 다른 본문을 보내면 409 IDEMPOTENCY_KEY_CONFLICT입니다. 자세한 규칙은 재시도에 있습니다.
직원이 화면에서 자료 조회까지 실행하는 UI는 개발 규격 §7을 참고하세요.
이미 보관 중인 인증서, ID/PW 저장소를 쓰는지, Windows에서 XBOSS 연결 프로그램(코드의 이름은 PKI Agent)으로 스캔하는지는 고객사 선택입니다.
정확한 입력, VID, 오류 규칙은 개발 규격과 기관별 준비물에서 확인하세요.