자료실 - 4대보험
1. 자주묻는질문 상세 조회fourinsure. b1. resources. faqs. detail
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
자주묻는질문 목록/검색 조회에서 받은 질문 번호를 넣으면 질문 제목과 화면 머리글, 표 줄, 답변이 담긴 화면 글자를 돌려줍니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
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 | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| qstn_ | string | Y | FAQ 질문 일련번호 qstnSn (목록 행 qstn_sn) | |
| current_ | number | N | 페이지 번호 currentPageNo. 기본 1 | |
| srch_ | string | N | 민원 유형 검색 srchCvlcptType | |
| srch_ | string | N | 분류 코드 srchClsfCd | |
| srch_ | string | N | 유형 코드 srchTypeCd | |
| srch_ | string | N | 검색 옵션 srchOpt | |
| srch_ | string | N | 검색어 srchTxt. 별칭은 query 입니다 | |
| srch_ | string | N | 정렬 srchSort |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: detail-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.resources.faqs.detail",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"qstn_sn": "<필수>"
}
}'Response
- result.data 의 detail 에 본문이 담깁니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| qstn_ | string | FAQ 질문 일련번호 | |
| detail | object | 상세 본문 객체 | |
| submitted_ | object | 제출 payload 맵 | |
| raw_ | number | 원본 HTML 길이 | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
// result.data
{
"success": true,
"qstn_sn": "...",
"detail": {},
"submitted_payload": {},
"raw_html_len": 0,
"source_url": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| VALIDATION_ | 필수 칸 누락 — 필수 칸(qstn_sn)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다. | |
| PROVIDER_ | 검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다. |
2. 자주묻는질문 목록/검색 조회fourinsure. b1. resources. faqs. list
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
검색 범위와 검색어, 정렬, 쪽 번호를 넣으면 자주묻는질문 한 쪽의 문의유형, 제목, 등록일, 조회수, 질문 번호를 돌려줍니다.
- 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
- 조회 결과가 없으면 items 가 빈 배열, row_count 가 0 으로 옵니다. 실패가 아닙니다.
- params 는 빈 객체로 보내도 호출됩니다.
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 | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| current_ | number | N | 페이지 번호 currentPageNo. 기본 1 | |
| srch_ | string | N | 민원 유형 검색 srchCvlcptType | |
| srch_ | string | N | 분류 코드 srchClsfCd | |
| srch_ | string | N | 유형 코드 srchTypeCd | |
| srch_ | string | N | 검색 옵션 srchOpt | |
| srch_ | string | N | 검색어 srchTxt. 별칭은 query 입니다 | |
| srch_ | string | N | 정렬 srchSort |
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: list-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.resources.faqs.list",
"params": {}
}'Response
- result.data 의 items 와 row_count 로 조회 결과를 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| row_ | number | 목록 건수 | |
| items | array | 조회 결과 행 배열 | |
| query | object | 적용된 검색 조건 맵 | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
// result.data
{
"success": true,
"row_count": 1,
"items": [
{ "row_index": 0, "row_key": "...", "qstn_sn": "12345", "title": "..." }
],
"query": { "currentPageNo": "1", "srchCvlcptType": "", "srchClsfCd": "", "srchTypeCd": "", "srchOpt": "", "srchTxt": "", "srchSort": "" },
"source_url": "https://..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |
3. 자주묻는질문 목록/검색 입력 서식 조회fourinsure. b1. resources. faqs. list_ init
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
입력 없이 부르면 자주묻는질문 검색 화면의 검색 범위(전체, 제목, 내용)와 정렬(최신순, 조회순) 선택 값, 기본값을 받습니다.
- 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
- params 는 빈 객체로 보내도 호출됩니다.
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 | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
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: list_init-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.resources.faqs.list_init",
"params": {}
}'Response
- result.data 에서 입력 항목(fields)과 화면 정보를 확인해 다음 단계(fourinsure.b1.resources.faqs.list)의 요청 본문을 만듭니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| page | object | 화면 페이지 메타 객체 | |
| forms | array | form 메타데이터 배열 | |
| fields | array | 입력 필드 계약 배열 | |
| semantic_ | array | 의미 단위 입력 컨트롤 배열 | |
| semantic_ | object | 의미 필드 키-값 맵 | |
| semantic_ | number | 의미 필드 개수 | |
| csrf_ | boolean | CSRF 토큰 존재 여부 | |
| followup_ | array | 기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다 | |
| raw_ | number | 원본 HTML 길이 | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
// result.data
{
"success": true,
"page": {},
"forms": [],
"fields": [],
"semantic_fields": [],
"semantic_payload": {},
"semantic_field_count": 1,
"csrf_token_present": true,
"followup_endpoints": [],
"raw_html_len": 0,
"source_url": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |
4. 자료실 첨부파일 다운로드fourinsure. b1. resources. files. download
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
첨부 묶음 번호와 순번을 넣으면 자료실에 그 파일이 있는지와 원본 이름을 확인해 돌려줍니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
- 기본은 dry_run=true 로 파일이 있는지와 받을 수 있는 형식인지만 확인합니다. 받으려면 dry_run 을 false 로 보냅니다.
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 | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| atfl_ | string | Y | 첨부파일 그룹 ID atflId | |
| atch_ | string | number | Y | 첨부파일 순번 atchFileSn | |
| dry_ | boolean | N | true면 downloadAtchFile 호출 없이 존재 여부만 확인. 기본 true |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: download-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.resources.files.download",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"atfl_id": "<필수>",
"atch_file_sn": "<필수: string | number>"
}
}'Response
- result.data 의 exists 로 파일이 있는지, downloadable 로 받을 수 있는 형식인지, downloaded 로 받았는지 확인합니다.받은 파일은 result.artifacts 에 download_url 과 함께 옵니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| dry_ | boolean | 접수 없이 검증만 한 호출이면 true | |
| downloaded | boolean | 다운로드 수행 여부 | |
| atfl_ | string | 첨부 묶음 번호(요청에 보낸 값) | |
| atch_ | string | 첨부 파일 순번(요청에 보낸 값) | |
| exists | boolean | 자료실에 그 첨부 파일이 있는지 여부 | |
| file_ | string | 파일명 | |
| downloadable | boolean | 그 첨부의 형식을 내려받을 수 있는지 여부(받을 수 있는 형식은 hwp 와 pdf 입니다). 기본 호출(dry_run=true)에서도 알려 주며, 다른 형식은 파일이 있어도 false 이고 dry_run 을 false 로 보내 받으려 하면 거절됩니다 |
// result.data
{
"success": true,
"dry_run": true,
"downloaded": false,
"atfl_id": "...",
"atch_file_sn": "...",
"exists": true,
"file_name": "...",
"downloadable": true
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| VALIDATION_ | 필수 칸 누락 — 필수 칸(atfl_id, atch_file_sn)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다. | |
| PROVIDER_ | 검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다. | |
| PROVIDER_ | 파일 없음 — dry_run 을 false 로 보내 받으려 했는데 자료실에 그 첨부가 없을 때입니다. error.message 는 첨부 목록을 다시 조회해 atfl_id 와 atch_file_sn 을 그대로 입력해 달라는 안내입니다. 확인만 하는 기본 호출(dry_run=true)은 거절하지 않고 exists 가 false 로 옵니다. | |
| PROVIDER_ | 지원 밖 형식 — dry_run 을 false 로 보내 받으려 했는데 그 첨부의 형식이 받을 수 있는 형식(hwp 와 pdf)이 아닐 때입니다. error.message 는 받을 수 있는 형식을 알려 주고 필요하면 문의해 달라는 안내입니다. 확인만 하는 기본 호출은 거절하지 않고 downloadable 이 false 로 오므로 받기 전에 알 수 있습니다. |
5. 서식자료실 첨부파일 목록 조회fourinsure. b1. resources. forms. attachments
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
서식자료실 목록/검색 조회의 게시판 번호, 게시글 번호, 첨부 묶음 번호를 넣으면 그 서식에 붙은 파일마다 원본 이름, 확장자, 크기, 순번을 돌려줍니다.
- 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
- 첨부가 없으면 files 가 빈 배열, file_count 가 0 으로 옵니다. 실패가 아닙니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| bbs_ | string | Y | 게시판 ID bbsId (목록 행 bbs_id) | |
| pst_ | string | Y | 게시글 일련번호 pstSn (목록 행 pst_sn) | |
| atfl_ | string | Y | 첨부파일 그룹 ID atflId | |
| current_ | number | N | 페이지 번호 currentPageNo. 기본 1 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: attachments-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.resources.forms.attachments",
"params": {
"bbs_id": "<필수>",
"pst_sn": "<필수>",
"atfl_id": "<필수>"
}
}'Response
- result.data 의 files 와 file_count 로 첨부 목록을 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| bbs_ | string | 게시판 ID | |
| pst_ | string | 게시글 일련번호 | |
| atfl_ | string | 첨부 묶음 번호(첨부 파일을 받을 때 atch_file_sn 과 함께 그대로 보냅니다) | |
| file_ | number | 첨부파일 수 | |
| files | array | 첨부파일 메타 배열 | |
| submitted_ | object | 제출 payload 맵 | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
// result.data
{
"success": true,
"bbs_id": "...",
"pst_sn": "...",
"atfl_id": "...",
"file_count": 1,
"files": [],
"submitted_payload": {},
"source_url": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| VALIDATION_ | 필수 칸 누락 — 필수 칸(bbs_id, pst_sn, atfl_id)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다. | |
| PROVIDER_ | 검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다. |
6. 서식자료실 상세 조회fourinsure. b1. resources. forms. detail
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
서식자료실 목록/검색 조회의 게시판 번호와 게시글 번호를 넣으면 그 게시글의 제목과 본문 글, 첨부파일 이름과 기관 화면의 내려받기, 미리보기 단추 정보를 돌려줍니다.
- 이 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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| bbs_ | string | Y | 게시판 ID bbsId (목록 행 bbs_id) | |
| pst_ | string | Y | 게시글 일련번호 pstSn (목록 행 pst_sn) |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: detail-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.resources.forms.detail",
"params": {
"bbs_id": "<필수>",
"pst_sn": "<필수>"
}
}'Response
- result.data 의 detail 에 본문이 담깁니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| bbs_ | string | 게시판 ID | |
| pst_ | string | 게시글 일련번호 | |
| detail | object | 상세 본문 객체 | |
| raw_ | number | 원본 HTML 길이 | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
// result.data
{
"success": true,
"bbs_id": "...",
"pst_sn": "...",
"detail": {},
"raw_html_len": 0,
"source_url": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| VALIDATION_ | 필수 칸 누락 — 필수 칸(bbs_id, pst_sn)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다. | |
| PROVIDER_ | 검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다. | |
| PROVIDER_ | 글 없음 — 보낸 bbs_id 와 pst_sn 에 해당하는 서식 글이 없을 때입니다. 기관이 글 화면이 아닌 응답을 주면 빈 값의 성공이 아니라 이 실패로 끝나고, error.message 는 해당 번호의 글을 찾을 수 없다는 안내입니다. 서식 목록 조회 결과의 bbs_id 와 pst_sn 값을 그대로 보내 다시 호출합니다. |
7. 서식자료실 목록/검색 조회fourinsure. b1. resources. forms. list
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
보험유형과 업무유형 코드, 검색어로 서식자료실 목록을 조회해 서식마다 제목, 보험 종류, 등록일과 상세 조회에 쓸 게시판 번호, 글 번호를 받습니다.
- 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
- 조회 결과가 없으면 items 가 빈 배열, row_count 가 0 으로 옵니다. 실패가 아닙니다.
- params 는 빈 객체로 보내도 호출됩니다.
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 | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| current_ | number | N | 페이지 번호 currentPageNo. 기본 1 | |
| srch_ | string | N | 4대보험 코드 srchInsuCd | |
| srch_ | string | N | 업무 코드 srchJobCd | |
| srch_ | string | N | 공개범위 코드 srchPubapCd | |
| srch_ | string | N | 검색어 srchTxt. 별칭은 query 입니다 |
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: list-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.resources.forms.list",
"params": {}
}'Response
- result.data 의 items 와 row_count 로 조회 결과를 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| row_ | number | 목록 건수 | |
| items | array | 조회 결과 행 배열 | |
| query | object | 적용된 검색 조건 맵 | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
// result.data
{
"success": true,
"row_count": 1,
"items": [
{
"row_index": 0,
"row_no": "...",
"row_key": "...",
"insurance_type": "...",
"title": "...",
"attachment_text": "...",
"posted_date": "2026-06-15",
"view_count": "...",
"bbs_id": "...",
"pst_sn": "...",
"atfl_id": "...",
"detail_url": "...",
"attachment_onclick": "...",
"raw_cells": []
}
],
"query": { "currentPageNo": "1", "srchInsuCd": "", "srchJobCd": "", "srchPubapCd": "", "srchTxt": "" },
"source_url": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |
8. 서식자료실 목록/검색 입력 서식 조회fourinsure. b1. resources. forms. list_ init
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
입력 없이 부르면 서식자료실 검색 화면에서 고를 수 있는 보험유형, 업무유형(자격, 보험료, 제증명 등), 민원유형 선택 값을 받습니다.
- 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
- params 는 빈 객체로 보내도 호출됩니다.
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 | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
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: list_init-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.resources.forms.list_init",
"params": {}
}'Response
- result.data 에서 입력 항목(fields)과 화면 정보를 확인해 다음 단계(fourinsure.b1.resources.forms.list)의 요청 본문을 만듭니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| page | object | 화면 페이지 메타 객체 | |
| forms | array | form 메타데이터 배열 | |
| fields | array | 입력 필드 계약 배열 | |
| semantic_ | array | 의미 단위 입력 컨트롤 배열 | |
| semantic_ | object | 의미 필드 키-값 맵 | |
| semantic_ | number | 의미 필드 개수 | |
| csrf_ | boolean | CSRF 토큰 존재 여부 | |
| followup_ | array | 기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다 | |
| raw_ | number | 원본 HTML 길이 | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
// result.data
{
"success": true,
"page": {},
"forms": [],
"fields": [],
"semantic_fields": [],
"semantic_payload": {},
"semantic_field_count": 1,
"csrf_token_present": true,
"followup_endpoints": [],
"raw_html_len": 0,
"source_url": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |
9. 기관별 공지사항 첨부파일 목록 조회fourinsure. b1. resources. notices. institutions. attachments
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
공지 글 번호를 넣으면 그 공지 상세 화면에 붙은 첨부파일의 개수와 파일마다 첨부 묶음 번호, 순번, 이름을 돌려줍니다.
- 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
- 첨부가 없으면 files 가 빈 배열, file_count 가 0 으로 옵니다. 실패가 아닙니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| pst_ | string | Y | 게시글 일련번호 pstSn (목록 행 pst_sn) |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: attachments-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.resources.notices.institutions.attachments",
"params": {
"pst_sn": "<필수>"
}
}'Response
- result.data 의 files 와 file_count 로 첨부 목록을 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| pst_ | string | 게시글 일련번호 | |
| file_ | number | 첨부파일 수 | |
| files | array | 첨부파일 메타 배열 | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
// result.data
{
"success": true,
"pst_sn": "...",
"file_count": 1,
"files": [],
"source_url": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| VALIDATION_ | 필수 칸 누락 — 필수 칸(pst_sn)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다. | |
| PROVIDER_ | 검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다. | |
| PROVIDER_ | 글 없음 — 보낸 pst_sn 에 해당하는 공지 글이 없을 때입니다. 기관이 글 화면이 아닌 응답을 주면 빈 값의 성공이 아니라 이 실패로 끝나고, error.message 는 해당 번호의 글을 찾을 수 없다는 안내입니다. 공지 목록 조회 결과의 pst_sn 값을 그대로 보내 다시 호출합니다. |
10. 기관별 공지사항 상세 조회fourinsure. b1. resources. notices. institutions. detail
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
공지 글 번호를 넣으면 그 공지의 제목과 본문 글, 붙은 첨부파일의 이름과 번호를 함께 돌려줍니다.
- 이 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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| pst_ | string | Y | 게시글 일련번호 pstSn (목록 행 pst_sn) |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: detail-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.resources.notices.institutions.detail",
"params": {
"pst_sn": "<필수>"
}
}'Response
- result.data 의 detail 에 본문이 담깁니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| pst_ | string | 게시글 일련번호 | |
| detail | object | 상세 본문 객체 | |
| raw_ | number | 원본 HTML 길이 | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
// result.data
{
"success": true,
"pst_sn": "...",
"detail": {},
"raw_html_len": 0,
"source_url": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| VALIDATION_ | 필수 칸 누락 — 필수 칸(pst_sn)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다. | |
| PROVIDER_ | 검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다. | |
| PROVIDER_ | 글 없음 — 보낸 pst_sn 에 해당하는 공지 글이 없을 때입니다. 기관이 글 화면이 아닌 응답을 주면 빈 값의 성공이 아니라 이 실패로 끝나고, error.message 는 해당 번호의 글을 찾을 수 없다는 안내입니다. 공지 목록 조회 결과의 pst_sn 값을 그대로 보내 다시 호출합니다. |
11. 기관별 공지사항 목록/검색 조회fourinsure. b1. resources. notices. institutions. list
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
검색 범위와 검색어로 기관별 공지사항 목록을 조회해 공지마다 올린 기관, 제목, 등록일, 조회수, 첨부 표시와 상세 조회에 쓸 글 번호를 받습니다.
- 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
- 조회 결과가 없으면 items 가 빈 배열, row_count 가 0 으로 옵니다. 실패가 아닙니다.
- params 는 빈 객체로 보내도 호출됩니다.
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 | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| current_ | number | N | 페이지 번호 currentPageNo. 기본 1 | |
| srch_ | string | N | 기관 검색 srchInst | |
| srch_ | string | N | 검색 옵션 srchOpt | |
| srch_ | string | N | 검색어 srchTxt. 별칭은 query 입니다 |
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: list-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.resources.notices.institutions.list",
"params": {}
}'Response
- result.data 의 items 와 row_count 로 조회 결과를 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| row_ | number | 목록 건수 | |
| items | array | 조회 결과 행 배열 | |
| query | object | 적용된 검색 조건 맵 | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
// result.data
{
"success": true,
"row_count": 1,
"items": [
{
"row_index": 0,
"row_no": "...",
"row_key": "...",
"institution": "...",
"title": "...",
"attachment_text": "...",
"posted_date": "2026-06-15",
"view_count": "...",
"pst_sn": "...",
"atfl_id": "...",
"detail_url": "...",
"attachment_href": "...",
"raw_cells": []
}
],
"query": { "currentPageNo": "1", "srchInst": "", "srchOpt": "", "srchTxt": "" },
"source_url": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |
12. 기관별 공지사항 목록/검색 입력 서식 조회fourinsure. b1. resources. notices. institutions. list_ init
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
입력 없이 부르면 기관별 공지사항 검색 화면의 검색 범위(전체, 제목, 내용)와 검색어 칸, 기관 칸 이름을 받습니다.
- 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
- params 는 빈 객체로 보내도 호출됩니다.
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 | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
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: list_init-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.resources.notices.institutions.list_init",
"params": {}
}'Response
- result.data 에서 입력 항목(fields)과 화면 정보를 확인해 다음 단계(fourinsure.b1.resources.notices.institutions.list)의 요청 본문을 만듭니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| page | object | 화면 페이지 메타 객체 | |
| forms | array | form 메타데이터 배열 | |
| fields | array | 입력 필드 계약 배열 | |
| semantic_ | array | 의미 단위 입력 컨트롤 배열 | |
| semantic_ | object | 의미 필드 키-값 맵 | |
| semantic_ | number | 의미 필드 개수 | |
| csrf_ | boolean | CSRF 토큰 존재 여부 | |
| followup_ | array | 기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다 | |
| raw_ | number | 원본 HTML 길이 | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
// result.data
{
"success": true,
"page": {},
"forms": [],
"fields": [],
"semantic_fields": [],
"semantic_payload": {},
"semantic_field_count": 1,
"csrf_token_present": true,
"followup_endpoints": [],
"raw_html_len": 0,
"source_url": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |