개발자 문서
서비스 소개키 관리자격증명 등록OpenAPI콘솔
개발자 문서

멀티계정 SDK 빠른 시작

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

이 페이지에서 할 일

샌드박스(sandbox): 1~5단계까지 Python 실습으로 첫 연결·작업(Job)을 확인합니다. 데모(real_test)·정식(production): 1~3단계(준비물·설치·catalog) 성공 후 4~5단계는 건너뛰고 개발 규격의 고객 연결으로 이동합니다. 연결 전 기관별 재료는 기관별 준비물에서 확인하세요.

  1. STEP 01
    키 준비

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

  2. STEP 02
    고객 연결

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

  3. STEP 03
    연결 ID 저장

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

  4. STEP 04
    업무 실행

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

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

한 회사의 키로 여러 고객 단위(고객사가 정한 거래처·회원·사업장 등)의 기관 계정을 연결합니다. 고객사 프로그램은 고객 단위마다 account_link_id를 저장하고 업무마다 해당 값을 지정합니다. 고객 단위를 무엇으로 삼을지는 고객사가 정하며, 아래 예제에서는 customer-001처럼 고객사가 붙인 값을 씁니다. 로그인·DB·업무 화면·자격증명 저장소는 고객사가 구현하며, XBOSS는 연결 API·SDK·키 설정 UI를 제공합니다. 아래 실습은 ZIP 예제로 첫 호출을 확인하는 것이며, 특정 샘플 앱을 설치할 필요는 없습니다.

지금 할 일읽을 안내
처음 연결을 실행해 보기이 페이지: Python + PowerShell 실습 (샌드박스)
내 언어·프로그램에 코드 붙이기개발 규격과 예제 — .NET·HTTP·키 UI·고객사 함수
연결 전 기관별 재료 확인기관별 준비물
오류·응답 유실·키 교체 처리오류와 운영
데모에서 홈택스 등 로그인 확인개발 규격의 session.login 워크플로 — probe만으로 성공 안내 금지
사용자 화면에서 업무 실행과 진행 표시개발 규격 7. UI 예시 — 거래처 연동, 업무 카드, 실행 내역

0.1.2 개발 검증본(미리보기)입니다. 정식 배포·서명 및 실제 키와 테스트 자료를 사용한 전체 연동 검증은 완료되지 않았습니다. 현재 모든 고객이 내려받을 수 있는 샌드박스 인증서 자료는 없습니다. 승인된 테스트 자료가 없다면 샌드박스 실습은 3단계까지 가능합니다. 실제 인증서를 가짜 자료 대신 사용하지 마세요.

1. 준비물 확인

콘솔 멀티계정 연동에서 승인된 키를 준비하세요. 일반 키 관리에서 만든 키와 다릅니다. 이미 발급받았다면 다시 신청할 필요가 없습니다. 멀티계정 연동 화면의 발급 키와 키 관리의 환경을 확인하세요. API 계약에서는 이 전용 키 유형을 desktop_agent라고 부르지만 Python 서버에서도 사용할 수 있습니다. 키 발급 안내와 환경 안내를 참고하세요.

준비물확인 방법
API 서버 주소아래 코드에 기본 주소 https://api.xdata.kr가 들어 있습니다. 콘솔이나 고객사 프로그램 주소가 아닙니다. /v1을 덧붙이지 마세요.
client_id / client_secret사용하려는 환경이 허용된 멀티계정 키. secret은 승인할 때 한 번만 발급되고 콘솔에서는 다시 볼 수 없습니다. XBOSS 담당자에게 전달받아 안전하게 보관하고, 분실하면 재발급을 신청합니다.
승인된 테스트 인증서샌드박스에서만 필요한 가짜 signCert.der·signPri.key·비밀번호입니다. 공개 제공되지 않으므로 자료가 없으면 3단계까지만 진행합니다.
실습 환경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 './xdata_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 ./xdata_multi_account-0.1.2-py3-none-any.whl
if ($LASTEXITCODE -ne 0) { throw 'SDK 설치 실패. 아래 설치 오류 안내를 확인하세요.' }
./.venv/Scripts/python.exe -c "from xdata_multi_account import XDataClient; 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 '발급받은 환경 입력: sandbox / real_test / production'
if ($environment -notin @('sandbox', 'real_test', 'production')) { throw '환경 이름을 확인하세요.' }
$clientId = Read-Host '발급받은 client_id'
$customerId = 'customer-001'
$provider = 'nhis_edi'
$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를 누르세요. 목록이 없거나 오류이면 오류 안내를 확인하세요. 목록 조회 성공은 고객 등록·상품 권한·기관 로그인 성공과는 다릅니다.

환경별 다음 단계

샌드박스: 아래 4~5단계로 국민건강보험공단 EDI 모의 연결·작업을 진행합니다. 데모·정식: 3단계 성공 후 이 페이지의 4~5단계는 건너뛰고 개발 규격의 고객 연결으로 이동하세요. 사용할 기관의 재료는 기관별 준비물을 먼저 확인합니다. 환경 이름만 바꾸어 샌드박스 모의 실행을 실제 인증서로 실행하지 마세요.

4. 첫 고객 연결 (샌드박스 전용)

아래 단계는 샌드박스의 국민건강보험공단 EDI 모의 실행 전용입니다. 먼저 연결 요청 ID를 저장합니다. journal은 중단 시 같은 요청을 찾기 위한 파일이며 고객사 DB를 대신하지 않습니다. 기존 journal이 있으면 삭제하지 말고 등록 복구를 확인하세요.

