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

지방세 조회 - 위택스

1. 지방세 고지 및 미납 내역 조회wetax.tax.local.due.query

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호출할 기관입니다.
  • wetax이 API 고정값 (기본값)

예시 : wetax

actionstring-Y호출할 작업입니다.
  • wetax.tax.local.due.query이 API 고정값 (기본값)

예시 : wetax.tax.local.due.query

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
province_codestring-N조회할 시도 코드입니다
municipality_codestring-N조회할 시군구 코드입니다
page_nonumber-N조회할 페이지 번호입니다. 첫 페이지는 1입니다

예시 : 1

tax_codesarray-N조회할 세목 코드 목록입니다. 비우면 전체 세목입니다
assessment_type_codesarray-N기관 과세구분 코드입니다. 기본값은 실제 조회 화면의 전체 선택(1, 2, 3)입니다
start_monthstring6Y조회 시작 연월입니다. YYYYMM 형식입니다

형식 : YYYYMM

end_monthstring6Y조회 종료 연월입니다. YYYYMM 형식입니다

형식 : YYYYMM

arrears_onlyboolean-N체납 항목만 조회할지 여부입니다
include_automatic_paymentboolean-N자동납부 대상 포함 여부입니다
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: demo-query-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "wetax",
  "action": "wetax.tax.local.due.query",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "page_no": 1,
    "start_month": "<필수>",
    "end_month": "<필수>"
  }
}'

Response

  • 표의 칸 이름은 result.data 안의 경로입니다.
순번변수명타입설명
successboolean요청한 조회가 끝났다는 표지입니다. 성공 응답에서는 항상 true 입니다. 위택스에서 조회 결과를 읽지 못한 경우는 이 응답이 아니라 실패로 옵니다.
providerstring기관 상품의 식별자입니다. 이 상품에서는 항상 wetax 입니다.
actionstring실행한 액션의 ID 입니다.
account_link_idstring이 작업에 쓴 연동 계정의 ID 입니다.
dataobject조회 결과를 담은 객체입니다. 이 조회에 쓴 조건과 위택스에서 읽은 내용이 들어 있습니다.
data.actionstring실행한 액션의 ID 입니다. 봉투의 action 과 같은 값입니다.
data.queryobject이번 조회에 실제로 쓴 조건입니다. 요청에 보낸 값에, 보내지 않은 칸의 기본값이 더해져 있고 account_link_id 는 담지 않습니다.
data.query.province_codestring이번 조회에 쓴 province_code 값입니다. 조회할 시도 코드입니다.
data.query.municipality_codestring이번 조회에 쓴 municipality_code 값입니다. 조회할 시군구 코드입니다.
data.query.page_nonumber이번 조회에 쓴 page_no 값입니다. 조회할 페이지 번호입니다. 첫 페이지는 1입니다.
data.query.tax_codesarray이번 조회에 쓴 tax_codes 값입니다. 조회할 세목 코드 목록입니다. 비우면 전체 세목입니다.
data.query.assessment_type_codesarray이번 조회에 쓴 assessment_type_codes 값입니다. 기관 과세구분 코드입니다. 기본값은 실제 조회 화면의 전체 선택(1, 2, 3)입니다.
data.query.start_monthstring이번 조회에 쓴 start_month 값입니다. 조회 시작 연월입니다. YYYYMM 형식입니다.
data.query.end_monthstring이번 조회에 쓴 end_month 값입니다. 조회 종료 연월입니다. YYYYMM 형식입니다.
data.query.arrears_onlyboolean이번 조회에 쓴 arrears_only 값입니다. 체납 항목만 조회할지 여부입니다.
data.query.include_automatic_paymentboolean이번 조회에 쓴 include_automatic_payment 값입니다. 자동납부 대상 포함 여부입니다.
data.itemsarray고지 및 미납 내역의 줄 목록입니다. 조건에 맞는 내역이 없으면 빈 배열입니다. 한 쪽에 10줄씩 받도록 요청하므로, 전체 건수(data.pagination.total_count)가 더 많으면 page_no 를 올려 다음 쪽을 받습니다.
data.items[].period_yyyymmstring | number | boolean | object | array | null과세 기간의 연월입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].tax_item_namestring | number | boolean | object | array | null세목의 이름입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].tax_class_namestring | number | boolean | object | array | null과세 구분의 이름입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].taxpayer_namestring | number | boolean | object | array | null납세자의 이름입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].amount_duenumber납부할 금액입니다. 원 단위 정수이고, 위택스가 값을 주지 않거나 정수로 읽을 수 없으면 조회가 실패로 끝납니다.
data.items[].payment_term_categorystring | number | boolean | object | array | null납부 기간 구분입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].payment_due_datestring | number | boolean | object | array | null납부 기한입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].overdue_payment_datestring | number | boolean | object | array | null기한 후 납부일입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].local_government_namestring | number | boolean | object | array | null지방자치단체의 이름입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].electronic_payment_numberstring | number | boolean | object | array | null전자납부번호입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].nonpayment_arrears_codestring | number | boolean | object | array | null미납 체납 구분 코드입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].auto_payment_targetstring | number | boolean | object | array | null자동납부 대상인지를 나타내는 값입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].partial_payment_in_progressstring | number | boolean | object | array | null부분 납부가 진행 중인지를 나타내는 값입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].automatic_settlement_datestring | number | boolean | object | array | null자동 정산일입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].tax_payment_numberstring | number | boolean | object | array | null납세번호입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].explanationstring | number | boolean | object | array | null설명 글입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].deduction_amountnumber | null공제 금액입니다. 원 단위 정수이고, 위택스 값이 비어 있으면 null 입니다.
data.items[].full_addressstring | number | boolean | object | array | null전체 주소입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].virtual_accountstring | number | boolean | object | array | null가상계좌입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].additional_tax_totalnumber | null가산세 합계 금액입니다. 원 단위 정수이고, 위택스 값이 비어 있으면 null 입니다.
data.items[].atm_deduction_tax_amountnumber | nullATM 공제 세액입니다. 원 단위 정수이고, 위택스 값이 비어 있으면 null 입니다.
data.has_databooleanitems 에 줄이 하나라도 있으면 true 이고, 없으면 false 입니다.
data.paginationobject페이지 정보입니다. 위택스가 알려 준 쪽 번호와 줄 수, 그리고 이 조회의 전체 건수와 그 출처를 담습니다.
data.pagination.page_nonumber | null위택스가 알려 준 쪽 번호입니다. 알려 주지 않으면 null 입니다.
data.pagination.row_countnumber | null위택스가 알려 준 한 쪽의 줄 수입니다. 알려 주지 않으면 null 입니다.
data.pagination.total_countnumber | null조건에 맞는 전체 건수입니다. 줄에 붙어 온 전체 건수가 있으면 그 첫 값을, 없으면 페이지 정보의 전체 건수를, 그것도 없으면 조회 조건 객체의 전체 건수를 씁니다. 어느 값을 썼는지는 source 가 알려 주고, 셋 다 없으면 null 입니다.
data.pagination.sourcestringtotal_count 를 어디서 읽었는지를 나타냅니다. row[0].totCnt 는 줄에 붙어 온 전체 건수, pagerVO.totalCount 는 페이지 정보의 전체 건수, embedded.totCnt 는 조회 조건 객체의 전체 건수입니다.
data.countsobject위택스 응답에 담겨 온 건수 칸을 그대로 모아 둔 객체입니다. 전체 건수를 어느 칸에서 읽었는지 확인할 때 씁니다.
data.counts.response_total_countnumber | null위택스 응답의 맨 바깥에 담겨 온 전체 건수입니다. 알려 주지 않으면 null 입니다.
data.counts.embedded_total_countnumber | null위택스가 되돌려 준 조회 조건 객체 안의 전체 건수입니다. 그 객체가 오지 않았거나 값이 없으면 null 입니다.
data.counts.pager_total_countnumber | null위택스 응답의 페이지 정보 안의 전체 건수입니다. 알려 주지 않으면 null 입니다.
data.counts.list_lengthnumber이 응답에 담긴 줄의 수입니다.
data.counts.row_total_countsarray줄마다 붙어 온 전체 건수 가운데 값이 있는 것만 줄 순서대로 모은 목록입니다.
data.counts.row_number_rangearray줄마다 붙어 온 순번의 가장 작은 값과 가장 큰 값을 이 순서로 담은 두 칸 목록입니다. 순번이 붙은 줄이 없으면 빈 배열입니다.
json
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
  "success": "<boolean>",
  "provider": "<string>",
  "action": "<string>",
  "account_link_id": "<string>",
  "data": {
    "action": "<string>",
    "query": {
      "province_code": "<string>",
      "municipality_code": "<string>",
      "page_no": "<number>",
      "tax_codes": [],
      "assessment_type_codes": [],
      "start_month": "<string>",
      "end_month": "<string>",
      "arrears_only": "<boolean>",
      "include_automatic_payment": "<boolean>"
    },
    "items": [
      {
        "period_yyyymm": "<string | number | boolean | object | array | null>",
        "tax_item_name": "<string | number | boolean | object | array | null>",
        "tax_class_name": "<string | number | boolean | object | array | null>",
        "taxpayer_name": "<string | number | boolean | object | array | null>",
        "amount_due": "<number>",
        "payment_term_category": "<string | number | boolean | object | array | null>",
        "payment_due_date": "<string | number | boolean | object | array | null>",
        "overdue_payment_date": "<string | number | boolean | object | array | null>",
        "local_government_name": "<string | number | boolean | object | array | null>",
        "electronic_payment_number": "<string | number | boolean | object | array | null>",
        "nonpayment_arrears_code": "<string | number | boolean | object | array | null>",
        "auto_payment_target": "<string | number | boolean | object | array | null>",
        "partial_payment_in_progress": "<string | number | boolean | object | array | null>",
        "automatic_settlement_date": "<string | number | boolean | object | array | null>",
        "tax_payment_number": "<string | number | boolean | object | array | null>",
        "explanation": "<string | number | boolean | object | array | null>",
        "deduction_amount": "<number | null>",
        "full_address": "<string | number | boolean | object | array | null>",
        "virtual_account": "<string | number | boolean | object | array | null>",
        "additional_tax_total": "<number | null>",
        "atm_deduction_tax_amount": "<number | null>"
      }
    ],
    "has_data": "<boolean>",
    "pagination": {
      "page_no": "<number | null>",
      "row_count": "<number | null>",
      "total_count": "<number | null>",
      "source": "<string>"
    },
    "counts": {
      "response_total_count": "<number | null>",
      "embedded_total_count": "<number | null>",
      "pager_total_count": "<number | null>",
      "list_length": "<number>",
      "row_total_counts": [],
      "row_number_range": []
    }
  }
}

