개발자 문서
API 레퍼런스

자료실 - 4대보험

1. 자주묻는질문 상세 조회fourinsure.b1.resources.faqs.detail

MCP 도구 이름 fourinsure__b1__resources__faqs__detail

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

자주묻는질문 목록/검색 조회에서 받은 질문 번호를 넣으면 질문 제목과 화면 머리글, 표 줄, 답변이 담긴 화면 글자를 돌려줍니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstring-Y호출할 작업입니다.
  • fourinsure.b1.resources.faqs.detail이 API 고정값 (기본값)

예시 : fourinsure.b1.resources.faqs.detail

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
qstn_snstringYFAQ 질문 일련번호 qstnSn (목록 행 qstn_sn)
current_page_nonumberN페이지 번호 currentPageNo. 기본 1
srch_cvlcpt_typestringN민원 유형 검색 srchCvlcptType
srch_clsf_cdstringN분류 코드 srchClsfCd
srch_type_cdstringN유형 코드 srchTypeCd
srch_optstringN검색 옵션 srchOpt
srch_txtstringN검색어 srchTxt. 별칭은 query 입니다
srch_sortstringN정렬 srchSort
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: 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 에 본문이 담깁니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
qstn_snstringFAQ 질문 일련번호
detailobject상세 본문 객체
submitted_payloadobject제출 payload 맵
raw_html_lennumber원본 HTML 길이
source_urlstring서버가 요청한 기관 화면 주소
json
// result.data
{
  "success": true,
  "qstn_sn": "...",
  "detail": {},
  "submitted_payload": {},
  "raw_html_len": 0,
  "source_url": "..."
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.
VALIDATION_INVALID_FIELD필수 칸 누락 — 필수 칸(qstn_sn)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다.
PROVIDER_VALIDATION_ERROR검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다.

2. 자주묻는질문 목록/검색 조회fourinsure.b1.resources.faqs.list

MCP 도구 이름 fourinsure__b1__resources__faqs__list

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

검색 범위와 검색어, 정렬, 쪽 번호를 넣으면 자주묻는질문 한 쪽의 문의유형, 제목, 등록일, 조회수, 질문 번호를 돌려줍니다.

  • 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
  • 조회 결과가 없으면 items 가 빈 배열, row_count 가 0 으로 옵니다. 실패가 아닙니다.
  • params 는 빈 객체로 보내도 호출됩니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입필수설명
providerstringY호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstringY호출할 작업입니다.
  • fourinsure.b1.resources.faqs.list이 API 고정값 (기본값)

예시 : fourinsure.b1.resources.faqs.list

paramsobjectN작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobjectN민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
current_page_nonumberN페이지 번호 currentPageNo. 기본 1
srch_cvlcpt_typestringN민원 유형 검색 srchCvlcptType
srch_clsf_cdstringN분류 코드 srchClsfCd
srch_type_cdstringN유형 코드 srchTypeCd
srch_optstringN검색 옵션 srchOpt
srch_txtstringN검색어 srchTxt. 별칭은 query 입니다
srch_sortstringN정렬 srchSort
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: 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 로 조회 결과를 확인합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
row_countnumber목록 건수
itemsarray조회 결과 행 배열
queryobject적용된 검색 조건 맵
source_urlstring서버가 요청한 기관 화면 주소
json
// 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_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.

3. 자주묻는질문 목록/검색 입력 서식 조회fourinsure.b1.resources.faqs.list_init

MCP 도구 이름 fourinsure__b1__resources__faqs__list_init

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

입력 없이 부르면 자주묻는질문 검색 화면의 검색 범위(전체, 제목, 내용)와 정렬(최신순, 조회순) 선택 값, 기본값을 받습니다.

  • 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
  • params 는 빈 객체로 보내도 호출됩니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입필수설명
providerstringY호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstringY호출할 작업입니다.
  • fourinsure.b1.resources.faqs.list_init이 API 고정값 (기본값)

예시 : fourinsure.b1.resources.faqs.list_init

paramsobjectN작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobjectN민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

추가 파라미터가 없습니다. params 는 {} 로 보냅니다.

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: 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)의 요청 본문을 만듭니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
pageobject화면 페이지 메타 객체
formsarrayform 메타데이터 배열
fieldsarray입력 필드 계약 배열
semantic_fieldsarray의미 단위 입력 컨트롤 배열
semantic_payloadobject의미 필드 키-값 맵
semantic_field_countnumber의미 필드 개수
csrf_token_presentbooleanCSRF 토큰 존재 여부
followup_endpointsarray기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다
raw_html_lennumber원본 HTML 길이
source_urlstring서버가 요청한 기관 화면 주소
json
// 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_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.

