개발자 문서
API 레퍼런스

공공자료 - 국민건강보험공단 EDI

1. 전체서식 화면 정보 조회nhis_edi.public.forms.list

MCP 도구 이름 nhis_edi__public__forms__list

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

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

연동 계정으로 부르면 전체서식 화면의 화면 번호와 그 메뉴로 가는 연결 번호를 받습니다. 실제 파일 다운로드는 하지 않습니다.

  • 로그인을 먼저 호출합니다. 이 API 는 세션만 있으면 되고 업무 화면 진입은 필요하지 않습니다. [국민건강보험공단 EDI 로그인]
  • 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추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • nhis_edi이 API 고정값 (기본값)

예시 : nhis_edi

actionstring-Y호출할 작업입니다.
  • nhis_edi.public.forms.list이 API 고정값 (기본값)

예시 : nhis_edi.public.forms.list

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

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-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: real_test' \
  --header "Idempotency-Key: list-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nhis_edi",
  "action": "nhis_edi.public.forms.list",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • download_contract 확인. implementation_status=form_download_contract_only, row_count=0.
순번변수명타입설명
successboolean처리 성공 여부
feature_namestring기능 식별자
phasestring단계(이 액션은 list)
workflow_stepstring워크플로 단계
screen_idstring화면 식별자
route_kindstring라우트 종류
row_countnumber반환 행 수(이 액션은 항상 0)
rowsarray조회 행(이 액션은 항상 빈 배열)
download_contractobject서식 다운로드 계약 정보 객체
source_evidenceobject출처 증적 객체
error_codenull오류 코드(문제가 없으면 null)
implementation_statusstring구현 상태(이 액션은 서식 다운로드 계약만 돌려줘서 항상 form_download_contract_only)
json
// result.data
{
  "success": true,
  "feature_name": "...",
  "phase": "list",
  "workflow_step": "public_forms_contract_loaded",
  "screen_id": "...",
  "route_kind": "live_session_contract",
  "row_count": 0,
  "rows": [],
  "download_contract": {
    "page_link_id": "100",
    "program_id": "...",
    "safe": true,
    "mutating": false,
    "note": "서식 다운로드 화면은 조회/다운로드 전용 화면이다. 파일 다운로드 실행은 별도 download API로 분리해야 한다."
  },
  "source_evidence": {
    "screenshot": "...",
    "xfdl": "...",
    "target_context_ready": true
  },
  "error_code": null,
  "implementation_status": "form_download_contract_only"
}

2. 대외 공지사항 목록 조회nhis_edi.public.notices.list

MCP 도구 이름 nhis_edi__public__notices__list

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

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

쪽 번호를 넣으면 대외 공지사항 게시판 그 쪽의 글마다 번호나 공지 표시, 제목, 등록일과 글 주소를 받고, 첨부가 있으면 첨부 안내도 받습니다.

  • 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
  • implementation_status=public_html_rows_empty.
  • success=false. result.data.error_code=PUBLIC_HTML_HTTP_ERROR.
  • params 는 빈 객체로 보내도 호출됩니다. page 는 기본값이 1 입니다.

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호출할 기관입니다.
  • nhis_edi이 API 고정값 (기본값)

예시 : nhis_edi

actionstringY호출할 작업입니다.
  • nhis_edi.public.notices.list이 API 고정값 (기본값)

예시 : nhis_edi.public.notices.list

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

[참고] 암호화

순번변수명타입필수설명
pagenumberN페이지 번호
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": "nhis_edi",
  "action": "nhis_edi.public.notices.list",
  "params": {}
}'

Response

  • rows·source_url·status_code 확인.