2. 지방세 납부내역 조회wetax.tax.local.payment.history.query

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호출할 기관입니다.
  • wetax이 API 고정값 (기본값)

예시 : wetax

actionstring-Y호출할 작업입니다.
  • wetax.tax.local.payment.history.query이 API 고정값 (기본값)

예시 : wetax.tax.local.payment.history.query

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
province_codestringN조회할 시도 코드입니다
municipality_codestringN조회할 시군구 코드입니다
page_nonumberN조회할 페이지 번호입니다. 첫 페이지는 1입니다

예시 : 1

tax_codesarrayN조회할 세목 코드 목록입니다. 비우면 전체 세목입니다
start_datestringY조회 시작일입니다
end_datestringY조회 종료일입니다
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: demo-query-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "wetax",
  "action": "wetax.tax.local.payment.history.query",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "page_no": 1,
    "start_date": "<필수>",
    "end_date": "<필수>"
  }
}'

Response

  • 표의 칸 이름은 result.data 안의 경로입니다.
순번변수명타입설명
successboolean요청한 조회가 끝났다는 표지입니다. 성공 응답에서는 항상 true 입니다. 위택스에서 조회 결과를 읽지 못한 경우는 이 응답이 아니라 실패로 옵니다.
providerstring기관 상품의 식별자입니다. 이 상품에서는 항상 wetax 입니다.
actionstring실행한 액션의 ID 입니다.
account_link_idstring이 작업에 쓴 연동 계정의 ID 입니다.
dataobject조회 결과를 담은 객체입니다. 이 조회에 쓴 조건과 위택스에서 읽은 내용이 들어 있습니다.
data.actionstring실행한 액션의 ID 입니다. 봉투의 action 과 같은 값입니다.
data.queryobject이번 조회에 실제로 쓴 조건입니다. 요청에 보낸 값에, 보내지 않은 칸의 기본값이 더해져 있고 account_link_id 는 담지 않습니다.
data.query.province_codestring이번 조회에 쓴 province_code 값입니다. 조회할 시도 코드입니다.
data.query.municipality_codestring이번 조회에 쓴 municipality_code 값입니다. 조회할 시군구 코드입니다.
data.query.page_nonumber이번 조회에 쓴 page_no 값입니다. 조회할 페이지 번호입니다. 첫 페이지는 1입니다.
data.query.tax_codesarray이번 조회에 쓴 tax_codes 값입니다. 조회할 세목 코드 목록입니다. 비우면 전체 세목입니다.
data.query.start_datestring이번 조회에 쓴 start_date 값입니다. 조회 시작일입니다. YYYY-MM-DD 꼴 문자열입니다.
data.query.end_datestring이번 조회에 쓴 end_date 값입니다. 조회 종료일입니다. YYYY-MM-DD 꼴 문자열입니다.
data.itemsarray납부 내역의 줄 목록입니다. 조건에 맞는 내역이 없으면 빈 배열입니다. 한 쪽에 10줄씩 받도록 요청하므로, 전체 건수(data.pagination.total_count)가 더 많으면 page_no 를 올려 다음 쪽을 받습니다.
data.items[].payment_datestring | null납부 일시입니다. 위택스가 알려 준 값 그대로이고, 실제 조회에서는 YYYY-MM-DD hh:mm:ss 꼴 문자열로 왔습니다. 알려 주지 않으면 null 입니다.
data.items[].tax_class_namestring | null과세 구분의 이름입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].tax_item_namestring | null세목의 이름입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].taxpayer_namestring | null납세자의 이름입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].payment_amountnumber납부 금액입니다. 원 단위 정수이고, 위택스가 값을 주지 않거나 정수로 읽을 수 없으면 조회가 실패로 끝납니다.
data.items[].total_amountnumber | null합계 금액입니다. 원 단위 정수이고, 위택스 값이 비어 있으면 null 입니다.
data.items[].local_government_namestring | null지방자치단체의 이름입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].electronic_payment_numberstring | null전자납부번호입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].representative_payment_nostring | null대표 전자납부번호입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].tax_period_yyyymmstring | null과세 기간의 연월입니다. 위택스가 알려 준 값 그대로이고, 실제 조회에서는 202609 처럼 연도 네 자리에 월 두 자리를 이은 여섯 자리 문자열로 왔습니다. 알려 주지 않으면 null 입니다.
data.items[].object_namestring | null과세 대상의 내용입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].auto_payment_targetstring | null자동납부 대상인지를 나타내는 값입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].explanationstring | null설명 글입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].vehicle_numberstring | number | boolean | object | array | null차량 번호입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].full_addressstring | null전체 주소입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.items[].tax_deposit_class_namestring | null지방세 입금 구분의 이름입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.has_databooleanitems 에 줄이 하나라도 있으면 true 이고, 없으면 false 입니다.
data.paginationobject페이지 정보입니다. 위택스가 알려 준 쪽 번호와 줄 수, 그리고 이 조회의 전체 건수와 그 출처를 담습니다.
data.pagination.page_nonumber | null위택스가 알려 준 쪽 번호입니다. 알려 주지 않으면 null 입니다.
data.pagination.row_countnumber | null위택스가 알려 준 한 쪽의 줄 수입니다. 알려 주지 않으면 null 입니다.
data.pagination.total_countnumber | null조건에 맞는 전체 건수입니다. 줄에 붙어 온 전체 건수가 있으면 그 첫 값을, 없으면 페이지 정보의 전체 건수를, 그것도 없으면 조회 조건 객체의 전체 건수를 씁니다. 어느 값을 썼는지는 source 가 알려 주고, 셋 다 없으면 null 입니다.
data.pagination.sourcestringtotal_count 를 어디서 읽었는지를 나타냅니다. row[0].totCnt 는 줄에 붙어 온 전체 건수, pagerVO.totalCount 는 페이지 정보의 전체 건수, embedded.totCnt 는 조회 조건 객체의 전체 건수입니다.
data.countsobject위택스 응답에 담겨 온 건수 칸을 그대로 모아 둔 객체입니다. 전체 건수를 어느 칸에서 읽었는지 확인할 때 씁니다.
data.counts.response_total_countnumber | null위택스 응답의 맨 바깥에 담겨 온 전체 건수입니다. 알려 주지 않으면 null 입니다.
data.counts.embedded_total_countnumber | null위택스가 되돌려 준 조회 조건 객체 안의 전체 건수입니다. 그 객체가 오지 않았거나 값이 없으면 null 입니다.
data.counts.pager_total_countnumber | null위택스 응답의 페이지 정보 안의 전체 건수입니다. 알려 주지 않으면 null 입니다.
data.counts.list_lengthnumber이 응답에 담긴 줄의 수입니다.
data.counts.row_total_countsarray줄마다 붙어 온 전체 건수 가운데 값이 있는 것만 줄 순서대로 모은 목록입니다.
data.counts.row_number_rangearray줄마다 붙어 온 순번의 가장 작은 값과 가장 큰 값을 이 순서로 담은 두 칸 목록입니다. 순번이 붙은 줄이 없으면 빈 배열입니다.
json
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
  "success": "<boolean>",
  "provider": "<string>",
  "action": "<string>",
  "account_link_id": "<string>",
  "data": {
    "action": "<string>",
    "query": {
      "province_code": "<string>",
      "municipality_code": "<string>",
      "page_no": "<number>",
      "tax_codes": [],
      "start_date": "<string>",
      "end_date": "<string>"
    },
    "items": [
      {
        "payment_date": "<string | null>",
        "tax_class_name": "<string | null>",
        "tax_item_name": "<string | null>",
        "taxpayer_name": "<string | null>",
        "payment_amount": "<number>",
        "total_amount": "<number | null>",
        "local_government_name": "<string | null>",
        "electronic_payment_number": "<string | null>",
        "representative_payment_no": "<string | null>",
        "tax_period_yyyymm": "<string | null>",
        "object_name": "<string | null>",
        "auto_payment_target": "<string | null>",
        "explanation": "<string | null>",
        "vehicle_number": "<string | number | boolean | object | array | null>",
        "full_address": "<string | null>",
        "tax_deposit_class_name": "<string | null>"
      }
    ],
    "has_data": "<boolean>",
    "pagination": {
      "page_no": "<number | null>",
      "row_count": "<number | null>",
      "total_count": "<number | null>",
      "source": "<string>"
    },
    "counts": {
      "response_total_count": "<number | null>",
      "embedded_total_count": "<number | null>",
      "pager_total_count": "<number | null>",
      "list_length": "<number>",
      "row_total_counts": [],
      "row_number_range": []
    }
  }
}

