멀티계정 개발 규격과 예제

$uiPackage = (Read-Host '다운로드한 tgz 전체 경로').Trim('"')
if (!(Test-Path './package.json')) { throw '고객사 프론트엔드 package.json 폴더에서 실행하세요.' }
if (!(Test-Path -LiteralPath $uiPackage -PathType Leaf)) { throw '다운로드한 파일 경로를 확인하세요.' }
npm install $uiPackage
if ($LASTEXITCODE -ne 0) { throw 'UI 패키지 설치 실패. 파일·네트워크·프로젝트 권한을 확인하세요.' }

import { mountXDataSettings, type SettingsHandler } from '@xdata/integration-settings-ui';

// 고객사 구현 함수를 인수로 받는 연결 함수입니다.
export function attachXDataSettings(
  container: HTMLElement,
  verify: SettingsHandler,
  save: SettingsHandler,
) {
  const widget = mountXDataSettings(container, { verify, save });
  return () => widget.destroy(); // 화면 해제 시 호출
}

// 고객사 로그인된 관리자 페이지에 <div id="xdata-settings"></div>를 두고 이 모듈을 불러옵니다.
import { mountXDataSettings } from '@xdata/integration-settings-ui';

// 아래 URL은 예시입니다. 고객사가 정한 경로로 verify/save API를 구현하세요. XBOSS API 주소가 아닙니다.
// 서버는 세션·관리자 권한·허용 출처를 검사하고 저장 시 키를 재검증해야 합니다.
// 응답 계약: 성공 시 {"ok":true}, 실패 시 적절한 HTTP 오류 또는 {"ok":false}.
async function sendSettings(url, settings, { signal }) {
  const response = await fetch(url, {
    method: 'POST',
    credentials: 'same-origin',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(settings),
    signal,
  });
  if (!response.ok) return { ok: false };
  const result = await response.json();
  return { ok: result.ok === true };
}
const widget = mountXDataSettings(document.getElementById('xdata-settings'), {
  verify: (settings, context) => sendSettings('/api/xdata/settings/verify', settings, context),
  save: (settings, context) => sendSettings('/api/xdata/settings/save', settings, context),
});
window.addEventListener('pagehide', () => widget.destroy(), { once: true });

dotnet add package XData.Settings.Windows --version 0.1.0 --source ./downloaded-packages
dotnet add package XData.MultiAccount --version 0.1.2 --source ./downloaded-packages

using XData.MultiAccount;
using XData.Settings.Windows;
// 기존 WinForms 설정 버튼 이벤트에서 호출합니다.
// storePath: 현재 사용자만 접근하는 파일의 절대 경로(상대 경로면 ArgumentException)
var store = new ProtectedKeyStore(storePath);
var revision = store.Read()?.Revision ?? 0;
async Task<bool> Verify(SettingsInput input, CancellationToken token) {
    await RequireCurrentAdministratorAsync(token); // 고객사의 관리자 권한 확인
    using var client = new XDataClient(new Uri(apiBase),
        input.Environment, input.ClientId, input.Secret);
    await client.GetProviderCatalogAsync(token);
    return true;
}
using var dialog = new SettingsDialog(Verify, async (input, token) => {
    await Verify(input, token);
    revision = store.Save(input, revision);
    return true;
});
dialog.ShowDialog();

./.venv/Scripts/python.exe -c "import sys; from xdata_multi_account import XDataClient; print(sys.executable); print('SDK 설치 확인 완료')"

from getpass import getpass
from xdata_multi_account import XDataClient, XDataError

try:
    with XDataClient(
        base_url="https://api.xdata.kr",
        env_scope=input("환경 (샌드박스 sandbox / 데모 real_test / 정식 production): ").strip(),
        client_id=input("Client ID: ").strip(),
        client_secret=getpass("Client secret: "),
    ) as client:
        providers = client.get_provider_catalog()
        print("catalog_received:", len(providers))
except XDataError as error:
    print(error.code, error.http_status, error.request_id, error.trace_id)
    raise SystemExit(2)

./.venv/Scripts/python.exe ./verify_key.py

dotnet restore ./dotnet-example --source ./downloaded-packages
dotnet run --project ./dotnet-example --no-restore -- help

$env:XDATA_API_BASE = 'https://api.xdata.kr'
$env:XDATA_ENV = Read-Host '환경: 샌드박스 sandbox / 데모 real_test / 정식 production'
$env:XDATA_CLIENT_ID = Read-Host 'Client ID'
$secureSecret = Read-Host 'Client Secret' -AsSecureString
try {
  $env:XDATA_CLIENT_SECRET = [System.Net.NetworkCredential]::new('', $secureSecret).Password
  dotnet run --project ./dotnet-example --no-restore -- catalog
} finally {
  Remove-Item Env:XDATA_CLIENT_SECRET
  $secureSecret.Dispose()
}

