자료실

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

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

정보연계센터 자주묻는질문 가운데 특정 질문 하나를 골라 제목과 답변 내용을 정리해 받아옵니다.

로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

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

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

변수명	타입	필수	설명
qstn_sn	string	Y	FAQ 질문 일련번호 qstnSn (목록 행 qstn_sn)
current_page_no	number	N	페이지 번호 currentPageNo. 기본 1
srch_cvlcpt_type	string	N	민원 유형 검색 srchCvlcptType
srch_clsf_cd	string	N	분류 코드 srchClsfCd
srch_type_cd	string	N	유형 코드 srchTypeCd
srch_opt	string	N	검색 옵션 srchOpt
srch_txt	string	N	검색어 srchTxt. 별칭은 query 입니다
srch_sort	string	N	정렬 srchSort

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-detail-001' \
  --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	요청 처리 성공 여부
	qstn_sn	FAQ 질문 일련번호
	detail	상세 본문 객체
	submitted_payload	제출 payload 맵
	raw_html_len	원본 HTML 길이
	source_url	업스트림 요청 URL

json

// result.data
{
  "success": true,
  "qstn_sn": "...",
  "detail": {},
  "submitted_payload": {},
  "raw_html_len": 0,
  "source_url": "..."
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
	PROVIDER_AUTH_FAILED	인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.
	PROVIDER_VALIDATION_ERROR	검증 오류 — 보낸 파라미터 값을 기관이 거부했습니다. 값을 확인합니다.

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

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

4대보험 정보연계센터의 자주묻는질문을 분류와 검색어로 찾습니다.

로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
조회 결과가 없으면 items 가 빈 배열, row_count 가 0 으로 옵니다. 실패가 아닙니다.
sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

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

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

변수명	타입	필수	설명
current_page_no	number	N	페이지 번호 currentPageNo. 기본 1
srch_cvlcpt_type	string	N	민원 유형 검색 srchCvlcptType
srch_clsf_cd	string	N	분류 코드 srchClsfCd
srch_type_cd	string	N	유형 코드 srchTypeCd
srch_opt	string	N	검색 옵션 srchOpt
srch_txt	string	N	검색어 srchTxt. 별칭은 query 입니다
srch_sort	string	N	정렬 srchSort

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-list-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.resources.faqs.list",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

result.data 의 items 와 row_count 로 조회 결과를 확인합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	row_count	목록 건수
	items	조회 결과 행 배열
	query	적용된 검색 조건 맵
	source_url	업스트림 요청 URL

json

// result.data
{
  "success": true,
  "row_count": 2,
  "items": [
    { "row_index": 0, "row_key": "...", "qstn_sn": "12345", "title": "..." }
  ],
  "query": { "srch_txt": "" },
  "source_url": "https://..."
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
	PROVIDER_AUTH_FAILED	인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.
	PROVIDER_VALIDATION_ERROR	검증 오류 — 보낸 파라미터 값을 기관이 거부했습니다. 값을 확인합니다.

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

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

자주묻는질문을 검색하기 전에 화면이 제공하는 검색 조건을 받아옵니다.

로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

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

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `fourinsure`이 API 고정값 (기본값) 예시 : fourinsure
action	string	-	Y	호출할 작업입니다. `fourinsure.b1.resources.faqs.list_init`이 API 고정값 (기본값) 예시 : fourinsure.b1.resources.faqs.list_init
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	N	작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fields	object	-	N	민감한 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: sandbox' \
  --header 'Idempotency-Key: demo-list_init-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.resources.faqs.list_init",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

result.data 에서 입력 항목(fields)과 다음 단계 정보를 확인해 후속 요청 본문을 만듭니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	page	화면 페이지 메타 객체
	forms	form 메타데이터 배열
	fields	입력 필드 계약 배열
	semantic_fields	의미 단위 입력 컨트롤 배열
	semantic_payload	의미 필드 키-값 맵
	semantic_field_count	의미 필드 개수
	csrf_token_present	CSRF 토큰 존재 여부
	followup_endpoints	후속 endpoint URL 배열
	navigation_steps	화면 내비게이션 단계 배열
	current_view	현재 화면 식별자
	target_ready	대상 폼 준비 여부
	raw_html_len	원본 HTML 길이
	source_url	업스트림 요청 URL

json

// result.data
{
  "success": true,
  "page": {},
  "forms": [],
  "fields": [],
  "semantic_fields": [],
  "semantic_payload": {},
  "semantic_field_count": 1,
  "csrf_token_present": true,
  "followup_endpoints": [],
  "navigation_steps": [],
  "current_view": "...",
  "target_ready": true,
  "raw_html_len": 0,
  "source_url": "..."
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
	PROVIDER_AUTH_FAILED	인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.
	PROVIDER_VALIDATION_ERROR	검증 오류 — 보낸 파라미터 값을 기관이 거부했습니다. 값을 확인합니다.

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

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

4대보험 EDI 자료실 첨부파일 다운로드 업무를 위해 공지와 서식 자료실의 첨부파일을 내려받습니다.

로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
기본은 dry_run=true 로 파일이 있는지만 확인합니다. 받으려면 dry_run 을 false 로 보냅니다.

Request

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

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

변수명	타입	필수	설명
atfl_id	string	Y	첨부파일 그룹 ID atflId
atch_file_sn	string \| number	Y	첨부파일 순번 atchFileSn
dry_run	boolean	N	true면 downloadAtchFile 호출 없이 존재 여부만 확인. 기본 true
include_base64	boolean	N	true면 응답에 base64 본문 포함

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-download-001' \
  --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 로 파일이 있는지, downloaded 로 받았는지 확인합니다. include_base64 가 true 면 base64 에 본문이 담깁니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	dry_run	dry-run 모드 여부
	downloaded	다운로드 수행 여부
	atfl_id	atfl_id 필드
	atch_file_sn	atch_file_sn 필드
	exists	exists 필드
	exists_response	exists_response 필드
	download_url	download_url 필드
	file_name	파일명
	content_type	MIME 타입
	bytes_len	바이트 길이
	base64	Base64 인코딩 본문(옵션)

json

// result.data
{
  "success": true,
  "dry_run": false,
  "downloaded": false,
  "atfl_id": "...",
  "atch_file_sn": "...",
  "exists": true,
  "exists_response": {},
  "download_url": "...",
  "file_name": "...",
  "content_type": "...",
  "bytes_len": 0,
  "base64": "..."
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
	PROVIDER_AUTH_FAILED	인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.
	PROVIDER_VALIDATION_ERROR	검증 오류 — 보낸 파라미터 값을 기관이 거부했습니다. 값을 확인합니다.

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

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

4대보험 EDI 서식자료실 첨부파일 목록 조회 업무를 위해 서식 게시물에 첨부된 파일 메타데이터 목록을 조회합니다.

로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
첨부가 없으면 files 가 빈 배열, file_count 가 0 으로 옵니다. 실패가 아닙니다.
sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

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

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

변수명	타입	필수	설명
bbs_id	string	Y	게시판 ID bbsId (목록 행 bbs_id)
pst_sn	string	Y	게시글 일련번호 pstSn (목록 행 pst_sn)
atfl_id	string	Y	첨부파일 그룹 ID atflId
current_page_no	number	N	페이지 번호 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: sandbox' \
  --header 'Idempotency-Key: demo-attachments-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.resources.forms.attachments",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "bbs_id": "<필수>",
    "pst_sn": "<필수>",
    "atfl_id": "<필수>"
  }
}'

Response

result.data 의 files 와 file_count 로 첨부 목록을 확인합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	bbs_id	게시판 ID
	pst_sn	게시글 일련번호
	atfl_id	atfl_id 필드
	file_count	첨부파일 수
	files	첨부파일 메타 배열
	submitted_payload	제출 payload 맵
	source_url	업스트림 요청 URL

json

// result.data
{
  "success": true,
  "bbs_id": "...",
  "pst_sn": "...",
  "atfl_id": "...",
  "file_count": 1,
  "files": [],
  "submitted_payload": {},
  "source_url": "..."
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
	PROVIDER_AUTH_FAILED	인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.
	PROVIDER_VALIDATION_ERROR	검증 오류 — 보낸 파라미터 값을 기관이 거부했습니다. 값을 확인합니다.

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

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

정보연계센터 서식자료실에 올라온 특정 서식의 제목과 안내 표 항목을 정리해 받아옵니다.

로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

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

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

순번	변수명	타입	필수	설명
	bbs_id	string	Y	게시판 ID bbsId (목록 행 bbs_id)
	pst_sn	string	Y	게시글 일련번호 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: sandbox' \
  --header 'Idempotency-Key: demo-detail-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.resources.forms.detail",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "bbs_id": "<필수>",
    "pst_sn": "<필수>"
  }
}'

Response

result.data 의 detail 에 본문이 담깁니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	bbs_id	게시판 ID
	pst_sn	게시글 일련번호
	detail	상세 본문 객체
	raw_html_len	원본 HTML 길이
	source_url	업스트림 요청 URL

json

// result.data
{
  "success": true,
  "bbs_id": "...",
  "pst_sn": "...",
  "detail": {},
  "raw_html_len": 0,
  "source_url": "..."
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
	PROVIDER_AUTH_FAILED	인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.
	PROVIDER_VALIDATION_ERROR	검증 오류 — 보낸 파라미터 값을 기관이 거부했습니다. 값을 확인합니다.

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

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

4대보험 정보연계센터 서식자료실에서 보험 종류와 업무별로 서식을 찾습니다.

로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
조회 결과가 없으면 items 가 빈 배열, row_count 가 0 으로 옵니다. 실패가 아닙니다.
sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

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

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

변수명	타입	필수	설명
current_page_no	number	N	페이지 번호 currentPageNo. 기본 1
srch_insu_cd	string	N	4대보험 코드 srchInsuCd
srch_job_cd	string	N	업무 코드 srchJobCd
srch_pubap_cd	string	N	공개범위 코드 srchPubapCd
srch_txt	string	N	검색어 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: sandbox' \
  --header 'Idempotency-Key: demo-list-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.resources.forms.list",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

result.data 의 items 와 row_count 로 조회 결과를 확인합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	row_count	목록 건수
	items	조회 결과 행 배열
	query	적용된 검색 조건 맵
	source_url	업스트림 요청 URL

json

// result.data
{
  "success": true,
  "row_count": 1,
  "items": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "query": {},
  "source_url": "..."
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
	PROVIDER_AUTH_FAILED	인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.
	PROVIDER_VALIDATION_ERROR	검증 오류 — 보낸 파라미터 값을 기관이 거부했습니다. 값을 확인합니다.

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

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

서식자료실을 검색하기 전에 화면이 제공하는 검색 조건을 받아옵니다.

로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

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

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `fourinsure`이 API 고정값 (기본값) 예시 : fourinsure
action	string	-	Y	호출할 작업입니다. `fourinsure.b1.resources.forms.list_init`이 API 고정값 (기본값) 예시 : fourinsure.b1.resources.forms.list_init
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	N	작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fields	object	-	N	민감한 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: sandbox' \
  --header 'Idempotency-Key: demo-list_init-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.resources.forms.list_init",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

result.data 에서 입력 항목(fields)과 다음 단계 정보를 확인해 후속 요청 본문을 만듭니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	page	화면 페이지 메타 객체
	forms	form 메타데이터 배열
	fields	입력 필드 계약 배열
	semantic_fields	의미 단위 입력 컨트롤 배열
	semantic_payload	의미 필드 키-값 맵
	semantic_field_count	의미 필드 개수
	csrf_token_present	CSRF 토큰 존재 여부
	followup_endpoints	후속 endpoint URL 배열
	navigation_steps	화면 내비게이션 단계 배열
	current_view	현재 화면 식별자
	target_ready	대상 폼 준비 여부
	raw_html_len	원본 HTML 길이
	source_url	업스트림 요청 URL

json

// result.data
{
  "success": true,
  "page": {},
  "forms": [],
  "fields": [],
  "semantic_fields": [],
  "semantic_payload": {},
  "semantic_field_count": 1,
  "csrf_token_present": true,
  "followup_endpoints": [],
  "navigation_steps": [],
  "current_view": "...",
  "target_ready": true,
  "raw_html_len": 0,
  "source_url": "..."
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
	PROVIDER_AUTH_FAILED	인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.
	PROVIDER_VALIDATION_ERROR	검증 오류 — 보낸 파라미터 값을 기관이 거부했습니다. 값을 확인합니다.

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

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

4대보험 EDI 기관별 공지사항 첨부파일 목록 조회 업무를 위해 기관 공지에 첨부된 파일 목록과 다운로드 링크를 조회합니다.

로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
첨부가 없으면 files 가 빈 배열, file_count 가 0 으로 옵니다. 실패가 아닙니다.
sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

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

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

순번	변수명	타입	필수	설명
	pst_sn	string	Y	게시글 일련번호 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: sandbox' \
  --header 'Idempotency-Key: demo-attachments-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.resources.notices.institutions.attachments",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "pst_sn": "<필수>"
  }
}'

Response

result.data 의 files 와 file_count 로 첨부 목록을 확인합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	pst_sn	게시글 일련번호
	file_count	첨부파일 수
	files	첨부파일 메타 배열
	source_url	업스트림 요청 URL

json

// result.data
{
  "success": true,
  "pst_sn": "...",
  "file_count": 1,
  "files": [],
  "source_url": "..."
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
	PROVIDER_AUTH_FAILED	인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.
	PROVIDER_VALIDATION_ERROR	검증 오류 — 보낸 파라미터 값을 기관이 거부했습니다. 값을 확인합니다.

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

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

국민연금과 건강보험, 고용보험, 산재보험 기관과 정보연계센터가 올린 공지 한 건을 골라 제목과 본문 표 항목, 함께 붙어 있는 첨부파일 목록까지 한 번에 받아 담당 부서에 그대로 공유할 수 있습니다.

로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

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

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

순번	변수명	타입	필수	설명
	pst_sn	string	Y	게시글 일련번호 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: sandbox' \
  --header 'Idempotency-Key: demo-detail-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.resources.notices.institutions.detail",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "pst_sn": "<필수>"
  }
}'

Response

result.data 의 detail 에 본문이 담깁니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	pst_sn	게시글 일련번호
	detail	상세 본문 객체
	raw_html_len	원본 HTML 길이
	source_url	업스트림 요청 URL

json

// result.data
{
  "success": true,
  "pst_sn": "...",
  "detail": {},
  "raw_html_len": 0,
  "source_url": "..."
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
	PROVIDER_AUTH_FAILED	인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.
	PROVIDER_VALIDATION_ERROR	검증 오류 — 보낸 파라미터 값을 기관이 거부했습니다. 값을 확인합니다.

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

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

국민연금과 건강보험, 고용보험, 산재보험 기관 공지사항을 검색합니다.

로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
조회 결과가 없으면 items 가 빈 배열, row_count 가 0 으로 옵니다. 실패가 아닙니다.
sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

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

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

변수명	타입	필수	설명
current_page_no	number	N	페이지 번호 currentPageNo. 기본 1
srch_inst	string	N	기관 검색 srchInst
srch_opt	string	N	검색 옵션 srchOpt
srch_txt	string	N	검색어 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: sandbox' \
  --header 'Idempotency-Key: demo-list-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.resources.notices.institutions.list",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

result.data 의 items 와 row_count 로 조회 결과를 확인합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	row_count	목록 건수
	items	조회 결과 행 배열
	query	적용된 검색 조건 맵
	source_url	업스트림 요청 URL

json

// result.data
{
  "success": true,
  "row_count": 1,
  "items": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "query": {},
  "source_url": "..."
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
	PROVIDER_AUTH_FAILED	인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.
	PROVIDER_VALIDATION_ERROR	검증 오류 — 보낸 파라미터 값을 기관이 거부했습니다. 값을 확인합니다.

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

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

국민연금과 건강보험, 고용보험, 산재보험 기관과 정보연계센터가 올린 공지를 찾기 전에 검색 화면에서 고를 수 있는 기관과 검색 방식, 검색어 입력 항목을 미리 확인해 조회 조건을 정확히 맞춥니다.

로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

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

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `fourinsure`이 API 고정값 (기본값) 예시 : fourinsure
action	string	-	Y	호출할 작업입니다. `fourinsure.b1.resources.notices.institutions.list_init`이 API 고정값 (기본값) 예시 : fourinsure.b1.resources.notices.institutions.list_init
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	N	작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fields	object	-	N	민감한 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: sandbox' \
  --header 'Idempotency-Key: demo-list_init-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.resources.notices.institutions.list_init",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

result.data 에서 입력 항목(fields)과 다음 단계 정보를 확인해 후속 요청 본문을 만듭니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	page	화면 페이지 메타 객체
	forms	form 메타데이터 배열
	fields	입력 필드 계약 배열
	semantic_fields	의미 단위 입력 컨트롤 배열
	semantic_payload	의미 필드 키-값 맵
	semantic_field_count	의미 필드 개수
	csrf_token_present	CSRF 토큰 존재 여부
	followup_endpoints	후속 endpoint URL 배열
	navigation_steps	화면 내비게이션 단계 배열
	current_view	현재 화면 식별자
	target_ready	대상 폼 준비 여부
	raw_html_len	원본 HTML 길이
	source_url	업스트림 요청 URL

json

// result.data
{
  "success": true,
  "page": {},
  "forms": [],
  "fields": [],
  "semantic_fields": [],
  "semantic_payload": {},
  "semantic_field_count": 1,
  "csrf_token_present": true,
  "followup_endpoints": [],
  "navigation_steps": [],
  "current_view": "...",
  "target_ready": true,
  "raw_html_len": 0,
  "source_url": "..."
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
	PROVIDER_AUTH_FAILED	인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.
	PROVIDER_VALIDATION_ERROR	검증 오류 — 보낸 파라미터 값을 기관이 거부했습니다. 값을 확인합니다.