4. 자료실 첨부파일 다운로드fourinsure.b1.resources.files.download

MCP 도구 이름 fourinsure__b1__resources__files__download

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

첨부 묶음 번호와 순번을 넣으면 자료실에 그 파일이 있는지와 원본 이름을 확인해 돌려줍니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • 기본은 dry_run=true 로 파일이 있는지와 받을 수 있는 형식인지만 확인합니다. 받으려면 dry_run 을 false 로 보냅니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstring-Y호출할 작업입니다.
  • fourinsure.b1.resources.files.download이 API 고정값 (기본값)

예시 : fourinsure.b1.resources.files.download

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
atfl_idstringY첨부파일 그룹 ID atflId
atch_file_snstring | numberY첨부파일 순번 atchFileSn
dry_runbooleanNtrue면 downloadAtchFile 호출 없이 존재 여부만 확인. 기본 true
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: 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 로 받았는지 확인합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
dry_runboolean접수 없이 검증만 한 호출이면 true
downloadedboolean다운로드 수행 여부
atfl_idstring첨부 묶음 번호(요청에 보낸 값)
atch_file_snstring첨부 파일 순번(요청에 보낸 값)
existsboolean자료실에 그 첨부 파일이 있는지 여부
file_namestring파일명
downloadableboolean그 첨부의 형식을 내려받을 수 있는지 여부(받을 수 있는 형식은 hwp 와 pdf 입니다). 기본 호출(dry_run=true)에서도 알려 주며, 다른 형식은 파일이 있어도 false 이고 dry_run 을 false 로 보내 받으려 하면 거절됩니다
json
// result.data
{
  "success": true,
  "dry_run": true,
  "downloaded": false,
  "atfl_id": "...",
  "atch_file_sn": "...",
  "exists": true,
  "file_name": "...",
  "downloadable": true
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.
VALIDATION_INVALID_FIELD필수 칸 누락 — 필수 칸(atfl_id, atch_file_sn)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다.
PROVIDER_VALIDATION_ERROR검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다.
PROVIDER_VALIDATION_ERROR파일 없음 — dry_run 을 false 로 보내 받으려 했는데 자료실에 그 첨부가 없을 때입니다. error.message 는 첨부 목록을 다시 조회해 atfl_id 와 atch_file_sn 을 그대로 입력해 달라는 안내입니다. 확인만 하는 기본 호출(dry_run=true)은 거절하지 않고 exists 가 false 로 옵니다.
PROVIDER_VALIDATION_ERROR지원 밖 형식 — dry_run 을 false 로 보내 받으려 했는데 그 첨부의 형식이 받을 수 있는 형식(hwp 와 pdf)이 아닐 때입니다. error.message 는 받을 수 있는 형식을 알려 주고 필요하면 문의해 달라는 안내입니다. 확인만 하는 기본 호출은 거절하지 않고 downloadable 이 false 로 오므로 받기 전에 알 수 있습니다.

5. 서식자료실 첨부파일 목록 조회fourinsure.b1.resources.forms.attachments

MCP 도구 이름 fourinsure__b1__resources__forms__attachments

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

서식자료실 목록/검색 조회의 게시판 번호, 게시글 번호, 첨부 묶음 번호를 넣으면 그 서식에 붙은 파일마다 원본 이름, 확장자, 크기, 순번을 돌려줍니다.

  • 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
  • 첨부가 없으면 files 가 빈 배열, file_count 가 0 으로 옵니다. 실패가 아닙니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입필수설명
providerstringY호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstringY호출할 작업입니다.
  • fourinsure.b1.resources.forms.attachments이 API 고정값 (기본값)

예시 : fourinsure.b1.resources.forms.attachments

paramsobjectY작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobjectN민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
bbs_idstringY게시판 ID bbsId (목록 행 bbs_id)
pst_snstringY게시글 일련번호 pstSn (목록 행 pst_sn)
atfl_idstringY첨부파일 그룹 ID atflId
current_page_nonumberN페이지 번호 currentPageNo. 기본 1
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: 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 로 첨부 목록을 확인합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
bbs_idstring게시판 ID
pst_snstring게시글 일련번호
atfl_idstring첨부 묶음 번호(첨부 파일을 받을 때 atch_file_sn 과 함께 그대로 보냅니다)
file_countnumber첨부파일 수
filesarray첨부파일 메타 배열
submitted_payloadobject제출 payload 맵
source_urlstring서버가 요청한 기관 화면 주소
json
// result.data
{
  "success": true,
  "bbs_id": "...",
  "pst_sn": "...",
  "atfl_id": "...",
  "file_count": 1,
  "files": [],
  "submitted_payload": {},
  "source_url": "..."
}
순번오류 코드발생 조건
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.
VALIDATION_INVALID_FIELD필수 칸 누락 — 필수 칸(bbs_id, pst_sn, atfl_id)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다.
PROVIDER_VALIDATION_ERROR검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다.

6. 서식자료실 상세 조회fourinsure.b1.resources.forms.detail

MCP 도구 이름 fourinsure__b1__resources__forms__detail

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

서식자료실 목록/검색 조회의 게시판 번호와 게시글 번호를 넣으면 그 게시글의 제목과 본문 글, 첨부파일 이름과 기관 화면의 내려받기, 미리보기 단추 정보를 돌려줍니다.

  • 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입필수설명
providerstringY호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstringY호출할 작업입니다.
  • fourinsure.b1.resources.forms.detail이 API 고정값 (기본값)

예시 : fourinsure.b1.resources.forms.detail

paramsobjectY작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobjectN민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
bbs_idstringY게시판 ID bbsId (목록 행 bbs_id)
pst_snstringY게시글 일련번호 pstSn (목록 행 pst_sn)
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: 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 에 본문이 담깁니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
bbs_idstring게시판 ID
pst_snstring게시글 일련번호
detailobject상세 본문 객체
raw_html_lennumber원본 HTML 길이
source_urlstring서버가 요청한 기관 화면 주소
json
// result.data
{
  "success": true,
  "bbs_id": "...",
  "pst_sn": "...",
  "detail": {},
  "raw_html_len": 0,
  "source_url": "..."
}
순번오류 코드발생 조건
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.
VALIDATION_INVALID_FIELD필수 칸 누락 — 필수 칸(bbs_id, pst_sn)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다.
PROVIDER_VALIDATION_ERROR검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다.
PROVIDER_VALIDATION_ERROR글 없음 — 보낸 bbs_id 와 pst_sn 에 해당하는 서식 글이 없을 때입니다. 기관이 글 화면이 아닌 응답을 주면 빈 값의 성공이 아니라 이 실패로 끝나고, error.message 는 해당 번호의 글을 찾을 수 없다는 안내입니다. 서식 목록 조회 결과의 bbs_id 와 pst_sn 값을 그대로 보내 다시 호출합니다.

7. 서식자료실 목록/검색 조회fourinsure.b1.resources.forms.list

MCP 도구 이름 fourinsure__b1__resources__forms__list

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

보험유형과 업무유형 코드, 검색어로 서식자료실 목록을 조회해 서식마다 제목, 보험 종류, 등록일과 상세 조회에 쓸 게시판 번호, 글 번호를 받습니다.

  • 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
  • 조회 결과가 없으면 items 가 빈 배열, row_count 가 0 으로 옵니다. 실패가 아닙니다.
  • params 는 빈 객체로 보내도 호출됩니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입필수설명
providerstringY호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstringY호출할 작업입니다.
  • fourinsure.b1.resources.forms.list이 API 고정값 (기본값)

예시 : fourinsure.b1.resources.forms.list

paramsobjectN작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobjectN민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
current_page_nonumberN페이지 번호 currentPageNo. 기본 1
srch_insu_cdstringN4대보험 코드 srchInsuCd
srch_job_cdstringN업무 코드 srchJobCd
srch_pubap_cdstringN공개범위 코드 srchPubapCd
srch_txtstringN검색어 srchTxt. 별칭은 query 입니다
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: 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 로 조회 결과를 확인합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
row_countnumber목록 건수
itemsarray조회 결과 행 배열
queryobject적용된 검색 조건 맵
source_urlstring서버가 요청한 기관 화면 주소
json
// 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_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.

8. 서식자료실 목록/검색 입력 서식 조회fourinsure.b1.resources.forms.list_init

MCP 도구 이름 fourinsure__b1__resources__forms__list_init

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

입력 없이 부르면 서식자료실 검색 화면에서 고를 수 있는 보험유형, 업무유형(자격, 보험료, 제증명 등), 민원유형 선택 값을 받습니다.

  • 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
  • params 는 빈 객체로 보내도 호출됩니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입필수설명
providerstringY호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstringY호출할 작업입니다.
  • fourinsure.b1.resources.forms.list_init이 API 고정값 (기본값)

예시 : fourinsure.b1.resources.forms.list_init

paramsobjectN작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobjectN민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

추가 파라미터가 없습니다. params 는 {} 로 보냅니다.

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: 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)의 요청 본문을 만듭니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
pageobject화면 페이지 메타 객체
formsarrayform 메타데이터 배열
fieldsarray입력 필드 계약 배열
semantic_fieldsarray의미 단위 입력 컨트롤 배열
semantic_payloadobject의미 필드 키-값 맵
semantic_field_countnumber의미 필드 개수
csrf_token_presentbooleanCSRF 토큰 존재 여부
followup_endpointsarray기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다
raw_html_lennumber원본 HTML 길이
source_urlstring서버가 요청한 기관 화면 주소
json
// 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_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.