3. 지방세 환급 조회wetax.tax.local.refund.query

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호출할 기관입니다.
  • wetax이 API 고정값 (기본값)

예시 : wetax

actionstring-Y호출할 작업입니다.
  • wetax.tax.local.refund.query이 API 고정값 (기본값)

예시 : wetax.tax.local.refund.query

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
province_codestringN조회할 시도 코드입니다
municipality_codestringN조회할 시군구 코드입니다
page_nonumberN조회할 페이지 번호입니다. 첫 페이지는 1입니다

예시 : 1

start_datestringY환급 이력 조회 시작일입니다
end_datestringY환급 이력 조회 종료일입니다
refund_type_codestringN환급 유형 코드입니다
status_codestringN처리 상태 코드입니다
municipality_paid_onlybooleanN자치단체 지급건만 조회할지 여부입니다
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: demo-query-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "wetax",
  "action": "wetax.tax.local.refund.query",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "page_no": 1,
    "start_date": "<필수>",
    "end_date": "<필수>"
  }
}'

Response

  • 표의 칸 이름은 result.data 안의 경로입니다.
순번변수명타입설명
successboolean요청한 조회가 끝났다는 표지입니다. 성공 응답에서는 항상 true 입니다. 위택스에서 조회 결과를 읽지 못한 경우는 이 응답이 아니라 실패로 옵니다.
providerstring기관 상품의 식별자입니다. 이 상품에서는 항상 wetax 입니다.
actionstring실행한 액션의 ID 입니다.
account_link_idstring이 작업에 쓴 연동 계정의 ID 입니다.
dataobject조회 결과를 담은 객체입니다. 이 조회에 쓴 조건과 위택스에서 읽은 내용이 들어 있습니다.
data.actionstring실행한 액션의 ID 입니다. 봉투의 action 과 같은 값입니다.
data.queryobject이번 조회에 실제로 쓴 조건입니다. 요청에 보낸 값에, 보내지 않은 칸의 기본값이 더해져 있고 account_link_id 는 담지 않습니다.
data.query.province_codestring이번 조회에 쓴 province_code 값입니다. 조회할 시도 코드입니다.
data.query.municipality_codestring이번 조회에 쓴 municipality_code 값입니다. 조회할 시군구 코드입니다.
data.query.page_nonumber이번 조회에 쓴 page_no 값입니다. 조회할 페이지 번호입니다. 첫 페이지는 1입니다.
data.query.start_datestring이번 조회에 쓴 start_date 값입니다. 환급 이력 조회 시작일입니다. YYYY-MM-DD 꼴 문자열입니다.
data.query.end_datestring이번 조회에 쓴 end_date 값입니다. 환급 이력 조회 종료일입니다. YYYY-MM-DD 꼴 문자열입니다.
data.query.refund_type_codestring이번 조회에 쓴 refund_type_code 값입니다. 환급 유형 코드입니다.
data.query.status_codestring이번 조회에 쓴 status_code 값입니다. 처리 상태 코드입니다.
data.query.municipality_paid_onlyboolean이번 조회에 쓴 municipality_paid_only 값입니다. 자치단체 지급건만 조회할지 여부입니다.
data.quickobject환급 건수의 요약입니다. 요청의 조회 조건은 이 건수를 읽을 때 위택스에 보내지 않으므로, 이 건수에는 조회 조건이 적용되지 않습니다.
data.quick.local_tax_refund_countnumber지방세 환급 건수입니다. 0 이상의 정수이고, 위택스가 값을 주지 않거나 음수이거나 정수로 읽을 수 없으면 조회가 실패로 끝납니다.
data.quick.non_tax_revenue_refund_countnumber세외수입 환급 건수입니다. 0 이상의 정수이고, 위택스가 값을 주지 않거나 음수이거나 정수로 읽을 수 없으면 조회가 실패로 끝납니다.
data.quick.environmental_refund_countnumber환경 환급 건수입니다. 0 이상의 정수이고, 위택스가 값을 주지 않거나 음수이거나 정수로 읽을 수 없으면 조회가 실패로 끝납니다.
data.quick.total_refund_countnumber전체 환급 건수입니다. 0 이상의 정수이고, 위택스가 값을 주지 않거나 음수이거나 정수로 읽을 수 없으면 조회가 실패로 끝납니다.
data.historyobject환급 신청과 지급 이력의 조회 결과입니다. 줄 목록과 페이지 정보, 건수, 환급 유형 목록을 담습니다.
data.history.itemsarray환급 신청과 지급 이력의 줄 목록입니다. 조건에 맞는 이력이 없으면 빈 배열입니다. 한 쪽에 10줄씩 받도록 요청하므로, 전체 건수(data.history.pagination.total_count)가 더 많으면 page_no 를 올려 다음 쪽을 받습니다.
data.history.items[].row_numberstring | number | boolean | object | array | null줄 번호입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.history.items[].taxpayer_namestring | number | boolean | object | array | null납세자의 이름입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.history.items[].refund_application_datestring | number | boolean | object | array | null환급 신청일입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.history.items[].local_government_namestring | number | boolean | object | array | null지방자치단체의 이름입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.history.items[].refund_type_codestring | number | boolean | object | array | null환급 유형 코드입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.history.items[].tax_payment_numberstring | number | boolean | object | array | null납세번호입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.history.items[].refund_amountnumber환급 금액 합계입니다. 원 단위 정수이고, 위택스가 값을 주지 않거나 정수로 읽을 수 없으면 조회가 실패로 끝납니다.
data.history.items[].process_status_codestring | number | boolean | object | array | null처리 상태 코드입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.history.items[].process_status_namestring | number | boolean | object | array | null처리 상태의 이름입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.history.items[].tax_deposit_class_codestring | number | boolean | object | array | null지방세 입금 구분 코드입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.history.items[].certificate_idstring | number | boolean | object | array | null환급 건에 붙은 식별값 가운데 하나입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.history.items[].application_idstring | number | boolean | object | array | null환급 신청의 식별값입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.history.items[].application_screen_nostring | number | boolean | object | array | null환급 신청 화면의 번호입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.history.items[].application_group_idstring | number | boolean | object | array | null환급 신청 묶음의 식별값입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.history.items[].local_government_codestring | number | boolean | object | array | null지방자치단체의 코드입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.history.has_databooleanitems 에 줄이 하나라도 있으면 true 이고, 없으면 false 입니다.
data.history.paginationobject페이지 정보입니다. 위택스가 알려 준 쪽 번호와 줄 수, 그리고 이 조회의 전체 건수와 그 출처를 담습니다.
data.history.pagination.page_nonumber | null위택스가 알려 준 쪽 번호입니다. 알려 주지 않으면 null 입니다.
data.history.pagination.row_countnumber | null위택스가 알려 준 한 쪽의 줄 수입니다. 알려 주지 않으면 null 입니다.
data.history.pagination.total_countnumber | null조건에 맞는 전체 건수입니다. 페이지 정보의 전체 건수가 있으면 그 값을, 없으면 조회 조건 객체의 전체 건수를 씁니다. 어느 값을 썼는지는 source 가 알려 주고, 둘 다 없으면 null 입니다.
data.history.pagination.sourcestringtotal_count 를 어디서 읽었는지를 나타냅니다. pagerVO.totalCount 는 페이지 정보의 전체 건수, embedded.totCnt 는 조회 조건 객체의 전체 건수입니다.
data.history.countsobject위택스 응답에 담겨 온 건수 칸을 그대로 모아 둔 객체입니다. 전체 건수를 어느 칸에서 읽었는지 확인할 때 씁니다.
data.history.counts.response_total_countnumber | null위택스 응답의 맨 바깥에 담겨 온 전체 건수입니다. 알려 주지 않으면 null 입니다.
data.history.counts.embedded_total_countnumber | null위택스가 되돌려 준 조회 조건 객체 안의 전체 건수입니다. 그 객체가 오지 않았거나 값이 없으면 null 입니다.
data.history.counts.pager_total_countnumber | null위택스 응답의 페이지 정보 안의 전체 건수입니다. 알려 주지 않으면 null 입니다.
data.history.counts.list_lengthnumber이 응답에 담긴 줄의 수입니다.
data.history.counts.row_total_countsarray줄마다 붙어 온 전체 건수 가운데 값이 있는 것만 줄 순서대로 모은 목록입니다.
data.history.counts.row_number_rangearray줄마다 붙어 온 순번의 가장 작은 값과 가장 큰 값을 이 순서로 담은 두 칸 목록입니다. 순번이 붙은 줄이 없으면 빈 배열입니다.
data.history.refund_typesarray환급 유형의 목록입니다. 위택스가 알려 준 환급 유형마다 코드와 이름이 한 줄씩 옵니다.
data.history.refund_types[].codestring | null환급 유형 코드입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
data.history.refund_types[].labelstring | null환급 유형의 이름입니다. 위택스가 알려 준 값 그대로이고, 알려 주지 않으면 null 입니다.
json
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
  "success": "<boolean>",
  "provider": "<string>",
  "action": "<string>",
  "account_link_id": "<string>",
  "data": {
    "action": "<string>",
    "query": {
      "province_code": "<string>",
      "municipality_code": "<string>",
      "page_no": "<number>",
      "start_date": "<string>",
      "end_date": "<string>",
      "refund_type_code": "<string>",
      "status_code": "<string>",
      "municipality_paid_only": "<boolean>"
    },
    "quick": {
      "local_tax_refund_count": "<number>",
      "non_tax_revenue_refund_count": "<number>",
      "environmental_refund_count": "<number>",
      "total_refund_count": "<number>"
    },
    "history": {
      "items": [
        {
          "row_number": "<string | number | boolean | object | array | null>",
          "taxpayer_name": "<string | number | boolean | object | array | null>",
          "refund_application_date": "<string | number | boolean | object | array | null>",
          "local_government_name": "<string | number | boolean | object | array | null>",
          "refund_type_code": "<string | number | boolean | object | array | null>",
          "tax_payment_number": "<string | number | boolean | object | array | null>",
          "refund_amount": "<number>",
          "process_status_code": "<string | number | boolean | object | array | null>",
          "process_status_name": "<string | number | boolean | object | array | null>",
          "tax_deposit_class_code": "<string | number | boolean | object | array | null>",
          "certificate_id": "<string | number | boolean | object | array | null>",
          "application_id": "<string | number | boolean | object | array | null>",
          "application_screen_no": "<string | number | boolean | object | array | null>",
          "application_group_id": "<string | number | boolean | object | array | null>",
          "local_government_code": "<string | number | boolean | object | array | null>"
        }
      ],
      "has_data": "<boolean>",
      "pagination": {
        "page_no": "<number | null>",
        "row_count": "<number | null>",
        "total_count": "<number | null>",
        "source": "<string>"
      },
      "counts": {
        "response_total_count": "<number | null>",
        "embedded_total_count": "<number | null>",
        "pager_total_count": "<number | null>",
        "list_length": "<number>",
        "row_total_counts": [],
        "row_number_range": []
      },
      "refund_types": [
        {
          "code": "<string | null>",
          "label": "<string | null>"
        }
      ]
    }
  }
}