powershell
if ($environment -ne 'sandbox') { throw '4~5단계는 샌드박스 전용입니다. real_test·production은 개발 규격으로 이동하세요.' }
$journal = './customer-001-operation.json'
$prepareArgs = @(
  'prepare', '--journal', $journal,
  '--base-url', $apiBase, '--env', $environment,
  '--customer', $customerId, '--provider', $provider
)
& $python ./python/examples/recover_connection.py @prepareArgs
if ($LASTEXITCODE -ne 0) { throw '요청 준비 실패. 기존 기록과 오류를 확인하세요.' }
$operationId = (Get-Content -Raw -Encoding UTF8 $journal |
  ConvertFrom-Json).operation_id
$certificatePath = Read-Host '승인된 가짜 signCert.der 경로'
$privateKeyPath = Read-Host '승인된 가짜 signPri.key 경로'
$certificateArgs = @(
  '--provider', $provider,
  '--certificate', $certificatePath,
  '--private-key', $privateKeyPath,
  '--operation-id', $operationId
)
& $python ./python/examples/connect.py certificate @connectionArgs @certificateArgs

성공 확인: account_link_id: 뒤에 연결 ID가 나옵니다. 이 값은 고객사 customer-001과 연결해서 저장할 값입니다. 다음 명령으로 현재 ACTIVE 상태를 확인하세요. ID/PW 기관은 별도 입력 예제를 사용합니다.

powershell
$accountLinkId = Read-Host '방금 반환된 account_link_id'
& $python ./python/examples/connect.py probe @connectionArgs --account-link-id $accountLinkId

probe가 오류 없이 같은 ID를 출력하면 ACTIVE 확인에 성공했습니다. 인증서 공개키 조회와 암호화는 SDK가 처리합니다. 자격증명 원문·개인키·비밀번호는 일반 로그나 고객사 업무 DB에 평문으로 남기지 마세요. 기존 고객사 자격증명 저장소에서 보호하여 읽는 방식은 사용할 수 있습니다.

5. 첫 작업 실행과 결과 확인 (샌드박스 전용)

ZIP의 first_job.py는 import, XDataClient 생성·종료, 업무 요청 키 생성·저장, 작업 제출, 제한된 상태 조회, 결과 수신을 포함한 실행 파일입니다. 별도의 client나 request_key 변수를 만들 필요가 없습니다. prepare에서 앞 단계와 같은 API 주소·키·고객 ID·연결 ID를 입력하세요.

powershell
$jobJournal = './customer-001-job.json'
$jobPrepare = @('prepare', '--journal', $jobJournal)
& $python ./python/examples/first_job.py @jobPrepare
if ($LASTEXITCODE -ne 0) { throw '작업 준비 실패. 기존 기록을 확인하세요.' }
if (Test-Path './customer-001-job-output.txt') { throw '기존 출력 기록을 덮어쓰지 않습니다. 아래 상태 조회 명령을 사용하세요.' }
& $python ./python/examples/first_job.py submit --journal $jobJournal | Tee-Object -FilePath './customer-001-job-output.txt'

성공 확인: job_id → status: SUCCEEDED → result_received: True 순으로 확인합니다. 이는 샌드박스 로그인 mock 결과를 수신했다는 의미이며, 실제 기관 자료 수집이나 고객사 DB 저장 완료가 아닙니다. 결과 원문은 출력하지 않습니다. 자신의 프로그램에서는 예제의 result 변수를 업무 저장 함수에 전달하세요.

받은 job_id는 customer-001-job.json에 자동 저장하고, 화면 출력은 customer-001-job-output.txt에 보관합니다. 이 기록에는 Secret과 결과 원문은 없지만 고객·작업 식별자가 있으므로 비공개 폴더에 보관하세요. 새 창에서는 실습 폴더로 이동하여 $python과 $jobJournal을 다시 지정하세요. 조회는 최대 20회, 간격 3초이며 각 HTTP 요청 제한은 별도입니다. 대기 중 종료되면 아래 명령이 저장된 job_id로 같은 작업만 조회합니다. 이 실습은 재제출을 막는 .submitted 파일도 남깁니다. 서버의 job_id 응답 자체를 받지 못했거나 ID 저장 전에 종료됐다면 모든 기록을 보관하고 운영 확인하세요. 마커를 삭제해 재제출하지 않습니다. 고객사 서비스의 재시도 구현은 운영 규격을 따릅니다.

powershell
$python = './.venv/Scripts/python.exe'
$jobJournal = './customer-001-job.json'
& $python ./python/examples/first_job.py status --journal $jobJournal

6. 내 프로그램에 붙이기

실습이 성공했거나 3단계 catalog 확인이 끝났다면 개발 규격과 예제로 이동하세요. 회사 키 설정 → 고객 단위별 연결 → account_link_id 매핑 → 작업 실행을 기존 서비스 코드에 연결합니다. 데모와 정식에서는 catalog의 login_contract.action(예: hometax.session.login)으로 로그인 확인 작업을 실행해 연결을 검증하고, 샌드박스의 nhis_edi mock 성공과 구분해 기록하세요. 직원이 화면에서 자료 조회까지 실행하는 UI는 개발 규격 §7을 참고하세요. 화면에서 작업을 다시 실행할 때는 새 업무마다 새 요청 키를 만듭니다. 네트워크 오류로 같은 업무를 재전송할 때는 같은 키와 같은 본문을 그대로 보내세요 — 같은 키에 다른 본문을 보내면 409 IDEMPOTENCY_KEY_CONFLICT입니다. 자세한 규칙은 재시도에 있습니다. 이미 보관 중인 인증서, ID/PW 저장소를 쓰는지, Windows에서 PKI Agent로 스캔하는지는 고객사 선택입니다. 정확한 입력, VID, 오류 규칙은 개발 규격과 기관별 준비물에서 확인하세요.