9. 기관별 공지사항 첨부파일 목록 조회fourinsure.b1.resources.notices.institutions.attachments

MCP 도구 이름 fourinsure__b1__resources__notices__institutions__attachments

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

공지 글 번호를 넣으면 그 공지 상세 화면에 붙은 첨부파일의 개수와 파일마다 첨부 묶음 번호, 순번, 이름을 돌려줍니다.

  • 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
  • 첨부가 없으면 files 가 빈 배열, file_count 가 0 으로 옵니다. 실패가 아닙니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입필수설명
providerstringY호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstringY호출할 작업입니다.
  • fourinsure.b1.resources.notices.institutions.attachments이 API 고정값 (기본값)

예시 : fourinsure.b1.resources.notices.institutions.attachments

paramsobjectY작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobjectN민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
pst_snstringY게시글 일련번호 pstSn (목록 행 pst_sn)
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: 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 로 첨부 목록을 확인합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
pst_snstring게시글 일련번호
file_countnumber첨부파일 수
filesarray첨부파일 메타 배열
source_urlstring서버가 요청한 기관 화면 주소
json
// result.data
{
  "success": true,
  "pst_sn": "...",
  "file_count": 1,
  "files": [],
  "source_url": "..."
}
순번오류 코드발생 조건
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.
VALIDATION_INVALID_FIELD필수 칸 누락 — 필수 칸(pst_sn)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다.
PROVIDER_VALIDATION_ERROR검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다.
PROVIDER_VALIDATION_ERROR글 없음 — 보낸 pst_sn 에 해당하는 공지 글이 없을 때입니다. 기관이 글 화면이 아닌 응답을 주면 빈 값의 성공이 아니라 이 실패로 끝나고, error.message 는 해당 번호의 글을 찾을 수 없다는 안내입니다. 공지 목록 조회 결과의 pst_sn 값을 그대로 보내 다시 호출합니다.

