조회 - 교통민원24

이 쪽의 모든 작업에 해당

이 작업은 샌드박스를 지원하지 않습니다. 샌드박스로 보내면 거절되므로 데모나 정식 환경으로 호출합니다.

1. 교통민원24 기납과태료 조회efine.paid_penalty.query

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

데모입니다. 실제 기관에 접속하며 가입한 날부터 30일 동안 사용자 기준 하루 10 사용 토큰까지 호출할 수 있습니다(KST 0시 초기화).

이미 낸 과태료 목록을 조회합니다. 전체 기간으로 보거나 석 달 이내의 구간을 정할 수 있습니다. 납부와 문서 출력, 상세조회는 제공하지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 이 작업은 지원하지 않습니다 `real_test`데모 — 하루 10 사용 토큰 `production`정식 — 스탠다드, PRO 또는 멀티계정 요금제 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `efine`이 API 고정값 (기본값) 예시 : efine
action	string	-	Y	호출할 작업입니다. `efine.paid_penalty.query`이 API 고정값 (기본값) 예시 : efine.paid_penalty.query
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	길이	필수	설명
all_period	boolean	-	Y	전체 기간을 조회할지 정하는 값으로 true 나 false 를 보냅니다. true 이면 date_from 과 date_to 를 보내지 않아야 하고(보내면 거절), false 이면 석 달 이내의 기간으로 둘 다 보내야 합니다
date_from	string	10	N	조회 시작일입니다. all_period 가 false 일 때 필수이고 true 이면 보내지 않습니다. YYYY-MM-DD 형식으로 월과 일도 두 자리로 적어야 하고(연도는 1000 이상), date_to 보다 늦을 수 없으며 date_to 의 석 달 전 같은 날이나 그 뒤여야 합니다(석 달 전 달에 같은 날이 없으면 넘친 날수만큼 다음 달로 넘어간 날이 기준입니다) 형식 : YYYY-MM-DD
date_to	string	10	N	조회 종료일입니다. all_period 가 false 일 때 필수이고 true 이면 보내지 않습니다. YYYY-MM-DD 형식으로 월과 일도 두 자리로 적어야 하고(연도는 1000 이상) date_from 과 같거나 뒤여야 합니다 형식 : YYYY-MM-DD
vehicle_number	string	-	N	목록을 좁힐 차량번호입니다. 10자 이내로 보내고 공백만으로 된 값이나 제어 문자가 든 값은 거절하며, 쓰지 않으면 null 을 보내지 말고 칸을 뺍니다
page_size	number	-	N	한 쪽에 받을 줄 수입니다. 10, 30, 50, 100 중 하나를 정수로 보내며 보내지 않으면 10 입니다 예시 : 10
page_index	number	-	N	받을 쪽 번호입니다. 1부터 세는 정수이고 보내지 않으면 1 이며, 조회 결과의 마지막 쪽보다 크면 입력 오류로 거절합니다 예시 : 1
output_formats	array	-	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: demo-query-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "efine",
  "action": "efine.paid_penalty.query",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "all_period": "<필수: boolean>",
    "page_size": 10,
    "page_index": 1
  }
}'

Response

아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.