using XData.MultiAccount;

static async Task VerifyKeyAsync(
    string apiOrigin, string environment,
    string clientId, string clientSecret)
{
    using var client = new XDataClient(
        new Uri(apiOrigin), environment, clientId, clientSecret);
    await client.GetProviderCatalogAsync();
}

# 고객사 서버의 연결 함수. 인증서 평문을 HTTP 응답이나 로그로 반환하지 않습니다.
def connect_certificate(client, provider, operation_id,
                        certificate_bytes, private_key_bytes, password, random_enc=None):
    return client.link_certificate(
        provider=provider, operation_id=operation_id,
        certificate=certificate_bytes, private_key=private_key_bytes,
        password=password, random_enc=random_enc,
    )

from xdata_multi_account import encode_login_secret

def connect_login(client, provider_entry, operation_id, login_id, values):
    # password-text-v1: values는 비밀번호 문자열
    # canonical-json-v1: values는 secret_schema에 맞는 dict
    secret = encode_login_secret(provider_entry, values)
    return client.link_id_password(
        provider=provider_entry["provider"], operation_id=operation_id,
        login_id=login_id, login_password=secret,
    )

from xdata_multi_account import LocalPkiAgentClient

def list_windows_certificates():
    # 반환된 후보를 고객사 화면에 보여 주고 사용자가 하나를 고르게 합니다.
    with LocalPkiAgentClient() as agent:
        return [
            {"source": source, "candidates": agent.scan_source(source["source_id"])}
            for source in agent.list_sources()
        ]

def connect_selected_windows_certificate(
    client, provider, operation_id, candidate_id, certificate_password
):
    # operation_id는 호출 전에 고객·기관·환경과 함께 저장해야 합니다.
    with LocalPkiAgentClient() as agent:
        return client.link_certificate_from_pki_agent(
            provider=provider,
            pki_agent=agent,
            candidate_id=candidate_id,
            password=certificate_password,
            operation_id=operation_id,
        )

using XData.MultiAccount;

// 기존 화면에서 sources와 candidates를 보여주고 사용자가 하나를 선택합니다.
using var agent = new LocalPkiAgentClient();
var sources = await agent.ListSourcesAsync(cancellationToken);
var candidates = await agent.ScanSourceAsync(selectedSourceId, cancellationToken);

// operationId는 호출 전에 고객·기관·환경과 함께 저장해야 합니다.
var result = await client.LinkCertificateFromPkiAgentAsync(
    provider: selectedProvider,
    pkiAgent: agent,
    password: certificatePassword,
    operationId: operationId,
    candidateId: selectedCandidateId,
    cancellation: cancellationToken);

def session_login_summary(response, *, provider: str, action: str) -> dict:
    # response 는 get_job_result(job_id) 의 반환값입니다. GET /v1/jobs/{job_id} 의 상태 응답에는 result 가 없습니다.
    if response.get("status") != "SUCCEEDED":
        raise ValueError("성공한 Job 결과가 아닙니다.")
    # 상품별 result.data 형식은 API 계약을 따릅니다. 홈택스 로그인 확인은 success · message · user_type ·
    # account_link_id · session_registered · cookies_count 를 돌려주며 verified 칸은 없습니다.
    data = (response.get("result") or {}).get("data") or {}
    return {
        "kind": "session_login",
        "provider": provider,
        "action": action,
        "login_verified": data.get("success") is True,
        "session_registered": data.get("session_registered") is True,
    }

# 고객사 코드: summary = session_login_summary(client.get_job_result(job_id), provider="hometax", action="hometax.session.login")
# save_business_result(customer_id, request_reference, summary)

def business_fields(response, expected_business_number):
    if response.get('status') != 'SUCCEEDED':
        raise ValueError('성공한 Job 결과가 아닙니다.')
    result = response['result']
    if 'download_url' in result:
        raise ValueError('파일형 결과입니다. 결과 다운로드 계약으로 먼저 받아야 합니다.')
    business = result['data']['business']
    name = business['firm_name']
    number = business['business_registration_no']
    if not isinstance(name, str) or not name.strip() or not isinstance(number, str):
        raise ValueError('사업장 응답 형식을 확인하세요.')
    if number != expected_business_number:
        raise ValueError('이 customer_id에 기대한 사업자번호와 응답이 다릅니다.')
    return {'company_name': name, 'business_number': number}

# 고객사 코드에서: fields = business_fields(response, 해당_customer의_사업자번호)
# 기존 저장 함수에 customer_id, job_id, fields를 전달합니다.