10. 기관별 공지사항 상세 조회fourinsure.b1.resources.notices.institutions.detail

MCP 도구 이름 fourinsure__b1__resources__notices__institutions__detail

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

공지 글 번호를 넣으면 그 공지의 제목과 본문 글, 붙은 첨부파일의 이름과 번호를 함께 돌려줍니다.

  • 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입필수설명
providerstringY호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstringY호출할 작업입니다.
  • fourinsure.b1.resources.notices.institutions.detail이 API 고정값 (기본값)

예시 : fourinsure.b1.resources.notices.institutions.detail

paramsobjectY작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobjectN민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
pst_snstringY게시글 일련번호 pstSn (목록 행 pst_sn)
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: 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 에 본문이 담깁니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
pst_snstring게시글 일련번호
detailobject상세 본문 객체
raw_html_lennumber원본 HTML 길이
source_urlstring서버가 요청한 기관 화면 주소
json
// result.data
{
  "success": true,
  "pst_sn": "...",
  "detail": {},
  "raw_html_len": 0,
  "source_url": "..."
}
순번오류 코드발생 조건
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.
VALIDATION_INVALID_FIELD필수 칸 누락 — 필수 칸(pst_sn)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다.
PROVIDER_VALIDATION_ERROR검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다.
PROVIDER_VALIDATION_ERROR글 없음 — 보낸 pst_sn 에 해당하는 공지 글이 없을 때입니다. 기관이 글 화면이 아닌 응답을 주면 빈 값의 성공이 아니라 이 실패로 끝나고, error.message 는 해당 번호의 글을 찾을 수 없다는 안내입니다. 공지 목록 조회 결과의 pst_sn 값을 그대로 보내 다시 호출합니다.

