세션

홈택스 로그인 세션을 만들고 회원·사업자 기본 정보를 확인합니다. 다른 홈택스 API 를 부르기 전에 먼저 호출합니다.

MCP 도구 이름 hometax__session__login

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

홈택스 로그인 후 세션을 만듭니다.

콘솔에서 발급한 API 키와 등록한 공동인증서가 필요합니다. 정식 환경은 유료 플랜을 이용 중일 때만 호출할 수 있습니다.
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
로그인 유형은 user 로 지정하고, 사용할 인증서는 account_link_id 로 지정합니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `hometax`이 API 고정값 (기본값) 예시 : hometax
action	string	-	Y	호출할 작업입니다. `hometax.session.login`이 API 고정값 (기본값) 예시 : hometax.session.login
account_link_id	string	36	N	등록한 자격증명을 가리키는 아이디입니다. 이 API 는 자격증명 없이도 호출할 수 있습니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

순번	변수명	타입	필수	설명
	api_base_url	string	N	로그인 콜백에 사용할 API 기본 주소입니다. 지정하지 않으면 서버 기본값을 사용합니다
	user	string	N	로그인 유형입니다 예시 : 01

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-login-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.session.login",
  "params": {
    "user": "01"
  }
}'

Response

result.data 의 success 와 session_registered 로 세션이 등록됐는지 확인합니다. cookies_count 로 확보한 쿠키 수를 알 수 있습니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	message	결과 메시지
	user_type	사용자 유형(법인/개인)
	API_KEY	세션 API 키(account_link_id)
	account_link_id	연동 ID
	session_registered	세션 등록 여부
	cookies_count	저장된 쿠키 수

json

// result.data
{
  "success": true,
  "message": "로그인 성공",
  "user_type": "법인",
  "API_KEY": "...",
  "account_link_id": "...",
  "session_registered": true,
  "cookies_count": 5
}

순번	오류 코드	발생 조건
	PROVIDER_AUTH_FAILED	로그인 실패 — 등록된 인증서를 찾지 못했거나, 인증서 비밀번호가 맞지 않거나, 홈택스 접속에 실패했습니다.
	PROVIDER_UNAVAILABLE	로그인 실패 — 등록된 인증서를 찾지 못했거나, 인증서 비밀번호가 맞지 않거나, 홈택스 접속에 실패했습니다.

2. 국세청 회원 등록여부hometax.session.user_info

MCP 도구 이름 hometax__session__user_info

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

회원·사업자 기본 정보를 조회합니다.

조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `hometax`이 API 고정값 (기본값) 예시 : hometax
action	string	-	Y	호출할 작업입니다. `hometax.session.user_info`이 API 고정값 (기본값) 예시 : hometax.session.user_info
account_link_id	string	36	N	등록한 자격증명을 가리키는 아이디입니다. 이 API 는 자격증명 없이도 호출할 수 있습니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	N	작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

추가 파라미터가 없습니다. params 는 {} 로 보냅니다.

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-user_info-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.session.user_info",
  "params": {}
}'

Response

result.data 의 success 값과 목록·페이지 필드를 확인합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	data	홈택스가 내려준 사용자 정보 객체
	message	결과 메시지

json

// result.data
{
  "data": {
    "tin": "123456789012345678",
    "charId": "A123456",
    "userId": "user01",
    "userNm": "예시 주식회사",
    "rprsFnm": "홍길동",
    "rprsTin": "123456789012345678",
    "rprsResno": "000000*******",
    "pubcUserNo": "123456789012345678",
    "txprClsfCd": "02",
    "txprDscmNo": "1234567890",
    "userClsfCd": "03"
  },
  "message": "사용자 정보 조회 성공",
  "success": true
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
	PROVIDER_BUSINESS_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_VALIDATION_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_UNAVAILABLE	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

세션

1. 홈택스 로그인(세션 생성)hometax.session.login

Request

Response

2. 국세청 회원 등록여부hometax.session.user_info

Request

Response