변수명	타입	설명
query	object	검증을 통과한 조회 조건입니다. 조회 조건 칸이 모두 돌아오며, 보내지 않은 칸은 기본값이고 기본값이 없으면 null 입니다.
total_count	number	기관 화면에 표시된 조회 결과의 전체 건수입니다.
returned_count	number	이 응답의 rows 에 담긴 행의 수입니다.
page_index	number	이 응답이 담은 쪽 번호입니다. 1부터 세고 요청한 page_index 와 같습니다.
page_size	number	한 쪽에 담는 행 수입니다. 요청한 page_size 와 같습니다.
has_more	boolean	다음 쪽이 있으면 true 입니다.
rows	array	기관 결과 표의 행 목록입니다. 결과가 없으면 빈 배열입니다. 칸 이름은 아래 rows[] 항목에 있고, 값은 기관 화면에 표시된 글자 그대로의 문자열입니다(줄바꿈과 겹친 공백은 공백 하나로 줄이고 앞뒤 공백은 지웁니다).
rows[].sequence	string	기관 결과 표의 「순위」 열입니다.
rows[].business_name	string	기관 결과 표의 「사업자명」 열입니다.
rows[].business_registration_no	string	기관 결과 표의 「사업자번호」 열입니다.
rows[].violation_datetime	string	기관 결과 표의 「위반일시」 열입니다.
rows[].violation_place	string	기관 결과 표의 「위반장소」 열입니다.
rows[].violator_name	string	기관 결과 표의 「위반자명」 열입니다.
rows[].vehicle_number	string	기관 결과 표의 「차량번호」 열입니다.
rows[].paid_date	string	기관 결과 표의 「납부일자」 열입니다.
rows[].paid_amount	string	기관 결과 표의 「납부금액」 열입니다.
rows[].paid_bank	string	기관 결과 표의 「납부은행명」 열입니다.
rows[].jurisdiction	string	기관 결과 표의 「관할관서」 열입니다.
rows[].department_contact	string	기관 결과 표의 「관서(담당부서)연락처」 열입니다.
rows[].penalty_number	string	기관 결과 표의 「과태료번호」 열입니다.

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "efine",
    "action": "efine.paid_penalty.query",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	저장된 기관 세션이 없습니다. 같은 연동 계정으로 efine.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다.
	PROVIDER_SESSION_EXPIRED	기관 세션이 만료됐습니다. 같은 연동 계정으로 efine.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다.
	VALIDATION_INVALID_FIELD	기납과태료 조회 조건이 올바르지 않거나 요청한 페이지가 조회 결과 범위를 벗어났습니다. 기간 조회는 3개월 이내로 입력해 주세요.
	PROVIDER_UPSTREAM_ERROR	기납과태료 조회 화면이 지원하는 형식과 달라 결과를 확인하지 못했습니다. 잠시 후 다시 시도해 주시고, 계속되면 서비스문의로 알려 주세요.
	PROVIDER_UPSTREAM_ERROR	페이지를 이동하는 사이 조회 조건이나 목록 크기가 유지되지 않아 결과를 반환하지 않았습니다. 첫 페이지부터 다시 조회해 주세요.

2. 교통민원24 기납범칙금 조회efine.paid_violation.query

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

데모입니다. 실제 기관에 접속하며 가입한 날부터 30일 동안 사용자 기준 하루 10 사용 토큰까지 호출할 수 있습니다(KST 0시 초기화).

이미 낸 범칙금 목록을 조회합니다. 기관이 표시한 건수와 페이지 결과를 받습니다. 납부와 문서 출력, 상세조회는 제공하지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 이 작업은 지원하지 않습니다 `real_test`데모 — 하루 10 사용 토큰 `production`정식 — 스탠다드, PRO 또는 멀티계정 요금제 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `efine`이 API 고정값 (기본값) 예시 : efine
action	string	-	Y	호출할 작업입니다. `efine.paid_violation.query`이 API 고정값 (기본값) 예시 : efine.paid_violation.query
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	필수	설명
page_size	number	N	한 쪽에 받을 줄 수입니다. 10, 30, 50, 100 중 하나를 정수로 보내며 보내지 않으면 10 입니다 예시 : 10
page_index	number	N	받을 쪽 번호입니다. 1부터 세는 정수이고 보내지 않으면 1 이며, 조회 결과의 마지막 쪽보다 크면 입력 오류로 거절합니다 예시 : 1
output_formats	array	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: demo-query-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "efine",
  "action": "efine.paid_violation.query",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "page_size": 10,
    "page_index": 1
  }
}'

Response

아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.

