세션 - 홈택스
홈택스 로그인 세션을 만들고 회원·사업자 기본 정보를 확인합니다. 다른 홈택스 API 를 부르기 전에 먼저 호출합니다.
1. 홈택스 로그인(세션 생성)hometax. session. login
MCP 도구 이름 hometax__
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
홈택스 로그인 후 세션을 만듭니다.
- 콘솔에서 발급한 API 키와 등록한 공동인증서가 필요합니다. 정식 환경은 라이트, 스탠다드, PRO 또는 멀티계정 요금제를 이용 중일 때만 호출할 수 있습니다.
- 사용할 인증서는 account_link_id 로 지정합니다. 로그인 유형(user)은 등록한 인증서로 정해지므로 보통 보내지 않습니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| user | string | N | 로그인 유형입니다. 01(법인) 또는 02(개인)만 받고 다른 값은 거절합니다. 실제 로그인 유형은 등록한 인증서로 정해지므로 보통 보내지 않습니다 |
curl --request POST \
--url 'https://api.xdata.kr/v1/jobs' \
--header 'Authorization: Basic {base64(client_id:client_secret)}' \
--header 'X-Env-Scope: real_test' \
--header "Idempotency-Key: login-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.session.login",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"user": "01"
}
}'Response
- result.data 의 success 와 session_registered 로 세션이 등록됐는지 확인합니다. cookies_count 로 확보한 쿠키 수를 알 수 있습니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| message | string | 결과 메시지 | |
| user_ | string | 사용자 유형(법인/개인) | |
| API_ | string | 이 호출에 쓴 연동 계정의 ID(account_link_id)입니다. XBOSS API 키가 아닙니다. | |
| account_ | string | 연동 ID | |
| session_ | boolean | 세션 등록 여부 | |
| cookies_ | number | 저장된 쿠키 수 |
// result.data
{
"success": true,
"message": "로그인 성공",
"user_type": "법인",
"API_KEY": "...",
"account_link_id": "...",
"session_registered": true,
"cookies_count": 5
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 연동 확인 — 로그인을 시작할 수 없는 경우입니다. 지정한 연동(account_link_id)을 쓸 수 없거나(없는 연동이거나, 이 계정 소유가 아니거나, 다른 서비스의 연동이거나, 비활성인 경우), 콘솔에 등록한 자격증명이 없거나 읽을 수 없거나 이 작업에 맞지 않거나, user 에 01 또는 02 가 아닌 값을 보낸 경우입니다. 같은 값으로는 다시 호출해도 결과가 같아 자동 재시도 대상이 아니니 error.message 안내대로 고칩니다. 연동은 콘솔에서 계정 ID 와 연동 상태를 확인하고, 자격증명은 콘솔에서 자격증명을 등록하거나 다시 등록하고, user 는 입력한 값을 다시 확인합니다. error.message 가 서비스 제공 상태 문제라고 알리면 다시 등록해도 풀리지 않으니 서비스문의로 알려 주세요. 제출할 때 이미 쓸 수 없는 연동이면 작업이 만들어지기 전에 제출이 거절됩니다. | |
| PROVIDER_ | 인증 정보 확인 — 등록된 인증서 정보를 찾지 못했거나 필수 값이 비어 있는 경우, 로그인은 끝났는데 쓸 수 있는 세션 쿠키를 받지 못한 경우, 등록된 인증서의 개인키를 열지 못한 경우, 또는 기관이 로그인을 거절한 경우입니다. 자동 재시도 대상이 아니니 error.message 안내대로 고칩니다. 개인키를 열지 못했다면 error.message 가 원인을 가릅니다. 인증서 비밀번호가 맞는지 확인하라는 안내면 비밀번호를 확인하고, 맞는데도 반복되면 콘솔에서 인증서를 다시 등록합니다. 인증서 형식을 열 수 없다는 안내면 비밀번호를 바꿔도 풀리지 않으니 다른 공동인증서로 다시 등록하거나 인증서를 재발급합니다. 기관이 로그인을 거절했다면 같은 인증서로 다시 호출해도 같은 거절이 되풀이되고 그때마다 기관에 요청이 나가니, 다시 호출하기 전에 연동한 인증서가 맞는지 확인합니다. 그 밖의 경우에도 연동한 인증 정보가 맞는지 확인하고 콘솔에서 다시 연결한 뒤 호출합니다. | |
| PROVIDER_ | 로그인 실패 — 로그인 실행이 끝까지 성공하지 못한 경우입니다. 로그인 실행이 오류로 끝났거나 로그인 실행 환경이 준비되지 않았을 때 옵니다(기관이 로그인을 거절한 경우는 위 인증 정보 확인 행입니다). 개인키를 열지 못했는데 그 원인을 가르지 못한 경우도 이 코드로 끝나며 error.message 는 그 원인을 말하지 않습니다. 재시도 가능으로 표시되지만 같은 인증서로 거듭 실패하면 인증서 비밀번호가 원인일 수 있어 다시 호출해도 풀리지 않으니, 콘솔에서 인증서 비밀번호를 확인해 인증서를 다시 등록한 뒤 호출합니다. 그렇지 않으면 error.message 안내대로 잠시 후 다시 호출하고, 계속되면 서비스문의로 알려 주세요. | |
| JOB_ | 시간 초과 — 로그인이 600초(10분) 안에 끝나지 않은 경우입니다. 재시도 가능으로 표시되니 error.message 안내대로 다시 호출합니다. | |
| INTERNAL_ | 세션 저장 실패 — 로그인은 끝났는데 서버가 세션을 저장하거나 되읽지 못한 경우입니다. 서버 쪽 문제라 연동을 다시 해도 풀리지 않으며, 예상하지 못한 오류도 같은 코드로 끝납니다. error.message 는 일반 안내('서버 내부 오류로 작업을 마치지 못했습니다. 서비스문의로 알려 주세요.')입니다. 자동 재시도 대상이 아니니 error.message 안내대로 서비스문의로 알려 주세요. | |
| POLICY_ | 개인사업자 — 로그인 뒤 사업자등록번호가 개인사업자 번호로 확인되면 방금 저장한 로그인 세션을 닫고 멈춥니다. error.message 는 「지금은 법인 사업자만 이용할 수 있습니다. 개인사업자는 서비스 안정화 뒤에 열 예정입니다.」 입니다. 재시도 불가로 표시되며, 다시 보내도 같은 답입니다. |
2. 국세청 회원 등록여부hometax. session. user_ info
MCP 도구 이름 hometax__
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
회원·사업자 기본 정보를 조회합니다.
- params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
curl --request POST \
--url 'https://api.xdata.kr/v1/jobs' \
--header 'Authorization: Basic {base64(client_id:client_secret)}' \
--header 'X-Env-Scope: real_test' \
--header "Idempotency-Key: user_info-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.session.user_info",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- result.data 의 success 값과 응답 칸을 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| data | object | 홈택스가 내려준 사용자 정보 객체 | |
| message | string | 결과 메시지 |
// 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_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |