# 하이패스 미납 여부 차량번호 하나로 고속도로 하이패스 미납통행료 대상 여부와 미납 건수를 확인합니다. 차량을 사고팔기 전이나 통행료를 납부하기 전에 미납이 있는지 빠르게 확인할 때 씁니다. 인증: Authorization: Bearer $APICK_API_KEY 본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다. 인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다. ## POST /rest/hipass_unpaid 응답 필드 - `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다. - `data.result` (object): 조회 결과 본문입니다. 서비스가 찾은 실제 데이터가 들어 있으며, 자료가 없거나 조회에 실패하면 null이거나 필드가 생략됩니다. - `data.result.car_no` (string): 조회한 차량번호입니다. 공백을 뺀 형태로 돌려줍니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. - `data.result.unpaid_target` (boolean): 미납통행료가 있으면 true 입니다. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. - `data.result.unpaid_count` (integer): 미납 건수입니다. 미납이 없으면 0 입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.result.checked_at` (string): 조회 시각(ISO 8601, UTC)입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. - `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/hipass_unpaid ### 입력 - `car_no` (string, 필수): 차량번호입니다. 예: 12가3456, 123가4567, 서울12가3456. 공백은 자동으로 제거합니다. 숫자 2~3자리 + 한글 1자 + 숫자 4자리 형식이어야 하며 앞에 지역명(한글 최대 2자)을 붙일 수 있습니다. ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "result": { "type": "object", "properties": { "car_no": { "type": "string", "description": "조회한 차량번호입니다. 공백을 뺀 형태로 돌려줍니다." }, "unpaid_target": { "type": "boolean", "description": "미납통행료가 있으면 true 입니다." }, "unpaid_count": { "type": "integer", "description": "미납 건수입니다. 미납이 없으면 0 입니다." }, "checked_at": { "type": "string", "description": "조회 시각(ISO 8601, UTC)입니다." } } } } }, "api": { "type": "object", "properties": { "cost": { "type": "integer", "description": "차감된 포인트입니다. 미납이 없거나 실패하면 0 입니다." }, "success": { "type": "boolean" }, "ms": { "type": "integer" } } } } } ``` ### 정적 응답 예시 ```json { "data": { "result": { "car_no": "12가3456", "unpaid_target": true, "unpaid_count": 2, "checked_at": "2026-10-20T00:30:00.000Z" } }, "api": { "cost": 60, "success": true, "ms": 900 } } ``` ### curl ```curl curl --fail-with-body --request POST 'https://apick.app/rest/hipass_unpaid' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'car_no=12가3456' ``` ### Node.js (서버 ESM) ```javascript const form = new FormData(); form.append("car_no", "12가3456"); const response = await fetch("https://apick.app/rest/hipass_unpaid", { 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 = [ ("car_no", (None, "12가3456")), ] response = requests.request("POST", "https://apick.app/rest/hipass_unpaid", headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, files=parts, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php '12가3456', ]; $curl = curl_init('https://apick.app/rest/hipass_unpaid'); 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. 차량번호로 미납 여부 확인 중고차 거래 전이나 통행료 납부 안내 전에 미납이 있는지 확인합니다. ```bash curl --fail-with-body --request POST 'https://apick.app/rest/hipass_unpaid' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'car_no=12가3456' ``` - `data.result.unpaid_target`이 true이면 미납이 있습니다. `data.result.unpaid_count`로 건수를 안내하세요. - 미납이 없으면 `unpaid_target`이 false, `api.cost`가 0입니다. ## 사용 예시 2. 지역명이 붙은 옛 번호판 확인 번호판에 지역명이 남아 있는 차량은 표기 그대로 보냅니다. 공백은 넣어도 자동으로 지워집니다. ```bash curl --fail-with-body --request POST 'https://apick.app/rest/hipass_unpaid' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'car_no=서울12가3456' ``` - `data.error_code`가 `INPUT_INVALID`이면 번호판 표기를 다시 확인합니다. 영문·특수문자는 넣지 않습니다. - `data.error_code`가 `UPSTREAM_FAILED`이면 과금되지 않으니 잠시 후 같은 값으로 다시 요청합니다. ## 코드·오류 ### 업무 실패 응답 입력 오류·대상 없음·일시 실패는 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에서 확인하세요. 미납이 없으면 unpaid_target=false, 건수 0으로 응답하며 과금되지 않습니다. 차량번호 형식이 맞지 않거나 조회에 실패하면 과금되지 않습니다. 이 API는 미납 여부와 건수만 제공합니다. 통행일시·구간·금액 같은 미납 내역은 제공하지 않습니다. ## 상세 요청 항목설정 메서드·주소POST https://apick.app/rest/hipass_unpaid 인증 헤더Authorization: Bearer — 내 계정의 API 인증키 본문 형식multipart/form-data 요청 예시 차량번호로 미납 여부를 확인하는 예입니다. 미납이 있으면 과금되는 실제 요청입니다. form-data 전체 예제 보기 ## 상세 응답 필드타입설명 data.result.car_nostring조회한 차량번호입니다. 공백을 뺀 형태로 돌려줍니다. data.result.unpaid_targetboolean미납통행료가 있으면 true 입니다. data.result.unpaid_countinteger미납 건수입니다. 미납이 없으면 0 입니다. data.result.checked_atstring조회 시각(ISO 8601, UTC)입니다. api.costinteger차감된 포인트입니다. 미납이 없거나 실패하면 0 입니다. { "data": { "result": { "car_no": "12가3456", "unpaid_target": true, "unpaid_count": 2, "checked_at": "2026-10-20T00:30:00.000Z" } }, "api": { "cost": 60, "success": true, "ms": 900 } } 등록되지 않은 차량번호도 형식만 맞으면 미납 없음(unpaid_target=false)으로 응답합니다. 차량 존재 여부를 확인하는 용도로는 쓰지 마세요. ## 상세 코드·정책 오류 코드 실패하면 data.error(안내 문구)와 data.error_code가 오며 과금되지 않습니다. error_code의미대처 INPUT_REQUIREDcar_no를 보내지 않았습니다.차량번호를 넣어 다시 요청합니다. INPUT_INVALID차량번호 형식이 맞지 않습니다.번호판 표기 그대로(예: 12가3456) 다시 보냅니다. 영문·특수문자는 넣지 않습니다. UPSTREAM_FAILED일시적으로 조회하지 못했습니다.잠시 후 같은 값으로 다시 요청합니다.