변수명	타입	설명
query	object	검증을 통과한 조회 조건입니다. 조회 조건 칸이 모두 돌아오며, 보내지 않은 칸은 기본값이고 기본값이 없으면 null 입니다.
total_count	number	기관 화면에 표시된 조회 결과의 전체 건수입니다.
returned_count	number	이 응답의 rows 에 담긴 행의 수입니다.
page_index	number	이 응답이 담은 쪽 번호입니다. 1부터 세고 요청한 page_index 와 같습니다.
page_size	number	한 쪽에 담는 행 수입니다. 요청한 page_size 와 같습니다.
has_more	boolean	다음 쪽이 있으면 true 입니다.
rows	array	기관 결과 표의 행 목록입니다. 결과가 없으면 빈 배열입니다. 칸 이름은 아래 rows[] 항목에 있고, 값은 기관 화면에 표시된 글자 그대로의 문자열입니다(줄바꿈과 겹친 공백은 공백 하나로 줄이고 앞뒤 공백은 지웁니다).
rows[].sequence	string	기관 결과 표의 「순위」 열입니다.
rows[].violation_datetime	string	기관 결과 표의 「위반일시」 열입니다.
rows[].violation_place	string	기관 결과 표의 「위반장소」 열입니다.
rows[].violator_name	string	기관 결과 표의 「위반자명」 열입니다.
rows[].vehicle_number	string	기관 결과 표의 「차량번호」 열입니다.
rows[].paid_date	string	기관 결과 표의 「납부일자」 열입니다.
rows[].paid_amount	string	기관 결과 표의 「납부금액」 열입니다.
rows[].paid_bank	string	기관 결과 표의 「납부은행명」 열입니다.
rows[].jurisdiction	string	기관 결과 표의 「관할관서」 열입니다.
rows[].department_contact	string	기관 결과 표의 「관서 (담당부서) 연락처」 열입니다.
rows[].violation_number	string	기관 결과 표의 「범칙금번호」 열입니다.

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "efine",
    "action": "efine.paid_violation.query",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	저장된 기관 세션이 없습니다. 같은 연동 계정으로 efine.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다.
	PROVIDER_SESSION_EXPIRED	기관 세션이 만료됐습니다. 같은 연동 계정으로 efine.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다.
	VALIDATION_INVALID_FIELD	기납범칙금 조회 조건이 올바르지 않거나 요청한 페이지가 조회 결과 범위를 벗어났습니다. 조회 조건과 페이지를 확인한 뒤 다시 조회해 주세요.
	PROVIDER_UPSTREAM_ERROR	기납범칙금 조회 화면이 지원하는 형식과 달라 결과를 확인하지 못했습니다. 잠시 후 다시 시도해 주시고, 계속되면 서비스문의로 알려 주세요.
	PROVIDER_UPSTREAM_ERROR	페이지를 이동하는 사이 목록 크기가 유지되지 않아 결과를 반환하지 않았습니다. 첫 페이지부터 다시 조회해 주세요.

3. 교통민원24 최근단속내역 조회efine.recent_enforcement.query

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

데모입니다. 실제 기관에 접속하며 가입한 날부터 30일 동안 사용자 기준 하루 10 사용 토큰까지 호출할 수 있습니다(KST 0시 초기화).

차량번호로 최근단속내역을 조회합니다. 기관이 돌려준 차량 필터와 페이지를 그대로 전달합니다. 조회 전용이라 납부나 이의신청, 엑셀 내보내기는 제공하지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 이 작업은 지원하지 않습니다 `real_test`데모 — 하루 10 사용 토큰 `production`정식 — 스탠다드, PRO 또는 멀티계정 요금제 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `efine`이 API 고정값 (기본값) 예시 : efine
action	string	-	Y	호출할 작업입니다. `efine.recent_enforcement.query`이 API 고정값 (기본값) 예시 : efine.recent_enforcement.query
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	필수	설명
vehicle_number	string	N	목록을 좁힐 차량번호입니다. 10자 이내로 보내고 공백만으로 된 값이나 제어 문자가 든 값은 거절하며, 쓰지 않으면 null 을 보내지 말고 칸을 뺍니다
page_size	number	N	한 쪽에 받을 줄 수입니다. 지금은 10 하나만 받으며 보내지 않으면 10 입니다 예시 : 10
page_index	number	N	받을 쪽 번호입니다. 1부터 세는 정수이고 보내지 않으면 1 이며, 조회 결과의 마지막 쪽보다 크면 입력 오류로 거절합니다 예시 : 1
output_formats	array	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: demo-query-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "efine",
  "action": "efine.recent_enforcement.query",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "page_size": 10,
    "page_index": 1
  }
}'

Response

아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.

