개발자 문서
API 레퍼런스

현금영수증 - 홈택스

현금영수증을 발행하고 당일 발행 건을 수정하거나 취소합니다. 매출·매입 내역도 조회합니다.

이 쪽의 모든 작업에 해당

1. 현금영수증 매출 내역 조회hometax.cash_receipt.sales.search_history

MCP 도구 이름 hometax__cash_receipt__sales__search_history

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

현금영수증 매출 내역을 조회합니다.

  • 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • hometax이 API 고정값 (기본값)

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.cash_receipt.sales.search_history이 API 고정값 (기본값)

예시 : hometax.cash_receipt.sales.search_history

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
from_datestring8-10Y조회 시작일입니다. 별칭 inqr_dt_strt / trs_dt_rng_strt

형식 : YYYY-MM-DD 또는 YYYYMMDD

to_datestring8-10Y조회 종료일입니다. 별칭 inqr_dt_end / trs_dt_rng_end

형식 : YYYY-MM-DD 또는 YYYYMMDD

fetch_all_pagesboolean-Ntrue 면 한 쪽이 아니라 모든 쪽을 모읍니다(기본 false). 쪽마다 기관 요청이 따로 나가 더 느립니다
max_pagesnumber-Nfetch_all_pages 가 true 일 때만 씁니다. 전체 수집에서 읽을 최대 쪽 수입니다(기본 100). 이 쪽 수를 다 읽고도 남은 행이 있으면 부분 결과 없이 입력 오류(VALIDATION_INVALID_FIELD)로 끝나니 조회 기간을 나누거나 값을 올려 다시 요청하세요

예시 : 100

page_numnumber-N페이지 번호 (기본: 1)

예시 : 1

page_sizenumber-N페이지당 조회건수 (기본: 10)

예시 : 10

pbl_cl_cdstring-N발행구분 (all=전체, 1=사업자, 2=국세청, 3=명세서, 기본: all)

예시 : all

trs_dt_rng_strtstring8N거래일자 범위 시작

형식 : YYYYMMDD

예시 : 20251030

trs_dt_rng_endstring8N거래일자 범위 종료

형식 : YYYYMMDD

예시 : 20251030

  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
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: search_history-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.cash_receipt.sales.search_history",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "from_date": "<필수>",
    "to_date": "<필수>",
    "max_pages": 100,
    "page_num": 1,
    "page_size": 10,
    "pbl_cl_cd": "all",
    "trs_dt_rng_strt": "20251030",
    "trs_dt_rng_end": "20251030"
  }
}'

Response

  • result.data 에 담긴 홈택스 응답 본문을 확인합니다.
  • result.data 에는 홈택스가 내려준 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
순번변수명타입설명
totalCountnumber건수. 이 응답에 담긴 행 수보다 작지 않습니다(기관이 준 값이 행 수보다 작으면 행 수를 씁니다)
pageInfoVOobject페이지 정보 객체(pageNum · pageSize · totalCount). totalCount 는 위와 같은 규칙으로 정합니다. 기관 원본은 문자열이지만 이 값은 정수입니다
collectionMetaobject수집 결과 객체 - complete(이 응답이 전부인지, false 면 다음 페이지를 더 받아야 함) · pagesFetched(받은 페이지 수) · collectedCount(이 응답에 담긴 행 수) · totalCount(위 totalCount 와 같은 값)
json
// result.data — 나머지 키는 홈택스 응답 본문입니다
{
  "cshTrsBrkdInqrDVOList": [ { "...": "..." } ],
  "totalCount": 1,
  "pageInfoVO": { "pageNum": 1, "pageSize": 10, "totalCount": 1 },
  "collectionMeta": { "complete": true, "pagesFetched": 1, "collectedCount": 1, "totalCount": 1 }
}
순번오류 코드발생 조건
VALIDATION_INVALID_FIELD요청 값 오류 — 필수 값이 빠지면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다.
VALIDATION_INVALID_FIELD쪽 수 상한 — fetch_all_pages 를 true 로 보내 모든 쪽을 모을 때 max_pages 만큼 쪽을 읽고도 남은 행이 있으면 부분 결과 없이 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. 조회 기간을 나누거나 max_pages 를 늘려 다시 요청합니다.
VALIDATION_INVALID_FIELD숫자 값 오류 — page_num, page_size, max_pages 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_UNAVAILABLE업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다.