순번변수명타입설명
successboolean게시판 응답이 정상(HTTP 400 미만)인지 여부
feature_namestring기능 식별자
phasestring단계(이 액션은 list)
workflow_stepstring워크플로 단계
screen_idstring화면 식별자
route_kindstring라우트 종류
source_urlstring조회한 게시판 주소
status_codenumber | null게시판 응답의 HTTP 상태 코드
row_countnumber결과 행 수
rowsarray게시판 행 목록
source_evidenceobject출처 증적 객체
error_codestring | null오류 코드(정상이면 null, HTTP 400 이상이면 PUBLIC_HTML_HTTP_ERROR)
implementation_statusstring | null구현 상태(행이 있으면 null, 한 건도 없으면 public_html_rows_empty - 마지막 페이지 뒤를 조회해도 정상입니다)
json
// result.data
{
  "rows": [
    {
      "href": "https://...",
      "cells": [
        "공지",
        "[공지] 웹EDI 가입 및 업무처리 매뉴얼",
        "2026.09.14",
        "첨부파일 첨부파일 웹EDI 매뉴얼(26.9.).pdf 첨부파일 목록 닫기"
      ],
      "title": "[공지] 웹EDI 가입 및 업무처리 매뉴얼",
      "row_index": 0
    },
    {
      "href": "https://...",
      "cells": [
        "44",
        "2025년도 귀속분 국세청 근로소득자료 연계에 따른 정산보험료 고지예정 안내",
        "2026.08.28"
      ],
      "title": "2025년도 귀속분 국세청 근로소득자료 연계에 따른 정산보험료 고지예정 안내",
      "row_index": 1
    },
    {
      "href": "https://...",
      "cells": [
        "43",
        "국민건강보험공단 사칭 악성문자 유포 주의",
        "2026.08.24"
      ],
      "title": "국민건강보험공단 사칭 악성문자 유포 주의",
      "row_index": 2
    },
    {
      "href": "https://...",
      "cells": [
        "42",
        "국민건강보험공단 '점심시간 휴무제' 시범운영 실시 안내",
        "2026.06.16"
      ],
      "title": "국민건강보험공단 '점심시간 휴무제' 시범운영 실시 안내",
      "row_index": 3
    },
    {
      "href": "https://...",
      "cells": [
        "41",
        "외국인근로자 장기요양보험 가입제외 가능 체류코드 추가 안내",
        "2026.05.19"
      ],
      "title": "외국인근로자 장기요양보험 가입제외 가능 체류코드 추가 안내",
      "row_index": 4
    },
    {
      "href": "https://...",
      "cells": [
        "40",
        "2025년도 귀속 개인사업장 사용자 건강보험료 연말정산 실시 안내",
        "2026.05.12"
      ],
      "title": "2025년도 귀속 개인사업장 사용자 건강보험료 연말정산 실시 안내",
      "row_index": 5
    },
    {
      "href": "https://...",
      "cells": [
        "39",
        "휴직자 등 납입고지 유예(해지예정일 변경, 해지)신청 관련 변경사항 안내",
        "2026.05.12"
      ],
      "title": "휴직자 등 납입고지 유예(해지예정일 변경, 해지)신청 관련 변경사항 안내",
      "row_index": 6
    },
    {
      "href": "https://...",
      "cells": [
        "38",
        "2026년 사업장 건강검진 실시안내",
        "2026.03.23",
        "첨부파일 첨부파일 1. 사업장 건강(암) 검진 대상자 변경(추가) 신청서.hwp 2. 사업장 건강(암) 검진 대상자 변경(제외) 신청서.hwp 3. 건강검진 대상자 확인서(검진기관제시용).hwp 4. 2026년 건강검진 실시안내(사업장담당자용).pdf 첨부파일 목록 닫기"
      ],
      "title": "2026년 사업장 건강검진 실시안내",
      "row_index": 7
    },
    {
      "href": "https://...",
      "cells": [
        "37",
        "공단 사칭 메일 주의 안내",
        "2026.03.17"
      ],
      "title": "공단 사칭 메일 주의 안내",
      "row_index": 8
    },
    {
      "href": "https://...",
      "cells": [
        "36",
        "2026년도 건강·장기요양보험료율 인상 안내",
        "2025.12.18",
        "첨부파일 첨부파일 (붙임1) 2026년도 보험료율 안내(한글).pdf (붙임2) 2026년도 보험료율 안내(영문).pdf 첨부파일 목록 닫기"
      ],
      "title": "2026년도 건강·장기요양보험료율 인상 안내",
      "row_index": 9
    },
    {
      "href": "https://...",
      "cells": [
        "35",
        "연금보험료율 인상 안내",
        "2025.12.02"
      ],
      "title": "연금보험료율 인상 안내",
      "row_index": 10
    }
  ],
  "phase": "list",
  "success": true,
  "row_count": 11,
  "screen_id": "portal_html",
  "error_code": null,
  "route_kind": "live",
  "source_url": "https://...",
  "status_code": 200,
  "feature_name": "...",
  "workflow_step": "public_notices_loaded",
  "source_evidence": {
    "html_len": 24007,
    "final_url": "https://...",
    "source_note": "...",
    "content_type": "..."
  },
  "implementation_status": null
}

3. 공개 자료실 목록 조회nhis_edi.public.resources.list

MCP 도구 이름 nhis_edi__public__resources__list

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

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

쪽 번호로 공개 자료실 게시판의 한 쪽을 읽어 자료마다 번호나 공지 표시, 제목, 등록일과 글 주소를 돌려주고, 첨부가 있는 자료에는 첨부 안내가 붙습니다.

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

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호출할 기관입니다.
  • nhis_edi이 API 고정값 (기본값)

예시 : nhis_edi

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

예시 : nhis_edi.public.resources.list

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

[참고] 암호화

순번변수명타입필수설명
pagenumberN페이지 번호
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": "nhis_edi",
  "action": "nhis_edi.public.resources.list",
  "params": {}
}'

Response

  • rows·source_url 확인.