변수명	타입	설명
query	object	검증을 통과한 조회 조건입니다. 값이 있는 칸만 돌아오며, 보내지 않은 칸은 기본값이 있는 것만 들어갑니다.
total_count	number	기관 화면에 표시된 조회 결과의 전체 건수입니다.
returned_count	number	이 응답의 rows 에 담긴 행의 수입니다.
page_index	number	이 응답이 담은 쪽 번호입니다. 1부터 세고 요청한 page_index 와 같습니다.
page_size	number	한 쪽에 담는 행 수입니다. 요청한 page_size 와 같습니다.
has_more	boolean	다음 쪽이 있으면 true 입니다.
rows	array	기관 결과 표의 행 목록입니다. 결과가 없으면 빈 배열입니다. 칸 이름은 아래 rows[] 항목에 있고, 값은 기관 화면에 표시된 글자 그대로의 문자열입니다(줄바꿈과 겹친 공백은 공백 하나로 줄이고 앞뒤 공백은 지웁니다).
rows[].row_no	string	기관 결과 표의 「순번」 열입니다.
rows[].violation_at	string	기관 결과 표의 「위반일시」 열입니다.
rows[].violation_place	string	기관 결과 표의 「위반장소」 열입니다.
rows[].vehicle_number	string	기관 결과 표의 「차량번호」 열입니다.
rows[].jurisdiction	string	기관 결과 표의 「관할관서」 열입니다.
rows[].office_contact	string	기관 결과 표의 「관서(담당부서)연락처」 열입니다.
rows[].notice_number	string	기관 결과 표의 「통지서번호」 열입니다.
rows[].violation_summary	string	기관 결과 표의 「위반내용」 열입니다.

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "efine",
    "action": "efine.recent_enforcement.query",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	저장된 기관 세션이 없습니다. 같은 연동 계정으로 efine.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다.
	PROVIDER_SESSION_EXPIRED	기관 세션이 만료됐습니다. 같은 연동 계정으로 efine.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다.
	VALIDATION_INVALID_FIELD	최근단속내역 조회 조건이 올바르지 않거나 요청한 페이지가 조회 결과 범위를 벗어났습니다. 조회 조건과 페이지를 확인한 뒤 다시 조회해 주세요.
	PROVIDER_UPSTREAM_ERROR	최근단속내역 조회 화면이 지원하는 형식과 달라 결과를 확인하지 못했습니다. 잠시 후 다시 시도해 주시고, 계속되면 서비스문의로 알려 주세요.
	PROVIDER_UPSTREAM_ERROR	요청한 페이지와 차량번호 조건이 유지됐는지 확인하지 못해 결과를 반환하지 않았습니다. 첫 페이지부터 다시 조회해 주세요.

4. 교통민원24 미납 과태료 조회efine.unpaid_penalty.query

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

데모입니다. 실제 기관에 접속하며 가입한 날부터 30일 동안 사용자 기준 하루 10 사용 토큰까지 호출할 수 있습니다(KST 0시 초기화).

미납 과태료를 조회합니다. 전체기간으로 보거나 납부기한 또는 위반일 기준으로 기간을 정할 수 있습니다. 기관이 만든 페이지 링크만 쓰며 납부는 제공하지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 이 작업은 지원하지 않습니다 `real_test`데모 — 하루 10 사용 토큰 `production`정식 — 스탠다드, PRO 또는 멀티계정 요금제 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `efine`이 API 고정값 (기본값) 예시 : efine
action	string	-	Y	호출할 작업입니다. `efine.unpaid_penalty.query`이 API 고정값 (기본값) 예시 : efine.unpaid_penalty.query
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	길이	필수	설명
all_period	boolean	-	Y	전체 기간을 조회할지 정하는 값으로 true 나 false 를 보냅니다. true 이면 date_from 과 date_to 를 보내지 않아야 하고(보내면 거절), false 이면 둘 다 보내야 합니다
date_basis	string	-	N	기간을 어느 날짜로 볼지 정합니다. payment_due - 납부기한 기준, violation - 위반일 기준이며 보내지 않으면 payment_due 입니다 예시 : payment_due
date_from	string	10	N	조회 시작일입니다. all_period 가 false 일 때 필수이고 true 이면 보내지 않습니다. YYYY-MM-DD 형식으로 월과 일도 두 자리로 적어야 하고(연도는 1000 이상), date_to 보다 늦을 수 없으며 계정에 따라 기관이 석 달 이내의 기간만 허용하면 그보다 긴 기간은 입력 오류로 거절합니다 형식 : YYYY-MM-DD
date_to	string	10	N	조회 종료일입니다. all_period 가 false 일 때 필수이고 true 이면 보내지 않습니다. YYYY-MM-DD 형식으로 월과 일도 두 자리로 적어야 하고(연도는 1000 이상) date_from 과 같거나 뒤여야 합니다 형식 : YYYY-MM-DD
vehicle_number	string	-	N	목록을 좁힐 차량번호입니다. 10자 이내로 보내고 공백만으로 된 값이나 제어 문자가 든 값은 거절하며, 쓰지 않으면 null 을 보내지 말고 칸을 뺍니다
page_size	number	-	N	한 쪽에 받을 줄 수입니다. 10, 30, 50, 100 중 하나를 정수로 보내며 보내지 않으면 10 입니다. 2쪽 이후를 받을 때는 10 이어야 합니다 예시 : 10
page_index	number	-	N	받을 쪽 번호입니다. 1부터 세는 정수이고 보내지 않으면 1 입니다. 2쪽 이후는 all_period 가 true 이고 vehicle_number 를 보내지 않으며 page_size 가 10 일 때만 받고, 마지막 쪽보다 크면 입력 오류로 거절합니다 예시 : 1
output_formats	array	-	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: demo-query-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "efine",
  "action": "efine.unpaid_penalty.query",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "all_period": "<필수: boolean>",
    "date_basis": "payment_due",
    "page_size": 10,
    "page_index": 1
  }
}'

