# 자동차세 계산 배기량과 차령으로 비영업용 승용자동차의 연간 자동차세와 지방교육세를 계산합니다. 차량을 등록하거나 보유 차량의 세금을 미리 확인할 때 씁니다. 인증: Authorization: Bearer $APICK_API_KEY 본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다. 인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다. ## POST /rest/vehicle_tax_calc 응답 필드 - `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다. - `data.result` (object): 조회 결과 본문입니다. 서비스가 찾은 실제 데이터가 들어 있으며, 자료가 없거나 조회에 실패하면 null이거나 필드가 생략됩니다. - `data.result.year` (integer): 과세연도입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.result.cc` (integer): 입력한 배기량입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.result.cc_rate` (integer): 적용한 1cc당 세액(원)입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.result.car_age_years` (integer): 계산에 쓴 차령(년)입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.result.discount_rate` (integer): 차령 경감률(%)입니다. 3년 미만은 0입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.result.vehicle_tax` (integer): 경감을 반영한 자동차세(원)입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.result.local_education_tax` (integer): 지방교육세(원)입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.result.total` (integer): 자동차세와 지방교육세의 합계(원)입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다. - `api.cost` (integer): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다. - `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다. - `api.ms` (integer): 서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다. ## API 요청: POST /rest/vehicle_tax_calc ### 입력 - `cc` (integer, 필수): 배기량(cc)입니다. 50~10000 사이 정수입니다. 쉼표는 무시합니다(예: 1,998). - `car_age_years` (integer, 선택): 차령(년)입니다. 0~40 사이 정수이며 생략하면 0으로 계산합니다. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다. - `year` (integer, 선택): 조회할 연도(4자리)입니다. 서비스별 지원 범위를 확인하세요. ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "result": { "type": "object", "properties": { "year": { "type": "integer", "description": "과세연도입니다." }, "cc": { "type": "integer", "description": "입력한 배기량입니다." }, "cc_rate": { "type": "integer", "description": "적용한 1cc당 세액(원)입니다." }, "car_age_years": { "type": "integer", "description": "계산에 쓴 차령(년)입니다." }, "discount_rate": { "type": "integer", "description": "차령 경감률(%)입니다. 3년 미만은 0입니다." }, "vehicle_tax": { "type": "integer", "description": "경감을 반영한 자동차세(원)입니다." }, "local_education_tax": { "type": "integer", "description": "지방교육세(원)입니다." }, "total": { "type": "integer", "description": "자동차세와 지방교육세의 합계(원)입니다." } } } } }, "api": { "type": "object", "properties": { "cost": { "type": "integer", "description": "차감된 포인트입니다. 실패하면 0 입니다." }, "success": { "type": "boolean" }, "ms": { "type": "integer" } } } } } ``` ### 정적 응답 예시 ```json { "data": { "result": { "year": 2026, "cc": 1998, "cc_rate": 200, "car_age_years": 5, "discount_rate": 15, "vehicle_tax": 339660, "local_education_tax": 101898, "total": 441558 } }, "api": { "cost": 60, "success": true, "ms": 12 } } ``` ### curl ```curl curl --fail-with-body --request POST 'https://apick.app/rest/vehicle_tax_calc' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'cc=1998' \ --form-string 'car_age_years=5' ``` ### Node.js (서버 ESM) ```javascript const form = new FormData(); form.append("cc", "1998"); form.append("car_age_years", "5"); const response = await fetch("https://apick.app/rest/vehicle_tax_calc", { method: "POST", headers: { Authorization: "Bearer " + process.env.APICK_API_KEY }, body: form, signal: AbortSignal.timeout(120_000), }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); const result = await response.json(); console.log(result); ``` ### python ```python import os import requests parts = [ ("cc", (None, "1998")), ("car_age_years", (None, "5")), ] response = requests.request("POST", "https://apick.app/rest/vehicle_tax_calc", headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, files=parts, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php '1998', 'car_age_years' => '5', ]; $curl = curl_init('https://apick.app/rest/vehicle_tax_calc'); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => $headers, CURLOPT_POSTFIELDS => $form, CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120, ]); $body = curl_exec($curl); if ($body === false) { throw new RuntimeException(curl_error($curl)); } $status = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); if ($status >= 400) { throw new RuntimeException($body); } $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR); print_r($result); ``` ## 사용 예시 1. 배기량과 차령으로 올해 자동차세 계산 보유 차량의 올해 자동차세를 미리 안내할 때 씁니다. `year`를 생략하면 올해 기준입니다. ```bash curl --fail-with-body --request POST 'https://apick.app/rest/vehicle_tax_calc' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'cc=1998' \ --form-string 'car_age_years=5' ``` - `data.result.total`이 자동차세와 지방교육세를 합친 연간 금액(원)입니다. - `data.result.discount_rate`로 차령 경감률(%)을 함께 보여 줄 수 있습니다. ## 사용 예시 2. 신차 경차의 과세연도 지정 계산 차령 0년 경차의 특정 과세연도 세액을 계산합니다. ```bash curl --fail-with-body --request POST 'https://apick.app/rest/vehicle_tax_calc' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'cc=998' \ --form-string 'car_age_years=0' \ --form-string 'year=2025' ``` - 1,000cc 이하라 `data.result.cc_rate`가 80입니다. - 차령 3년 미만이라 `data.result.discount_rate`가 0입니다. ## 사용 예시 3. 오래된 차량의 최대 경감 확인 차령 12년 이상 차량은 경감률이 50%로 고정됩니다. ```bash curl --fail-with-body --request POST 'https://apick.app/rest/vehicle_tax_calc' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'cc=2497' \ --form-string 'car_age_years=15' ``` - `data.result.discount_rate`가 50입니다. - `data.error_code`가 `INPUT_INVALID`이면 `cc` 50~10000, `car_age_years` 0~40 범위를 확인합니다. ## 코드·오류 ### 업무 실패 응답 입력 오류·대상 없음·일시 실패는 data.error(사유)와 data.success=0으로 오며 api.cost는 0(과금 없음)입니다. HTTP 상태는 400·404·408·424 중 하나입니다. 입력 오류는 값을 고쳐 다시 요청하고, 408·424는 잠시 후 한 번 다시 시도하세요. ```json { "data": { "error": "입력값을 확인해 주세요.", "success": 0 }, "api": { "success": true, "cost": 0, "ms": 5 } } ``` ## 상세 기능·요금 이용 전 확인 성공한 계산 한 건당 60P가 차감됩니다. 실제 차감액은 응답의 api.cost에서 확인하세요. 세율은 지방세법 제47조·제151조의 비영업용 승용자동차 기준입니다. 2020~2026년 과세연도에 같은 세율을 적용합니다. 연납 공제, 장애인·국가유공자 감면, 영업용 차량은 계산하지 않습니다. 입력값이 범위를 벗어나면 계산하지 않고 실패하며 과금되지 않습니다. 계산 기준 항목기준 1cc당 세액1,000cc 이하 80원 · 1,600cc 이하 140원 · 1,600cc 초과 200원 차령 경감차령 3년부터 5%, 이후 매년 5%p씩 늘어 12년 이상은 50% 지방교육세경감 후 자동차세의 30% 단수 처리자동차세·지방교육세 각각 원 미만 절사 예: 1,998cc·차령 5년이면 1,998 × 200 = 399,600원에서 15%를 경감해 자동차세 339,660원, 지방교육세 101,898원, 합계 441,558원입니다. ## 상세 요청 항목설정 메서드·주소POST https://apick.app/rest/vehicle_tax_calc 인증 헤더Authorization: Bearer — 내 계정의 API 인증키 본문 형식multipart/form-data 요청 예시 배기량 1,998cc, 차령 5년 차량의 연세액을 계산하는 예입니다. 성공 시 과금되는 실제 요청입니다. form-data 전체 예제 보기 ## 상세 응답 필드타입설명 data.result.yearinteger과세연도입니다. data.result.ccinteger입력한 배기량입니다. data.result.cc_rateinteger적용한 1cc당 세액(원)입니다. data.result.car_age_yearsinteger계산에 쓴 차령(년)입니다. data.result.discount_rateinteger차령 경감률(%)입니다. 3년 미만은 0입니다. data.result.vehicle_taxinteger경감을 반영한 자동차세(원)입니다. data.result.local_education_taxinteger지방교육세(원)입니다. data.result.totalinteger자동차세와 지방교육세의 합계(원)입니다. api.costinteger차감된 포인트입니다. 실패하면 0 입니다. { "data": { "result": { "year": 2026, "cc": 1998, "cc_rate": 200, "car_age_years": 5, "discount_rate": 15, "vehicle_tax": 339660, "local_education_tax": 101898, "total": 441558 } }, "api": { "cost": 60, "success": true, "ms": 12 } } 계산 결과는 입력값 기준의 추정 금액입니다. 실제 고지서는 감면·연납 신청에 따라 달라질 수 있습니다. ## 상세 코드·정책 오류 코드 실패하면 data.error(안내 문구)와 data.error_code가 오며 과금되지 않습니다. error_code의미대처 INPUT_REQUIREDcc를 보내지 않았습니다.배기량을 넣어 다시 요청합니다. INPUT_INVALID숫자가 아니거나 허용 범위를 벗어났습니다.cc 50~10000, car_age_years 0~40, year 2000~2026 범위의 정수로 보냅니다.