순번변수명타입설명
successboolean게시판 응답이 정상(HTTP 400 미만)인지 여부
feature_namestring기능 식별자
phasestring단계(이 액션은 list)
workflow_stepstring워크플로 단계
screen_idstring화면 식별자
route_kindstring라우트 종류
source_urlstring조회한 게시판 주소
status_codenumber | null게시판 응답의 HTTP 상태 코드
row_countnumber결과 행 수
rowsarray게시판 행 목록
source_evidenceobject출처 증적 객체
error_codestring | null오류 코드(정상이면 null, HTTP 400 이상이면 PUBLIC_HTML_HTTP_ERROR)
implementation_statusstring | null구현 상태(행이 있으면 null, 한 건도 없으면 public_html_rows_empty - 마지막 페이지 뒤를 조회해도 정상입니다)
json
// result.data
{
  "rows": [
    {
      "href": "https://...",
      "cells": [
        "공지",
        "[공지] 웹EDI 가입 및 업무처리 매뉴얼",
        "2026.09.14",
        "첨부파일 첨부파일 웹EDI 매뉴얼(26.9.).pdf 첨부파일 목록 닫기"
      ],
      "title": "[공지] 웹EDI 가입 및 업무처리 매뉴얼",
      "row_index": 0
    },
    {
      "href": "https://...",
      "cells": [
        "공지",
        "[공지] 1인 업무대행기관 웹EDI 가입 매뉴얼",
        "2026.03.16",
        "첨부파일 첨부파일 1인 업무대행기관 매뉴얼.pdf 첨부파일 목록 닫기"
      ],
      "title": "[공지] 1인 업무대행기관 웹EDI 가입 매뉴얼",
      "row_index": 1
    },
    {
      "href": "https://...",
      "cells": [
        "공지",
        "[공지] 2026년도 사업장 업무편람",
        "2026.01.16",
        "첨부파일 첨부파일 2026년 건강보험 사업장 업무편람(게시용).pdf 첨부파일 목록 닫기"
      ],
      "title": "[공지] 2026년도 사업장 업무편람",
      "row_index": 2
    },
    {
      "href": "https://...",
      "cells": [
        "공지",
        "[공지] 웹EDI 신고화면 등 새창이 안열리는 경우 브라우저 설정 방법",
        "2025.05.08"
      ],
      "title": "[공지] 웹EDI 신고화면 등 새창이 안열리는 경우 브라우저 설정 방법",
      "row_index": 3
    },
    {
      "href": "https://...",
      "cells": [
        "공지",
        "[공지] 건설현장 사업장 건강보험 실무안내(202502)",
        "2025.04.09",
        "첨부파일 첨부파일 건설현장_사업장_건강보험_실무안내(2025.2.).pdf 첨부파일 목록 닫기"
      ],
      "title": "[공지] 건설현장 사업장 건강보험 실무안내(202502)",
      "row_index": 4
    },
    {
      "href": "https://...",
      "cells": [
        "공지",
        "[공지] 건강보험 관련 각종 서식 다운로드 경로 안내",
        "2023.12.29"
      ],
      "title": "[공지] 건강보험 관련 각종 서식 다운로드 경로 안내",
      "row_index": 5
    },
    {
      "href": "https://...",
      "cells": [
        "5",
        "[공지] 건강보험 EDI 업무대행 위임처리기준(202604)",
        "2026.07.03",
        "첨부파일 첨부파일 웹EDI 업무대행 위임 처리기준_260401.pdf 첨부파일 목록 닫기"
      ],
      "title": "[공지] 건강보험 EDI 업무대행 위임처리기준(202604)",
      "row_index": 6
    },
    {
      "href": "https://...",
      "cells": [
        "4",
        "일용근로자 국민연금 사업장 실무안내 매뉴얼",
        "2025.06.11",
        "첨부파일 첨부파일 일용근로자 국민연금 사업장 실무안내.pdf 첨부파일 목록 닫기"
      ],
      "title": "일용근로자 국민연금 사업장 실무안내 매뉴얼",
      "row_index": 7
    },
    {
      "href": "https://...",
      "cells": [
        "3",
        "건강보험 EDI 파일신고 시 활용하는 파일사양서",
        "2024.01.11",
        "첨부파일 첨부파일 EDI 전자신고 파일사양서 설명서.pptx 웹EDI_파일신고_파일사양서(엑셀).zip 첨부파일 목록 닫기"
      ],
      "title": "건강보험 EDI 파일신고 시 활용하는 파일사양서",
      "row_index": 8
    },
    {
      "href": "https://...",
      "cells": [
        "2",
        "(영상)건강보험 건설일용근로자 가입기준 및 사례별 예시",
        "2021.11.23"
      ],
      "title": "(영상)건강보험 건설일용근로자 가입기준 및 사례별 예시",
      "row_index": 9
    },
    {
      "href": "https://...",
      "cells": [
        "1",
        "EDI 모사업장정보 확인방법 안내",
        "2016.12.06",
        "첨부파일 첨부파일 등록16.12.6._모사업장_확인_방법_안내.pdf 첨부파일 목록 닫기"
      ],
      "title": "EDI 모사업장정보 확인방법 안내",
      "row_index": 10
    }
  ],
  "phase": "list",
  "success": true,
  "row_count": 11,
  "screen_id": "portal_html",
  "error_code": null,
  "route_kind": "live",
  "source_url": "https://...",
  "status_code": 200,
  "feature_name": "...",
  "workflow_step": "public_resources_loaded",
  "source_evidence": {
    "html_len": 26364,
    "final_url": "https://...",
    "source_note": "...",
    "content_type": "..."
  },
  "implementation_status": null
}