Response

아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.

변수명	타입	설명
query	object	검증을 통과한 조회 조건입니다. 값이 있는 칸만 돌아오며, 보내지 않은 칸은 기본값이 있는 것만 들어갑니다.
institution_filter_echo	object	기관 화면의 조회 폼에 남아 있는 조건 값입니다. 값이 없는 칸은 빈 문자열입니다.
institution_filter_echo.vehicle_number	string	기관 화면의 차량번호 입력 칸 값입니다.
institution_filter_echo.date_from	string	기관 화면의 조회 시작일 입력 칸 값입니다.
institution_filter_echo.date_to	string	기관 화면의 조회 종료일 입력 칸 값입니다.
institution_filter_echo.date_basis	string	기관 화면의 기준 날짜 선택 칸 값입니다. 요청의 date_basis 는 payment_due 가 1, violation 이 2 로 바뀌어 기관에 전달됩니다.
total_count	number	기관 화면에 표시된 조회 결과의 전체 건수입니다.
returned_count	number	이 응답의 rows 에 담긴 행의 수입니다.
page_index	number	이 응답이 담은 쪽 번호입니다. 1부터 세고 요청한 page_index 와 같습니다.
page_size	number	한 쪽에 담는 행 수입니다. 요청한 page_size 와 같습니다.
has_more	boolean	다음 쪽이 있으면 true 입니다. 2쪽부터는 all_period 가 true 이고 vehicle_number 를 보내지 않고 page_size 가 10 일 때만 요청할 수 있습니다.
rows	array	기관 결과 표의 행 목록입니다. 결과가 없으면 빈 배열입니다. 칸 이름은 아래 rows[] 항목에 있고, 값은 기관 화면 칸의 글자를 공백 하나로 이어 붙인 문자열입니다(칸 안에서 글자가 나뉘어 있으면 그 사이에 공백이 들어갈 수 있습니다).
rows[].sequence	string	기관 결과 표의 「순번」 열입니다.
rows[].violation_datetime	string	기관 결과 표의 「위반일시」 열입니다.
rows[].violation_place	string	기관 결과 표의 「위반장소」 열입니다.
rows[].vehicle_number	string	기관 결과 표의 「차량번호」 열입니다.
rows[].virtual_account	string	기관 결과 표의 「가상계좌」 열입니다.
rows[].payment_due_date	string	기관 결과 표의 「납부기한」 열입니다.
rows[].payment_amount	string	기관 결과 표의 「납부금액」 열입니다.
rows[].responsible_office	string	기관 결과 표의 「관할관서」 열입니다.
rows[].office_contact	string	기관 결과 표의 「관서(담당부서)연락처」 열입니다.
rows[].penalty_number	string	기관 결과 표의 「과태료번호」 열입니다.

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "efine",
    "action": "efine.unpaid_penalty.query",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	저장된 기관 세션이 없습니다. 같은 연동 계정으로 efine.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다.
	PROVIDER_SESSION_EXPIRED	기관 세션이 만료됐습니다. 같은 연동 계정으로 efine.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다.
	VALIDATION_INVALID_FIELD	미납과태료 조회 조건이 올바르지 않습니다. 조건이 있는 조회는 첫 페이지만 지원합니다. 조건을 지우거나 첫 페이지로 다시 조회해 주세요.
	PROVIDER_UPSTREAM_ERROR	미납과태료 조회 화면이 지원하는 형식과 달라 결과를 확인하지 못했습니다. 잠시 후 다시 시도해 주시고, 계속되면 서비스문의로 알려 주세요.
	PROVIDER_UPSTREAM_ERROR	조회가 거절되었거나 조회할 법인 선택이 필요합니다. 교통민원24에서 법인을 선택한 뒤 다시 시도해 주세요.

5. 교통민원24 미납범칙금 조회efine.unpaid_violation.query

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