┌─ 기관 연동 – 엑스보스 (427-87-03367) ──────────────────────┐
│ 체크: 키 저장 ✓, 자격증명 ✓, 연결 ✓, 로그인 확인 ○         │
│                                                          │
│ [ 홈택스 로그인 확인까지 실행 ]    ← 연결 검증 (session.login) │
│                                                          │
│ ── 업무 실행 ───────────────────────────────────────────  │
│ 업무 종류  [ 세금계산서 매출 조회 ▼ ]                       │
│ 조회 기간  [ 2026-01-01 ] ~ [ 2026-01-31 ]               │
│ 업무 이름  [ 홈택스-매출-2026-01-엑스보스-0921134502 ]       │
│            (비우면 실행 시각으로 자동 생성)                 │
│ [ 실행 ]   [ 실행 내역 보기 ]                                │
│                                                          │
│ 최근 실행                                                 │
│ • 세금계산서 매출 조회, 완료, 14건 반영                     │
│ • 홈택스 로그인 확인,   완료, 연결 검증됨                   │
└──────────────────────────────────────────────────────────┘

POST /api/customers/c476ce7e-baa5-46e2-879c-6543b6174c98/xdata/jobs
Content-Type: application/json
Cookie: session=…

{
  "connection_id": "bddd13da-0000-4000-8000-000000000001",
  "template_id": "hometax_sales_invoice",
  "params": {
    "from_date": "2026-01-01",
    "to_date": "2026-01-31"
  },
  "request_reference": "홈택스-매출-2026-01-엑스보스-0921134502"
}

POST /v1/jobs
Authorization: Basic …
X-Env-Scope: real_test
Idempotency-Key: {reserve_request가 저장한 request_key}

{
  "provider": "hometax",
  "action": "hometax.etax.invoice.search_list",
  "account_link_id": "{연결 등록 응답의 account_link_id(UUID)}",
  "params": {
    "from_date": "2026-01-01",
    "to_date": "2026-01-31",
    "prh_sls_cl_cd": "01",
    "page_num": 1,
    "page_size": 10
  }
}

┌─ 업무: 1월 부가세 자료 수집 ─────────────────────────────┐
│ 거래처: 엑스보스 (427-87-03367) – 담당: 김OO – [ 진행 중 ]   │
│                                                          │
│ 필요 자료                                                 │
│ ☑ 홈택스 매출 세금계산서 (2026-01)                        │
│ ☐ 홈택스 매입 세금계산서 (2026-01)                        │
│ ☐ 카드매출 요약                                           │
│                                                          │
│ [ 선택 항목 기관에서 가져오기 ]                             │
│                                                          │
│ 진행 로그                                                 │
│ 09:12 홈택스 매출 조회, 실행 중, job_01M2T…                │
│ 09:05 홈택스 로그인 확인, 완료                            │
└──────────────────────────────────────────────────────────┘

POST /api/tasks/task_01K2ABCDEF/xdata/run-selected
Content-Type: application/json

{
  "customer_id": "c476ce7e-baa5-46e2-879c-6543b6174c98",
  "items": [
    {
      "template_id": "hometax_sales_invoice",
      "params": { "from_date": "2026-01-01", "to_date": "2026-01-31" },
      "request_reference": "업무-부가세-홈택스매출-2026-01-엑스보스-0921150001"
    }
  ]
}

┌─ 홈택스 매출 세금계산서 조회 ────────────────────────────┐
│ ✓ 거래처 권한 확인                                        │
│ ✓ 요청 접수, job_01M2T1J3…                                │
│ ◐ 처리 중, 약 45% (추정), 인증 처리 중…                    │
│   다음 확인 2초 후 (retry_after_seconds)                  │
│ ○ 결과 반영                                               │
│                                                          │
│ [ 진행 상태 확인 ]     자동 갱신 (대기·처리 중일 때만)     │
│                                                          │
│ 이 창을 닫아도 고객사 서버에 job_id가 저장되어 있습니다.     │
│ 실행 내역이나 다음 로그인 때 이어서 조회할 수 있습니다.      │
└──────────────────────────────────────────────────────────┘

┌─ 홈택스 매출 세금계산서 조회 ────────────────────────────┐
│ ✓ 완료, 매출 세금계산서 14건, 거래처 메모에 반영됨          │
│ [ 결과 요약 보기 ]   [ 같은 기간 다시 실행 ]                  │
└──────────────────────────────────────────────────────────┘

┌─ XBOSS 실행 내역 – 엑스보스 ───────────────────────────────┐
│ 업무 이름                    상태   반영  시각              │
│ 홈택스-매출-2026-01-…        완료    ✓    오늘 09:14        │
│ 홈택스-로그인-확인-…         완료    ✓    오늘 09:05        │
│ 홈택스-매출-2026-01-…        실패    —    어제 (인증 불일치) │
│                                                          │
│ [ 상태 다시 확인 ]  [ 실패 건 재실행 ]  [ 상세(운영자) ]     │
└──────────────────────────────────────────────────────────┘