2. 현금영수증 매출내역누계hometax.cash_receipt.sales.search_summary

MCP 도구 이름 hometax__cash_receipt__sales__search_summary

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

현금영수증 매출내역누계를 조회합니다.

  • 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • hometax이 API 고정값 (기본값)

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.cash_receipt.sales.search_summary이 API 고정값 (기본값)

예시 : hometax.cash_receipt.sales.search_summary

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
cmtt_yrstring4Y조회년도

형식 : YYYY

예시 : 2025

qrtstring-N분기 (all=연도별 전체, 1=1분기, 2=2분기, 3=3분기, 4=4분기, 기본: all)

예시 : all

bash
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: search_summary-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.cash_receipt.sales.search_summary",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "cmtt_yr": "2025",
    "qrt": "all"
  }
}'

Response

  • result.data 에 담긴 홈택스 응답 본문을 확인합니다.
  • result.data 에는 홈택스가 내려준 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.

이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.

json
// result.data — 홈택스 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
{}
순번오류 코드발생 조건
VALIDATION_INVALID_FIELD요청 값 오류 — 필수 값이 빠지면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_UNAVAILABLE업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다.

3. 현금영수증 매입 내역 조회hometax.cash_receipt.purchase.search_history

MCP 도구 이름 hometax__cash_receipt__purchase__search_history

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

현금영수증 매입 내역을 조회합니다.

  • 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • hometax이 API 고정값 (기본값)

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.cash_receipt.purchase.search_history이 API 고정값 (기본값)

예시 : hometax.cash_receipt.purchase.search_history

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
from_datestring8-10Y조회 시작일입니다. 별칭 inqr_dt_strt / trs_dt_rng_strt

형식 : YYYY-MM-DD 또는 YYYYMMDD

to_datestring8-10Y조회 종료일입니다. 별칭 inqr_dt_end / trs_dt_rng_end

형식 : YYYY-MM-DD 또는 YYYYMMDD

fetch_all_pagesboolean-Ntrue 면 한 쪽이 아니라 모든 쪽을 모읍니다(기본 false). 쪽마다 기관 요청이 따로 나가 더 느립니다
max_pagesnumber-Nfetch_all_pages 가 true 일 때만 씁니다. 전체 수집에서 읽을 최대 쪽 수입니다(기본 100). 이 쪽 수를 다 읽고도 남은 행이 있으면 부분 결과 없이 입력 오류(VALIDATION_INVALID_FIELD)로 끝나니 조회 기간을 나누거나 값을 올려 다시 요청하세요

예시 : 100

mrnt_txpr_dscm_nostring-N가맹점 사업자번호 (하이픈 제거, 최대 10자리)
page_numnumber-N페이지 번호 (기본: 1)

예시 : 1

page_sizenumber-N페이지당 조회건수 (기본: 10)

예시 : 10

pubc_user_nostring-N부서 사용자 번호 (all=전체, 기본: all)

예시 : all

spjb_trs_ynstring-N현금매출명세서 발행 여부 (all=전체, Y=현금매출명세서 발행만, 기본: all)

예시 : all

spst_cnfr_idstring-N신분확인수단 ID (all=전체, 기본: all)

예시 : all

trs_dt_rng_strtstring8N거래일자 범위 시작

형식 : YYYYMMDD

예시 : 20251030

trs_dt_rng_endstring8N거래일자 범위 종료

형식 : YYYYMMDD

예시 : 20251030

output_formatsarray-N이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
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: search_history-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.cash_receipt.purchase.search_history",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "from_date": "<필수>",
    "to_date": "<필수>",
    "max_pages": 100,
    "page_num": 1,
    "page_size": 10,
    "pubc_user_no": "all",
    "spjb_trs_yn": "all",
    "spst_cnfr_id": "all",
    "trs_dt_rng_strt": "20251030",
    "trs_dt_rng_end": "20251030"
  }
}'