데모입니다. 실제 기관에 접속하며 가입한 날부터 30일 동안 사용자 기준 하루 10 사용 토큰까지 호출할 수 있습니다(KST 0시 초기화).

미납 범칙금 목록을 조회합니다. 페이지 크기와 번호로 나눠 받습니다. 납부와 엑셀 내보내기, 상세조회, 법인 선택은 제공하지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 이 작업은 지원하지 않습니다 `real_test`데모 — 하루 10 사용 토큰 `production`정식 — 스탠다드, PRO 또는 멀티계정 요금제 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `efine`이 API 고정값 (기본값) 예시 : efine
action	string	-	Y	호출할 작업입니다. `efine.unpaid_violation.query`이 API 고정값 (기본값) 예시 : efine.unpaid_violation.query
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	필수	설명
page_size	number	N	한 쪽에 받을 줄 수입니다. 10, 30, 50, 100 중 하나를 정수로 보내며 보내지 않으면 10 입니다. 2쪽 이후를 받을 때는 10 이어야 합니다 예시 : 10
page_index	number	N	받을 쪽 번호입니다. 1부터 세는 정수이고 보내지 않으면 1 입니다. 2쪽 이후는 page_size 가 10 일 때만 받고, 마지막 쪽보다 크면 입력 오류로 거절합니다 예시 : 1
output_formats	array	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: demo-query-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "efine",
  "action": "efine.unpaid_violation.query",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "page_size": 10,
    "page_index": 1
  }
}'

Response

아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.

변수명	타입	설명
query	object	검증을 통과한 조회 조건입니다. 조회 조건 칸이 모두 돌아오며, 보내지 않은 칸은 기본값이고 기본값이 없으면 null 입니다.
total_count	number	기관 화면에 표시된 조회 결과의 전체 건수입니다.
returned_count	number	이 응답의 rows 에 담긴 행의 수입니다.
page_index	number	이 응답이 담은 쪽 번호입니다. 1부터 세고 요청한 page_index 와 같습니다.
page_size	number	한 쪽에 담는 행 수입니다. 요청한 page_size 와 같습니다.
has_more	boolean	다음 쪽이 있으면 true 입니다. 2쪽부터는 page_size 가 10 일 때만 요청할 수 있습니다.
rows	array	기관 결과 표의 행 목록입니다. 결과가 없으면 빈 배열입니다. 칸 이름은 아래 rows[] 항목에 있고, 값은 기관 화면에 표시된 글자 그대로의 문자열입니다(줄바꿈과 겹친 공백은 공백 하나로 줄이고 앞뒤 공백은 지웁니다).
rows[].sequence	string	기관 결과 표의 「순번」 열입니다.
rows[].violation_datetime	string	기관 결과 표의 「위반일시」 열입니다.
rows[].violation_place	string	기관 결과 표의 「위반장소」 열입니다.
rows[].violation_legal_basis	string	기관 결과 표의 「위반법조항」 열입니다.
rows[].vehicle_number	string	기관 결과 표의 「차량번호」 열입니다.
rows[].virtual_account	string	기관 결과 표의 「가상계좌번호」 열입니다.
rows[].payment_due_date	string	기관 결과 표의 「납부기한」 열입니다.
rows[].payment_amount	string	기관 결과 표의 「범칙금」 열입니다.
rows[].violation_number	string	기관 결과 표의 「범칙금 번호」 열입니다.

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "efine",
    "action": "efine.unpaid_violation.query",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	저장된 기관 세션이 없습니다. 같은 연동 계정으로 efine.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다.
	PROVIDER_SESSION_EXPIRED	기관 세션이 만료됐습니다. 같은 연동 계정으로 efine.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다.
	VALIDATION_INVALID_FIELD	미납범칙금 조회 조건이 올바르지 않거나 요청한 페이지가 조회 결과 범위를 벗어났습니다. 첫 페이지 이후는 기본 페이지 크기로만 조회할 수 있습니다. 첫 페이지부터 다시 조회해 주세요.
	PROVIDER_UPSTREAM_ERROR	미납범칙금 조회 화면이 지원하는 형식과 달라 결과를 확인하지 못했습니다. 잠시 후 다시 시도해 주시고, 계속되면 서비스문의로 알려 주세요.
	PROVIDER_UPSTREAM_ERROR	조회할 법인 선택이 필요해 미납범칙금을 조회하지 않았습니다. 교통민원24에서 법인을 선택한 뒤 다시 시도해 주세요.