파일신고 - 국민건강보험공단 EDI
1. 파일신고 입력 서식 조회nhis_ edi. file_ report. init
MCP 도구 이름 nhis_
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
로그인한 연동 계정으로 파일신고에 쓸 수 있는 서식 다섯 가지와 기본 서식, 올릴 수 있는 파일 형식, 신고 자료 표의 열을 받습니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [국민건강보험공단 EDI 로그인]
- 파일열기·자료검증·전송/신고 미실행. JGBA_021I_SND 등 blocked_transactions에만 기록.
- 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 | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| 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: init-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "nhis_edi",
"action": "nhis_edi.file_report.init",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- supported_documents·file_inputs·safety·blocked_transactions 확인.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| API_ | string | 이 호출에 쓴 연동 계정의 ID(account_link_id)입니다. XBOSS API 키가 아닙니다. | |
| supported_ | array | 지원 문서 양식 목록 배열 | |
| file_ | array | 파일 입력 계약 배열 | |
| safety | object | 안전 플래그 객체 | |
| blocked_ | array | 차단된 트랜잭션 목록 (실행 안 됨) | |
| form_ | string | 기관 화면 폼 id | |
| document_ | string | 기관 화면 문서 id | |
| business_ | object | 사업장 기본 맥락 값 | |
| default_ | object | 화면 기본값 | |
| datasets | array | 기관 응답 데이터셋 원본 | |
| dataset_ | number | 데이터셋 수 | |
| datasets_ | array | 업무에 쓰는 데이터셋 이름 | |
| fields | array | 입력 필드 정의 배열 | |
| field_ | number | 입력 필드 수 | |
| grid | object | 표 구성 (열 이름과 열 수) | |
| init_ | array | 화면 초기 트랜잭션 목록 | |
| local_ | array | 제출 전 로컬 검증 단계 | |
| observed_ | array | 화면에서 관찰한 service 호출 목록 | |
| script_ | string | 화면 XFDL JavaScript URL | |
| shortcut | string | 화면을 여는 바로가기 호출식(pageLinkPopup1 등) | |
| source_ | string | 원천 NHIS EDI URL | |
| target_ | boolean | 화면 진입 준비 완료 여부 | |
| visible_ | array | 화면 확인용 고정 문구 |
// result.data
{
"grid": {
"name": "grd_List",
"columns": [
"BCH_YN",
"CHILD_BDAY",
"CHILD_SEX",
"DIV_CHASU",
"JUMIN_NO",
"JUNG_NO",
"NM",
"REINST_DIR_RETR_YN",
"REINST_DT",
"REINST_FEE_MM_AMT",
"REINST_SCD_DT",
"REST_END_DT1",
"REST_END_DT2",
"REST_END_DT3",
"REST_KIND_CD1",
"REST_KIND_CD2",
"REST_KIND_CD3",
"REST_PERD_FEE_AMT1",
"REST_PERD_FEE_AMT2",
"REST_PERD_FEE_AMT3",
"REST_PERD_FEE_AMT4",
"REST_PERD_FEE_AMT5",
"REST_STRT_DT1",
"REST_STRT_DT2",
"REST_STRT_DT3",
"REST_YEAR1",
"REST_YEAR2",
"REST_YEAR3",
"REST_YEAR4",
"REST_YEAR5",
"RPT_TYPE",
"SAYU_CD",
"SEQ_NO",
"TRET_DT"
],
"dataset": "...",
"column_count": 34
},
"phase": "init",
"fields": [
{
"mask": null,
"name": "cbo_DocId",
"text": null,
"type": "Combo",
"column": null,
"dataset": null,
"enabled": null,
"readonly": null,
"innerdataset": "..."
}
],
"safety": {
"warning": "이 API는 파일신고 화면 contract/init 응답만 제공하며 파일열기, 자료검증, 전송/신고를 실행하지 않는다.",
"init_only": true,
"allowed_transaction_cmds": [
"GetCnstInfo",
"GetCommCombo2"
],
"blocked_transaction_cmds": [
"JGBA_021I_SND",
"JGBB_031I_SND",
"JGCB_040_I",
"JGBA_010_I",
"BMCC_080_I02_1"
],
"mutating_actions_executed": false
},
"API_KEY": "[REDACTED]",
"form_id": "frm_WETC_120",
"success": true,
"datasets": [
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"...",
"..."
],
"shortcut": "pageLinkPopup1('120')",
"screen_id": "...",
"program_id": "...",
"route_kind": "live_session_contract",
"script_url": "https://...",
"source_url": "https://...",
"document_id": "WETC_120",
"field_count": 1,
"file_inputs": [
{
"key": "document_code",
"label": "서식명",
"dataset": "...",
"required": true
},
{
"key": "file",
"label": "신고 파일",
"required": true,
"accepted_extensions": [
"CELL",
"XLS",
"XLSX",
"TXT"
]
}
],
"feature_name": "...",
"page_link_id": "120",
"target_ready": true,
"dataset_count": 37,
"workflow_step": "file_report_form_contract_loaded",
"default_values": {
"WRT_CHASU": "20260615ZZ",
"작성일": "2026-06-15",
"default_document_code": "A"
},
"source_evidence": {},
"business_context": {
"firm_sym": null,
"firm_name": null,
"unit_firm_sym": null,
"nhic_bslc_mgmt_no": "",
"firm_management_no": null,
"target_context_ready": false,
"session_cookie_context_ready": false
},
"init_transactions": [
{
"cmd": "GetCnstInfo",
"in_ds": "...",
"action": "COMMONAction",
"effect": "건설현장/사업장 보조 정보 조회",
"out_ds": "...",
"mutates": false
},
{
"cmd": "GetCommCombo2",
"in_ds": "...",
"action": "COMMONAction",
"effect": "서식별 검증 코드/콤보 조회",
"mutates": false
}
],
"supported_documents": [
{
"code": "4",
"label": "직장가입자 근무처/근무내역 등 변동통보서",
"send_cmd": "JGCB_040_I",
"send_action": "JGCB_040Action",
"input_dataset": "..."
},
{
"code": "6",
"label": "휴직자등 직장가입자 보험료 납입 고지 유예 신청서",
"send_cmd": "BMCC_080_I02_1",
"send_action": "BMCC_080Action",
"input_dataset": "..."
},
{
"code": "7",
"label": "피부양자 자격(취득,상실) 신고서",
"send_cmd": "JGBA_010_I",
"send_action": "JGBA_010Action",
"input_dataset": "..."
},
{
"code": "A",
"label": "사업장(직장) 가입자 자격취득 신고서(통합)",
"send_cmd": "JGBA_021I_SND",
"send_action": "JGBA_021Action",
"input_dataset": "..."
},
{
"code": "B",
"label": "사업장(직장) 가입자 자격상실 신고서(통합)",
"send_cmd": "JGBB_031I_SND",
"send_action": "JGBB_031Action",
"input_dataset": "..."
}
],
"blocked_transactions": [
{
"cmd": "JGBA_021I_SND",
"action": "JGBA_021Action",
"reason": "실제 자격취득 통합 파일 신고 접수"
},
{
"cmd": "JGBB_031I_SND",
"action": "JGBB_031Action",
"reason": "실제 자격상실 통합 파일 신고 접수"
},
{
"cmd": "JGCB_040_I",
"action": "JGCB_040Action",
"reason": "실제 근무처/근무내역 변동 파일 신고 접수"
},
{
"cmd": "JGBA_010_I",
"action": "JGBA_010Action",
"reason": "실제 피부양자 자격 파일 신고 접수"
},
{
"cmd": "BMCC_080_I02_1",
"action": "BMCC_080Action",
"reason": "실제 휴직자 보험료 납입 고지 유예 파일 신고 접수"
},
{
"button": "파일열기",
"reason": "사용자 로컬 파일 내용이 ...에 적재됨"
},
{
"button": "자료검증",
"reason": "파일 행 단위 검증 결과가 화면 상태에 반영됨"
},
{
"button": "전송/신고",
"reason": "공단에 실제 대량 신고 접수 발생"
}
],
"datasets_of_interest": [
{
"name": "...",
"purpose": "파일신고 지원 서식 목록"
},
{
"name": "...",
"purpose": "불러온 파일 원본/검증 대상 행"
},
{
"name": "...",
"purpose": "통합 자격취득/상실 전송 대상 행"
},
{
"name": "...",
"columns": [
"RowNo",
"Desc"
],
"purpose": "파일 검증 오류 목록"
},
{
"name": "...",
"purpose": "신청/해지/신청+해지/유예 구분"
},
{
"name": "...",
"purpose": "건설현장/사업장 정보"
},
{
"name": "...",
"purpose": "건설현장 정보 조회 조건"
},
{
"name": "...",
"purpose": "공통 코드 조회 조건"
}
],
"visible_text_markers": [
"서식명 : ",
"※ 고용보험/산재보험 자료는 이직확인서를 입력하지 않을 자료만 입력하세요"
],
"implementation_status": "implemented_init_form_contract_only",
"observed_callservices": [
{
"cmd": "GetCnstInfo",
"in_ds": "...",
"action": "COMMONAction",
"out_ds": "..."
},
{
"cmd": "JGBA_021I_SND",
"in_ds": "...",
"action": "JGBA_021Action",
"out_ds": "..."
},
{
"cmd": "JGCB_040_I",
"in_ds": "...",
"action": "JGCB_040Action",
"out_ds": "..."
},
{
"cmd": "JGBA_010_I",
"in_ds": "...",
"action": "JGBA_010Action",
"out_ds": "..."
},
{
"cmd": "BMCC_080_I02_1",
"in_ds": "...",
"action": "BMCC_080Action",
"out_ds": "..."
},
{
"cmd": "JGBB_031I_SND",
"in_ds": "...",
"action": "JGBB_031Action",
"out_ds": "..."
}
],
"local_validation_steps": [
{
"step": "file_select",
"label": "파일열기",
"effect": "로컬 파일을 ...로 로드"
},
{
"step": "file_import",
"label": "파일 변환",
"effect": "CELL/XLS/XLSX/TXT 서식을 화면 dataset으로 변환"
},
{
"step": "validate",
"label": "자료검증",
"effect": "...에 행별 오류 적재"
}
]
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. |