Response

  • result.data 에 담긴 홈택스 응답 본문을 확인합니다.
  • result.data 에는 홈택스가 내려준 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
  • 아래 표의 cshTrsBrkdInqrDVOList[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 홈택스 화면의 표 머리글입니다.
  • 기관이 내려주는 행에는 아래 표에 없는 칸도 더 있습니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
totalCountnumber건수. 이 응답에 담긴 행 수보다 작지 않습니다(기관이 준 값이 행 수보다 작으면 행 수를 씁니다)
pageInfoVOobject페이지 정보 객체(pageNum · pageSize · totalCount). totalCount 는 위와 같은 규칙으로 정합니다. 기관 원본은 문자열이지만 이 값은 정수입니다
collectionMetaobject수집 결과 객체 - complete(이 응답이 전부인지, false 면 다음 페이지를 더 받아야 함) · pagesFetched(받은 페이지 수) · collectedCount(이 응답에 담긴 행 수) · totalCount(위 totalCount 와 같은 값)
cshTrsBrkdInqrDVOListstring | number | boolean | object | array | null조회한 행의 목록 배열입니다. 아래 줄이 그 행의 칸입니다
cshTrsBrkdInqrDVOList[].trsDtTimestring | number | boolean | object | array | null매입일시 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요.
cshTrsBrkdInqrDVOList[].cardOwnrNmstring | number | boolean | object | array | null사용자명 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요.
cshTrsBrkdInqrDVOList[].mrntTxprNmstring | number | boolean | object | array | null가맹점명 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요.
cshTrsBrkdInqrDVOList[].splCftstring | number | boolean | object | array | null공급가액 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요.
cshTrsBrkdInqrDVOList[].vaTxamtstring | number | boolean | object | array | null부가세 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요.
cshTrsBrkdInqrDVOList[].tipstring | number | boolean | object | array | null봉사료 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요.
cshTrsBrkdInqrDVOList[].totaTrsAmtstring | number | boolean | object | array | null매입금액 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요.
cshTrsBrkdInqrDVOList[].trsClNmstring | number | boolean | object | array | null거래구분 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요.
cshTrsBrkdInqrDVOList[].prhTxamtDdcClNmstring | number | boolean | object | array | null공제여부 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요.
json
// result.data — 나머지 키는 홈택스 응답 본문입니다
{
  "cshTrsBrkdInqrDVOList": [
    {
      "trsDtTime": "...",
      "cardOwnrNm": "...",
      "mrntTxprNm": "...",
      "splCft": "...",
      "vaTxamt": "...",
      "tip": "...",
      "totaTrsAmt": "...",
      "trsClNm": "...",
      "prhTxamtDdcClNm": "..."
    }
  ],
  "totalCount": 1,
  "pageInfoVO": {
    "pageNum": 1,
    "pageSize": 10,
    "totalCount": 1
  },
  "collectionMeta": {
    "complete": true,
    "pagesFetched": 1,
    "collectedCount": 1,
    "totalCount": 1
  }
}
순번오류 코드발생 조건
VALIDATION_INVALID_FIELD요청 값 오류 — 필수 값이 빠지면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다.
VALIDATION_INVALID_FIELD쪽 수 상한 — fetch_all_pages 를 true 로 보내 모든 쪽을 모을 때 max_pages 만큼 쪽을 읽고도 남은 행이 있으면 부분 결과 없이 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. 조회 기간을 나누거나 max_pages 를 늘려 다시 요청합니다.
VALIDATION_INVALID_FIELD숫자 값 오류 — page_num, page_size, max_pages 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_UNAVAILABLE업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다.

4. 현금영수증 발행hometax.cash_receipt.issue_individual

MCP 도구 이름 hometax__cash_receipt__issue_individual

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

현금영수증을 개별 발행합니다.

  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • hometax이 API 고정값 (기본값)

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.cash_receipt.issue_individual이 API 고정값 (기본값)

예시 : hometax.cash_receipt.issue_individual

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
cshptIsnMmoCntnstringN현금영수증 발급 메모 (최대 300바이트)
cshptTrsTypeCdstringY거래유형코드 (01=과세, 02=면세, 03=간이)
cshptUsgClCdstringY용도구분코드 (0=소득공제용, 1=지출증빙용)
spstCnfrClCdstringY발급수단구분코드 (01=주민등록번호, 02=사업자등록번호, 03=휴대전화번호, 04=카드번호)
spstCnfrNoEncCntnstringY발급수단번호 (주민번호, 사업자번호, 휴대폰번호, 카드번호 등)
tipstringN봉사료 (기본: 0)

예시 : 0

totaTrsAmtstringY총 거래금액 (최소 1원)
confirmation_tokenstringN1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
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: issue_individual-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.cash_receipt.issue_individual",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "cshptTrsTypeCd": "<필수>",
    "cshptUsgClCd": "<필수>",
    "spstCnfrClCd": "<필수>",
    "spstCnfrNoEncCntn": "<필수>",
    "tip": "0",
    "totaTrsAmt": "<필수>"
  }
}'

