개발자 문서
개발자 문서

멀티계정 SDK 빠른 시작

키로 첫 요청을 확인한 뒤, 선택한 환경에 맞춰 고객 연결과 업무 실행을 진행합니다.

이 페이지에서 할 일

  • 1~3단계(준비물, 설치, catalog): 키와 SDK가 동작하는지 Python 실습으로 확인합니다.
  • 고객 연결과 업무 실행: 3단계가 성공하면 개발 규격의 고객 연결로 이동합니다.

연결 전 기관별 재료는 기관별 준비물에서 확인하세요.

  1. STEP 01
    키 준비

    발급받은 멀티계정 키의 환경을 확인하고 SDK를 준비합니다.

  2. STEP 02
    고객 연결

    고객별 기관 자격증명을 연결합니다.

  3. STEP 03
    연결 ID 저장

    고객 ID와 account_link_id를 매핑합니다.

  4. STEP 04
    업무 실행

    해당 고객의 연결 ID로 작업을 실행합니다.

승인된 키로 고객을 연결하고 연결 ID를 저장한 뒤 해당 고객의 업무를 실행합니다.

한 회사의 키로 여러 고객 단위의 기관 계정을 연결합니다. 고객 단위(거래처, 회원, 사업장 등)는 고객사가 정합니다.

  • 고객사 프로그램은 고객 단위마다 account_link_id를 저장하고, 업무마다 그 값을 지정합니다.
  • 고객이 새로 받은 인증서를 다시 등록하면 같은 연결이 새 인증서로 바뀌기도(outcome UPDATED, 같은 account_link_id) 하고 새 연결이 생기기도(201, 새 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 선택은 개발 규격에 있습니다.

powershell
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 --help

catalog, certificate, probe 등의 도움말이 나오면 설치 확인이 끝납니다.

pip 실패 시 다음 단계로 넘어가지 마세요.

  • 파일 없음: Get-Location과 Test-Path로 위치를 확인하세요.
  • python을 찾지 못함: Python 3.11 이상 설치와 PATH 설정을 확인하고 새 창을 여세요.
  • 다운로드 오류: 네트워크와 회사 프록시 설정을 확인하세요.
  • 권한 오류: 쓰기 가능한 개인 폴더에서 진행하세요.
  • 설치 확인은 성공, import 실패: 같은 .venv/Scripts/python.exe를 사용했는지 확인하세요.

기존 프로그램에 붙일 때는 그 서버를 실행하는 Python 경로로 설치해야 합니다.

3. 키로 기관 목록 조회

다음 공통 설정은 같은 PowerShell 창에서 사용합니다. 새 창을 열었다면 이 설정부터 다시 실행하세요. secret은 각 명령의 숨김 입력으로 받으며 파일·명령문에 넣지 않습니다.

powershell
$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이 들여쓴 형태로 차례로 출력됩니다.

목록 조회 성공은 고객 등록, 상품 권한, 기관 로그인 성공과는 다릅니다.

목록이 없거나 오류이면 오류 안내를 확인하세요.

환경은 데모가 real_test, 정식이 production입니다. Secret 입력 시 글자나 별표가 표시되지 않아도 정상이니 입력하고 Enter를 누르세요.

다음 단계

연결하기 전에 사용할 기관의 재료를 기관별 준비물에서 확인합니다.

고객 연결과 업무 실행은 데모(real_test)와 정식(production)에서 실제 기관 자격증명으로 합니다.

4. 내 프로그램에 붙이기

3단계 catalog 확인 후 개발 규격과 예제로 이동하세요.

회사 키 설정, 고객 단위별 연결, account_link_id 매핑, 작업 실행 순서로 기존 서비스 코드에 연결합니다.

  • catalog의 login_contract.action(예: hometax.session.login)으로 로그인 확인 작업을 실행해 연결을 검증하세요.
  • 화면에서 작업을 다시 실행할 때는 새 업무마다 새 요청 키를 만듭니다.
  • 네트워크 오류로 같은 업무를 재전송할 때는 같은 키와 같은 본문으로 그대로 요청해 주세요.

직원이 화면에서 자료 조회까지 실행하는 UI는 개발 규격 §7을 참고하세요.

이미 보관 중인 인증서, ID/PW 저장소를 쓰는지, Windows에서 XBOSS 연결 프로그램(코드의 이름은 PKI Agent)으로 스캔하는지는 고객사 선택입니다.

정확한 입력, VID, 오류 규칙은 개발 규격과 기관별 준비물에서 확인하세요.