건설업 행정처분 - 공공데이터 기업 위험 조회
1. 국토교통부 건설업 행정처분 조회opendata. kiscon. sanction
MCP 도구 이름 opendata__
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
건설업체 공시 자료를 기간을 정해 훑고 사업자등록번호가 맞는 건을 골라냅니다.
- 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| provider | string | Y | 호출할 기관입니다.
| |
| action | string | Y | 호출할 작업입니다.
| |
| params | object | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| bizno | string | - | Y | 사업자등록번호 10자리. 조회 기간의 공시 가운데 이 번호의 업체 것만 돌려줍니다 | |
| sDate | string | 8 | Y | 공시 기간 시작일. 꼭 보내야 합니다 | |
| eDate | string | 8 | Y | 공시 기간 종료일. 꼭 보내야 합니다 | |
| corp_ | string | - | N | 업체명(선택) - 공시에 등록번호가 없는 업체는 이 이름으로 찾습니다 | |
| numOfRows | number | - | N | 기관 페이지당 행 수(기본 100, 최대 100) | |
| maxPages | number | - | N | 훑을 최대 페이지 수(기본 5, 상한 20) | |
| ncrAreaName | string | - | N | 등록 시도 필터(선택) | |
| ncrAreaDetailName | string | - | N | 등록 시군구 필터(선택) |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: sanction-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "opendata",
"action": "opendata.kiscon.sanction",
"params": {
"bizno": "<필수>",
"sDate": "<필수>",
"eDate": "<필수>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- 이 API 가 돌려주는 데이터: 사업자등록번호가 일치한 공시 건, 업체명, 상호로만 걸린 후보.건마다 행정처분명, 위반내용, 처분근거, 과징금, 과태료, 영업정지 시작일과 종료일, 시정내용, 등록말소일을 받습니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| source_ | string | 이 작업의 원천 데이터셋 번호입니다. 이 작업에서는 항상 15061362 입니다(공공데이터포털 data.go.kr 의 번호). | |
| action | string | 호출한 작업 이름입니다. 이 작업에서는 항상 opendata.kiscon.sanction 입니다. | |
| job_ | string | 이 결과를 만든 작업의 ID 입니다. | |
| source | object | 원천의 출처 정보입니다. 결과를 사용자에게 보여 줄 때 출처 표시에 씁니다. | |
| source. | string | 원천 데이터셋 번호입니다. source_id 와 같은 값입니다. | |
| source. | string | 원천 데이터를 제공하는 기관 이름입니다. 이 작업에서는 항상 국토교통부 입니다. | |
| source. | string | 원천 데이터의 이용 허락 범위 표기입니다. 값은 원천마다 다르고, 결과를 보여 줄 때 출처 표시와 함께 씁니다. | |
| license_ | array | 출처 표시 문구, 이용 허락 표기, 결과 해석 안내가 이 순서로 담긴 문장 목록입니다. 첫 줄은 「출처: 국토교통부 KISCON 건설행정처분 / data.go.kr 15061362」 입니다. | |
| upstream | object | 건설업 행정처분 공시를 조회 기간 안에서 훑어 사업자등록번호가 같은 행을 찾은 결과입니다. 아래 칸은 XBOSS 가 정해 담습니다. | |
| upstream. | string | 원천에서 부른 조회 이름입니다. 이 작업에서는 항상 GongsiAdmi 입니다. | |
| upstream. | string | 조회 방식입니다. 이 작업에서는 항상 M1_WITH_FALLBACK 로, 사업자등록번호가 같은 행을 찾고 상호(corp_name)를 보냈으면 번호가 비어 있는 행 가운데 이름이 같은 행을 보조 후보로 함께 담는다는 뜻입니다. | |
| upstream. | array | 조회 기간 안의 공시 행 가운데 사업자등록번호가 요청한 번호와 같은 행입니다. 원천이 준 행을 그대로 담고 안쪽 칸은 원천이 정하므로 이 문서가 보장하지 않습니다 - 어떤 정보가 오는지는 위의 「이 API 가 돌려주는 데이터」 에 적혀 있습니다. 비어 있으면 이 기간에는 일치하는 행이 없었다는 뜻입니다. | |
| upstream. | array | 사업자등록번호가 비어 있는 공시 행 가운데 요청한 상호와 이름이 같은 행입니다. 상호를 보내지 않았으면 비어 있습니다. 같은 사업자라는 확인은 아니므로 직접 대조해야 합니다. | |
| upstream. | object | 이번 조회가 훑은 범위입니다. | |
| upstream. | string | 훑은 기간의 시작일입니다(YYYYMMDD). 요청한 sDate 와 같습니다. | |
| upstream. | string | 훑은 기간의 마지막 날입니다(YYYYMMDD). 요청한 eDate 와 같습니다. | |
| upstream. | number | 원천에서 실제로 받은 쪽 수입니다. | |
| upstream. | number | 훑어 본 공시 행의 수입니다. | |
| upstream. | number | 한 쪽에 요청한 행 수입니다. | |
| upstream. | number | 최대로 훑는 쪽 수입니다. 요청한 maxPages 입니다. | |
| upstream. | number | null | 원천이 알려 준 기간 안의 전체 행 수입니다. 알려 주지 않으면 null 입니다. | |
| upstream. | boolean | 최대 쪽 수까지 훑고도 기간 안의 행이 더 남았을 수 있으면 true 입니다. 이때 matches 가 비어 있어도 일치하는 행이 없다는 확인이 아닙니다. | |
| upstream. | string | 이 조회의 범위와 한계를 알리는 안내문입니다. 기간 안에서만 훑었고 비어 있는 matches 가 깨끗하다는 확인이 아니라는 점을 적습니다. |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "opendata",
"action": "opendata.kiscon.sanction",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| POLICY_ | 공공데이터 조회의 하루 한도를 모두 쓰면 작업이 이 오류로 끝납니다. error.message 는 「오늘 이 조직의 공공데이터 조회 한도를 모두 썼습니다. 한국시간 자정에 다시 열립니다. 한도 상향이 필요하면 서비스문의로 알려 주세요.」 꼴이고, 한도의 범위에 따라 「이 조직의」 대신 「무료 요금제 몫의」 나 「서비스 전체」 가 들어갑니다. 자정이 지난 뒤에 다시 요청합니다. | |
| PROVIDER_ | 공공데이터 제공처가 오류로 답하면 작업이 이 오류로 끝나고, error.message 는 응답 상태로 고릅니다. 429 이면 「요청이 잠시 제한되었습니다. 잠시 후 다시 시도해 주세요.」, 500번대이면 「일시적인 오류로 요청을 마치지 못했습니다. 잠시 후 다시 시도해 주세요.」, 401 과 403 을 뺀 400번대이면 「요청을 처리할 수 없습니다. 입력한 값을 다시 확인해 주세요.」 입니다(401 과 403, 그리고 제공처가 인증키나 접근 권한을 거절한 응답은 이 오류가 아니라 INTERNAL_ERROR 로 끝납니다). 응답은 받았는데 읽지 못했거나 상태를 알 수 없으면 「기관에서 받은 응답을 처리하지 못했습니다. 잠시 후 다시 시도해 주시고, 계속되면 서비스문의로 알려 주세요.」 가 오고, 상태가 400번대도 500번대도 아니면 「일시적인 오류로 요청을 마치지 못했습니다. 잠시 후 다시 시도해 주세요.」 가 옵니다. | |
| VALIDATION_ | 요청 값이 맞지 않으면 작업이 이 오류로 끝나고, 요청을 고쳐 다시 요청합니다. 값이 빠지면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 값의 형식이 틀리면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴입니다(칸 이름이 다섯을 넘으면 앞 다섯과 「외 N개」 를 적습니다). 지원하지 않는 작업을 부르면 「지원하지 않는 작업입니다.」 입니다. 빠지거나 형식이 틀린 칸이 bizno 이면 그 꼴 대신 「사업자등록번호는 숫자 열 자리로 입력해 주세요.」 가 옵니다. | |
| INTERNAL_ | XBOSS 쪽 설정이나 처리 결함으로 끝나면 이 오류가 나가고 error.message 는 「서버 내부 오류로 작업을 마치지 못했습니다. 서비스문의로 알려 주세요.」 입니다. 고객이 고칠 값이 없으므로 잠시 뒤 다시 요청하고, 계속되면 서비스문의로 알려 주세요. 공공데이터 제공처가 XBOSS 의 이용 권한을 받아들이지 않을 때(응답 상태 401 이나 403, 또는 인증키나 접근 권한을 거절한 응답)도 이 오류이고 error.message 는 「조회 서비스를 이용할 수 없습니다. 서비스문의로 연결 상태 확인을 요청해 주세요.」 입니다. 다시 요청해도 같은 결과이므로 서비스문의로 알려 주세요. |