Response

  • 기관이 처리했음을 확인한 경우에만 성공합니다.
순번변수명타입설명
outcomestring기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다
actionstring요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
json
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "confirmed",
  "action": "hometax.cash_receipt.issue_individual"
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UPSTREAM_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UNAVAILABLE홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.

MCP 도구 이름 hometax__cash_receipt__daily_issue__search

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

당일발행을 조회합니다.

  • 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • hometax이 API 고정값 (기본값)

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.cash_receipt.daily_issue.search이 API 고정값 (기본값)

예시 : hometax.cash_receipt.daily_issue.search

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
page_numnumber-N페이지 번호 (기본: 1)

예시 : 1

page_sizenumber-N페이지당 조회건수 (기본: 10)

예시 : 10

trs_dtstring8N거래일자 (기본: 당일, 당일만 조회 가능)

형식 : YYYYMMDD

bash
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: search-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.cash_receipt.daily_issue.search",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "page_num": 1,
    "page_size": 10
  }
}'

Response

  • result.data 에 담긴 홈택스 응답 본문을 확인합니다.
  • result.data 에는 홈택스가 내려준 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
순번변수명타입설명
totalCountnumber건수. 이 응답에 담긴 행 수보다 작지 않습니다(기관이 준 값이 행 수보다 작으면 행 수를 씁니다)
pageInfoVOobject페이지 정보 객체(pageNum · pageSize · totalCount). totalCount 는 위와 같은 규칙으로 정합니다. 기관 원본은 문자열이지만 이 값은 정수입니다
collectionMetaobject수집 결과 객체 - complete(이 응답이 전부인지, false 면 다음 페이지를 더 받아야 함) · pagesFetched(받은 페이지 수) · collectedCount(이 응답에 담긴 행 수) · totalCount(위 totalCount 와 같은 값)
json
// result.data — 나머지 키는 홈택스 응답 본문입니다
{
  "cshptIsfIsnPubcDVOList": [ { "...": "..." } ],
  "totalCount": 1,
  "pageInfoVO": { "pageNum": 1, "pageSize": 10, "totalCount": 1 },
  "collectionMeta": { "complete": true, "pagesFetched": 1, "collectedCount": 1, "totalCount": 1 }
}
순번오류 코드발생 조건
VALIDATION_INVALID_FIELD숫자 값 오류 — page_num, page_size 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_UNAVAILABLE업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다.

6. 당일발행 수정hometax.cash_receipt.daily_issue.modify

MCP 도구 이름 hometax__cash_receipt__daily_issue__modify

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

당일발행 수정합니다. 응답을 받지 못해 다시 보낼 때는 같은 Idempotency-Key를 씁니다.

  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • hometax이 API 고정값 (기본값)

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.cash_receipt.daily_issue.modify이 API 고정값 (기본값)