11. 기관별 공지사항 목록/검색 조회fourinsure.b1.resources.notices.institutions.list

MCP 도구 이름 fourinsure__b1__resources__notices__institutions__list

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

검색 범위와 검색어로 기관별 공지사항 목록을 조회해 공지마다 올린 기관, 제목, 등록일, 조회수, 첨부 표시와 상세 조회에 쓸 글 번호를 받습니다.

  • 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
  • 조회 결과가 없으면 items 가 빈 배열, row_count 가 0 으로 옵니다. 실패가 아닙니다.
  • params 는 빈 객체로 보내도 호출됩니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입필수설명
providerstringY호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstringY호출할 작업입니다.
  • fourinsure.b1.resources.notices.institutions.list이 API 고정값 (기본값)

예시 : fourinsure.b1.resources.notices.institutions.list

paramsobjectN작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobjectN민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
current_page_nonumberN페이지 번호 currentPageNo. 기본 1
srch_inststringN기관 검색 srchInst
srch_optstringN검색 옵션 srchOpt
srch_txtstringN검색어 srchTxt. 별칭은 query 입니다
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: 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 로 조회 결과를 확인합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
row_countnumber목록 건수
itemsarray조회 결과 행 배열
queryobject적용된 검색 조건 맵
source_urlstring서버가 요청한 기관 화면 주소
json
// 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_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.

12. 기관별 공지사항 목록/검색 입력 서식 조회fourinsure.b1.resources.notices.institutions.list_init

MCP 도구 이름 fourinsure__b1__resources__notices__institutions__list_init

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

입력 없이 부르면 기관별 공지사항 검색 화면의 검색 범위(전체, 제목, 내용)와 검색어 칸, 기관 칸 이름을 받습니다.

  • 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
  • params 는 빈 객체로 보내도 호출됩니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입필수설명
providerstringY호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstringY호출할 작업입니다.
  • fourinsure.b1.resources.notices.institutions.list_init이 API 고정값 (기본값)

예시 : fourinsure.b1.resources.notices.institutions.list_init

paramsobjectN작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobjectN민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

추가 파라미터가 없습니다. params 는 {} 로 보냅니다.

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: 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)의 요청 본문을 만듭니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
pageobject화면 페이지 메타 객체
formsarrayform 메타데이터 배열
fieldsarray입력 필드 계약 배열
semantic_fieldsarray의미 단위 입력 컨트롤 배열
semantic_payloadobject의미 필드 키-값 맵
semantic_field_countnumber의미 필드 개수
csrf_token_presentbooleanCSRF 토큰 존재 여부
followup_endpointsarray기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다
raw_html_lennumber원본 HTML 길이
source_urlstring서버가 요청한 기관 화면 주소
json
// 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_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.