예시 : hometax.cash_receipt.daily_issue.modify

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
aprv_nostring-Y승인번호 (필수)
cshpt_isn_mmo_cntnstring-N현금영수증 발급 메모 (선택, 최대 300바이트. 입력하지 않으면 오늘 발급 목록의 원본 메모를 유지합니다)
cshpt_trs_type_cdstring-N거래유형코드 (선택, 01=과세, 02=면세, 03=간이. 안 주면 원본에 부가세가 있을 때 과세로 본다. 원본으로 알 수 없으면 이 값을 요청한다)
cshpt_usg_cl_cdstring-N용도구분코드 (선택, 0=소득공제용, 1=지출증빙용. 안 주면 오늘 발급 목록의 원본 값)
rcpr_tinstring-N수취자 TIN (선택, 조회 결과에서 자동 설정)
spst_cnfr_cl_cdstring-N발급수단구분코드 (선택, 01=주민등록번호, 02=사업자등록번호, 03=휴대전화번호, 04=카드번호. 안 주면 오늘 발급 목록의 원본 값)
spst_cnfr_no_enc_cntnstring-N발급수단번호 (선택, 주민번호, 사업자번호, 휴대폰번호, 카드번호 등. 안 주면 오늘 발급 목록의 원본 값)
tipstring-N봉사료 (선택. 입력하지 않으면 오늘 발급 목록의 원본 값을 유지합니다. 봉사료를 없애려면 0 을 입력합니다)
tota_trs_amtstring-Y총 거래금액 (필수, 최소 1원)
trs_dtstring8N거래일자 (안 주면 원본의 거래일자. 오늘 발급분만 수정할 수 있다)

형식 : YYYYMMDD

trs_timestring-N거래시간 (HHMMSS 형식, 안 주면 원본의 거래시각)
confirmation_tokenstring-N1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
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: modify-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.cash_receipt.daily_issue.modify",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "aprv_no": "<필수>",
    "tota_trs_amt": "<필수>"
  }
}'

Response

  • 기관이 처리했음을 확인한 경우에만 성공합니다.
순번변수명타입설명
outcomestring기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다
actionstring요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
json
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "confirmed",
  "action": "hometax.cash_receipt.daily_issue.modify"
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UPSTREAM_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UNAVAILABLE홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.

7. 당일발행 취소hometax.cash_receipt.daily_issue.cancel

MCP 도구 이름 hometax__cash_receipt__daily_issue__cancel

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

당일발행 취소합니다. 응답을 받지 못해 다시 보낼 때는 같은 Idempotency-Key를 씁니다.

  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • hometax이 API 고정값 (기본값)

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.cash_receipt.daily_issue.cancel이 API 고정값 (기본값)

예시 : hometax.cash_receipt.daily_issue.cancel

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
aprv_nostring-Y승인번호 (필수)
cshpt_cncl_rsn_cdstring-Y취소사유코드 (필수, 1=거래취소, 2=오류발급, 3=기타)
cshpt_trs_type_cdstring-N거래유형코드 (선택, 조회 결과에서 가져옴, 01=과세, 02=면세, 03=간이)
cshpt_usg_cl_cdstring-N용도구분코드 (선택, 조회 결과에서 가져옴)
rcpr_tinstring-N수취자 TIN (선택, 조회 결과에서 가져옴)
spl_cftstring-N공급가액 (선택, 조회 결과에서 가져옴)
spst_cnfr_cl_cdstring-N발급수단구분코드 (선택, 조회 결과에서 가져옴)
spst_cnfr_no_enc_cntnstring-N발급수단번호 (선택, 조회 결과에서 가져옴)
tipstring-N봉사료 (선택, 조회 결과에서 가져옴)
tota_trs_amtstring-N총 거래금액 (선택, 조회 결과에서 가져옴)
trs_dtstring8N거래일자 (안 주면 원본의 거래일자. 오늘 발급분만 취소할 수 있다)

형식 : YYYYMMDD

trs_timestring-N거래시간 (HHMMSS 형식, 조회 결과에서 가져옴)
va_txamtstring-N부가세 (선택, 조회 결과에서 가져옴)
confirmation_tokenstring-N1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
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: cancel-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.cash_receipt.daily_issue.cancel",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "aprv_no": "<필수>",
    "cshpt_cncl_rsn_cd": "<필수>"
  }
}'

Response

  • 기관이 처리했음을 확인한 경우에만 성공합니다.
순번변수명타입설명
outcomestring기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다
actionstring요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
json
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "confirmed",
  "action": "hometax.cash_receipt.daily_issue.cancel"
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UPSTREAM_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UNAVAILABLE홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.