HIRA e-Form 업로더BY SODAMSOFT · HANICARE

USER GUIDE · v4.36.1

설치부터 전송까지,
차근차근 시작하세요.

프로그램에 표시되는 실제 메뉴를 기준으로 안내합니다.
먼저 00번에서 HIRA Agent 설치·로그인을 준비해 주세요.
업로더를 처음 설치한다면 01번, 기존 EXE 사용자는 02번으로 이어서 진행합니다.

00 · HIRA E-FORM AGENT

HIRA e-Form 설치·로그인부터 준비하기

심평원의 HIRA e-Form Agent와 소담소프트의 HIRA e-Form 업로더는 서로 다른 프로그램입니다. 먼저 전송할 Windows PC에 Agent를 설치하고 공동인증서 로그인과 WebAPI 설정을 완료해 주세요.

1. 심평원 공식 사이트에서 Agent 설치

  1. HIRA e-Form 공식 사이트 열기 ↗로 접속합니다.
  2. Agent 다운로드 또는 개발가이드 및 Agent다운로드 안내에서 Windows용 Agent 설치파일을 받습니다. 사이트 화면과 메뉴는 개편에 따라 다를 수 있습니다.
  3. 공식 설치 안내에 따라 설치하고 Agent를 실행합니다. 이미 설치되어 있다면 중복 설치 전에 실행 여부를 확인합니다.
  4. Windows 작업 표시줄 오른쪽 알림 영역에서 HIRA e-Form Agent 아이콘을 찾습니다. 보이지 않으면 숨겨진 아이콘 목록도 확인해 주세요.

설치 출처: 심평원 HIRA e-Form 시스템 · 심평원 공식 Agent 다운로드 안내(PDF). 아래 이미지는 제공된 화면 예시로, Agent 버전에 따라 배치가 다를 수 있습니다.

2. 기관 공동인증서로 로그인

  1. Agent 트레이 아이콘을 마우스 오른쪽 버튼으로 눌러 HIRA e-Form Agent 로그인을 선택합니다.
  2. 로그인 창에 해당 기관의 요양기관기호(기관코드)를 입력하거나 표시된 값이 맞는지 확인합니다.
  3. 공동인증서 로그인을 누르고 기관에서 사용하는 인증서로 로그인합니다. 인증서 선택과 비밀번호 입력은 심평원 인증 창에서 진행합니다.
오른쪽 트레이 메뉴의 HIRA e-Form Agent 로그인 항목과 왼쪽 공동인증서 로그인 창. 기관코드 입력란은 가려져 있습니다.
오른쪽 트레이 메뉴에서 로그인을 선택하면 왼쪽 로그인 창이 열립니다. 기관코드는 비공개 처리했습니다. 이미지를 누르면 크게 볼 수 있습니다.
Agent 로그인과 업로더 API KEY 설정은 별개입니다.

공동인증서와 비밀번호는 심평원 Agent에서만 사용합니다. 이 안내 페이지에 인증서나 기관코드, 비밀번호를 입력하지 마세요.

3. Agent 환경설정에서 WebAPI 사용

  1. Agent 트레이 메뉴의 환경설정을 엽니다.
  2. 전송서버 설정과 오른쪽 위 요양기관기호를 확인합니다. 아래 예시는 실제 업무용 운영 서버입니다. 검증용 환경을 사용하는 기관은 담당자의 안내를 따르세요.
  3. 개발자 설정 → WebAPI 사용을 체크하고, 바로 옆 Port를 1707로 맞춥니다. 위쪽 전송서버의 Port 입력란과 혼동하지 마세요.
  4. 오른쪽 아래 저장을 누릅니다. Agent에서 재시작을 안내하면 작업을 마친 뒤 재시작하고 로그인 상태를 다시 확인합니다.
  5. PC를 켤 때 Agent도 실행하려면 윈도우 시작시 자동실행을 선택합니다. 자동 실행이 공동인증서 로그인 완료까지 보장하는 것은 아닙니다.
HIRA e-Form Agent 환경설정 예시. 개발자 설정의 WebAPI 사용이 선택되어 있고 Port는 1707이며 오른쪽 아래에 저장 버튼이 있습니다. 오른쪽 위 요양기관기호는 가려져 있습니다.
하단 개발자 설정의 WebAPI 사용·Port 1707을 확인하고 저장합니다. 오른쪽 위 기관코드는 비공개 처리했습니다. 다른 항목을 모두 예시와 똑같이 변경할 필요는 없습니다.
업로더의 기본 Agent 연결 주소는 http://localhost:1707입니다.

Agent와 업로더를 같은 PC에서 실행하고 WebAPI 포트를 맞춰 주세요. 이 절차를 위해 1707 포트를 인터넷에 공개할 필요는 없습니다.

4. 업로더 설치 후 연결 확인

아래 업로더 설치와 기관·API 설정까지 마친 뒤 도구 → HIRA Agent 상태 확인(F7)을 실행합니다. 연결과 로그인 상태를 확인한 후 업무 자료를 전송하세요. 연결 확인을 위해 실제 환자자료를 전송하지 마세요.

01 · INSTALL

처음 설치하기

  1. Windows x64 PC를 준비합니다.
    HIRA e-Form Agent 설치·로그인·WebAPI 설정을 먼저 완료합니다. 업로더와 Agent는 같은 PC에서 실행해 주세요.
  2. 설치파일을 다운로드합니다.
    HiraEFormUploader-win-Setup.exe 다운로드
  3. 다운로드한 Setup.exe를 실행합니다.
    .NET 런타임이 포함되어 있어 별도로 .NET SDK를 설치할 필요는 없습니다.
  4. 설치된 HIRA e-Form 업로더를 실행합니다.
    기존 EXE를 사용한 적이 있다면 다음 항목의 데이터 이전을 먼저 진행합니다. 처음 사용한다면 기관 설정으로 이동합니다.
  5. 도움말 → 프로그램 정보에서 버전을 확인합니다.
    이 안내는 v4.36.1 기준입니다.
업로더와 HIRA Agent는 별개의 프로그램입니다.

업로더를 설치해도 HIRA e-Form Agent가 함께 설치되지는 않습니다. 기관에서 사용하는 Agent를 먼저 준비해 주세요.

현재 설치파일은 미서명 상태입니다.

Windows에서 게시자 확인 또는 보안 경고가 표시될 수 있습니다. sodamsoft.com에서 받은 파일인지 확인하고, 설치 여부가 불확실하면 기관 담당자에게 문의하세요. 기관의 보안 정책을 확인한 뒤 진행해 주세요.

02 · MIGRATION

기존 EXE의 데이터를 가져오기

설치 없이 EXE를 실행하던 사용자를 위한 절차입니다. 같은 PC·같은 Windows 사용자 계정으로 진행해 주세요.

  1. 기존 프로그램을 완전히 종료합니다.
    닫기(X)는 종료가 아닙니다. 기존 프로그램의 파일 → 프로그램 종료 또는 트레이 메뉴 → 프로그램 종료를 선택합니다.
  2. 기존 EXE 옆의 data 폴더를 별도로 백업합니다.
    설정과 대기·완료·실패 자료가 들어 있습니다.
  3. Setup.exe를 설치한 뒤 첫 실행에서 기존 데이터 가져오기를 선택합니다.
    폴더 선택 창에서 기존 EXE 옆의 data 폴더를 지정하세요.
  4. 복사가 완료된 뒤 설정과 대기열을 확인합니다.
    원본 data 폴더는 삭제하지 않습니다. 전체 복사가 끝난 뒤 새 데이터 경로를 사용합니다.
  5. 이후에는 설치된 프로그램만 실행합니다.
    기존 EXE와 설치된 프로그램을 동시에 실행해 같은 자료를 처리하지 않도록 확인하세요.
이미 새 경로에 데이터가 있다면

기존 자료를 자동으로 병합하거나 덮어쓰지 않습니다. 기존 자료가 표시되는지 먼저 확인하고, 잘못된 폴더를 선택했다면 임의로 지우지 말고 담당자에게 문의해 주세요.

이전 경로 %LOCALAPPDATA%\HiraEFormUploader\data에 설정이 있는 경우에는 새 경로로 자동 복사를 시도합니다.

API KEY 암호화는 Windows 사용자 계정에 연결됩니다. 다른 PC나 다른 계정으로 옮겼다면 도구 → 설정에서 API KEY를 다시 입력하세요. 실패한 .migration-* 폴더는 복구용으로 남을 수 있습니다.

03 · SETTINGS

업로더의 기관·API 정보 설정하기

아래는 소담소프트 업로더의 설정입니다. 심평원 Agent의 환경설정은 앞의 Agent 설정 안내를 참고해 주세요.

도구 → 설정을 열고 다음 정보를 입력한 뒤 저장합니다. 트레이 메뉴의 설정으로도 열 수 있습니다.

설정 탭입력 내용
HIRA e-Form Agent요양기관기호, 기관명, 기본 서식ID를 기관에서 사용하는 값으로 입력합니다. 서식ID를 모르면 기관 담당자에게 확인해 주세요.
Hanicare 환자 API하니케어 기관 설정에서 발급받은 x-api-key를 입력합니다. 조회가 지연되는 환경에서는 타임아웃을 조정할 수 있습니다.
자동 실행 스케줄예약 전송을 사용할 때만 활성화하고 요일과 시간을 지정합니다. 예약 실행 안내를 먼저 확인하세요.
  1. 기관의 Agent를 실행하고 로그인 상태를 확인합니다.
  2. 업로더에서 도구 → HIRA Agent 상태 확인 또는 F7을 선택합니다.
  3. 정상 응답을 확인한 뒤 자료를 가져옵니다. 연결 실패 시 하단 로그와 Agent 상태부터 확인하세요.
기관기호와 API KEY는 같은 기관의 값이어야 합니다.

API KEY는 비밀번호처럼 보관하고 공개 게시판이나 문의 화면에 그대로 붙여 넣지 마세요. 이 사용법 페이지에는 API KEY를 입력하는 기능이 없습니다.

04 · TRANSFER

자료 가져오기와 전송

자료를 먼저 확인하고 전송하기

  1. 가져오기 → API에서 환자 가져오기(F5)를 선택합니다. 환자와 방문점검 자료를 조회해 대기목록에 표시합니다.
  2. 목록에서 자료를 선택합니다. 더블클릭 또는 도구 → JSON 미리보기 / 편집에서 내용을 확인할 수 있습니다.
  3. 전송 → 선택 자료 검증을 선택하면 JSON 구조를 확인합니다. 이 검사는 HIRA 접수 성공이나 모든 업무 규칙의 통과를 보장하지 않습니다.
  4. 전송 → 선택 자료 전송 또는 전체 자료 전송으로 실제 전송합니다.
  5. 하단 로그와 완료·실패 폴더에서 결과를 확인합니다. API 조회만으로 자료가 전송되지는 않습니다.
API를 다시 가져오면 기존 대기목록이 초기화됩니다.

v4.36.1의 API에서 환자 가져오기와 API 가져오기 + 전송은 기존 outbox 파일을 정리한 뒤 자료를 조회합니다. 수동으로 편집했거나 따로 가져온 대기자료가 있다면 실행 전에 백업하거나 처리해 주세요.

환자등록부터 방문점검까지 연속 처리하기

전송 → API 가져오기 + 전송(F6)은 확인 창에서 동의한 뒤 아래 순서로 실제 전송합니다.

  1. Agent 연결·로그인 상태 확인
  2. API 환자정보 조회 및 대상자 등록 전송
  3. 환자등록 완료 반영 후 방문점검 자료 재조회
  4. 방문점검 자료 전송 및 하니케어 완료 상태 반영

심평원 환자 일련번호가 아직 반영되지 않은 방문점검은 보류될 수 있습니다. 하단 로그에서 보류 사유를 확인해 주세요.

결과를 읽는 방법

위치의미
대기목록 · outbox전송 대기 중인 JSON 자료입니다. 화면 목록은 주기적으로 새로 표시됩니다.
완료 · sentHIRA 처리와 하니케어 완료 반영까지 정상 종료된 자료를 보관합니다.
실패 · failed전송 실패, 자료 오류 또는 하니케어 완료 반영 실패 등을 확인해야 하는 자료입니다.
결과·오류 파일.result.json과 .error.txt에서 처리 결과와 오류 내용을 확인할 수 있습니다.
실패 폴더에 있다고 무조건 다시 전송하지 마세요.

HIRA에는 이미 반영됐지만 하니케어 완료 처리만 실패한 경우도 있습니다. 로그의 전송 성공 여부와 완료 처리 결과를 먼저 확인한 뒤 재처리하세요. 검증 목적으로 실제 환자자료를 전송하지 않습니다.

05 · SCHEDULE & TRAY

예약 실행과 트레이 사용

  1. 도구 → 설정 → 자동 실행 스케줄에서 매주 자동 실행 사용을 선택합니다.
  2. 실행 요일을 하나 이상 선택하고 시간을 저장합니다.
  3. 설정된 요일·시간 이후 프로그램이 실행 중이면 대상자 등록과 방문점검 전송을 순서대로 처리합니다. PC가 꺼져 있거나 프로그램이 종료되어 있으면 실행되지 않습니다.
  4. 예약 작업은 같은 날짜에 한 번 실행되도록 기록됩니다. 오류가 발생하면 로그를 확인하고 필요한 경우 담당자가 수동 처리합니다.
‘스케줄 지금 실행’은 실제 전송을 즉시 시작합니다.

도구 → 스케줄 지금 실행 또는 트레이 메뉴의 동일 항목은 예약 전송 흐름을 바로 실행하며, 별도의 전송 확인 창을 띄우지 않습니다. 시험 버튼으로 사용하지 마세요.

창 닫기와 프로그램 종료는 다릅니다.

  • 닫기(X)·최소화: 트레이로 이동하며 프로그램과 예약 작업은 계속 실행됩니다.
  • 다시 열기: 알림 영역 아이콘을 더블클릭하거나 업로더 열기를 선택합니다.
  • 완전 종료: 파일 → 프로그램 종료 또는 트레이 메뉴 → 프로그램 종료를 선택합니다.

06 · UPDATE

자동 업데이트

Setup.exe로 설치한 버전에서 동작합니다. 설치하지 않은 기존 EXE는 설치·데이터 이전 절차를 먼저 진행하세요.

  • 앱 실행 시 한 번, 이후 4시간마다 업데이트 목록을 확인합니다.
  • 도움말 → 업데이트 확인으로 직접 확인할 수 있습니다.
  • 새 버전이 있을 때만 업데이트 패키지를 다운로드합니다.
  • 전송·API 조회·예약 작업·설정 및 편집 창 사용 중에는 적용을 미룹니다.
  • 작업이 없고 메인 창이 최소화 또는 트레이 상태일 때 적용하고 자동 재시작합니다. 창을 계속 열어두면 적용이 대기할 수 있습니다.
  • 프로그램이 완전히 종료되어 있으면 업데이트를 확인하지 않습니다. 다음 실행 때 확인합니다.
  • 업데이트 서버 연결에 실패하면 기존 버전을 계속 사용하고, 다음 정기 확인 또는 수동 확인 때 재시도합니다.
새 설치파일을 매번 다시 받을 필요는 없습니다.

이미 설치형 버전을 사용 중이라면 프로그램의 업데이트 확인 기능을 이용하세요. 업데이트 후에도 별도 data 폴더의 설정과 대기·완료·실패 자료를 사용합니다.

07 · DATA

데이터 보관과 백업

현재 Windows 사용자의 아래 경로에 설정과 전송 자료를 보관합니다.

%LOCALAPPDATA%\Hanicare\HiraEFormUploader\data

파일 → 데이터 폴더 열기 또는 트레이 메뉴의 데이터 폴더 열기를 이용하면 바로 확인할 수 있습니다.

  • 백업할 때는 프로그램을 완전히 종료하고 data 폴더 전체를 복사합니다.
  • 설정·API KEY·환자자료가 포함될 수 있으므로 접근이 제한된 위치에 보관하세요.
  • 프로그램 설치 제거 후에도 별도 data 폴더는 보존됩니다. 이를 자동 삭제나 백업으로 간주하지 마세요.
  • 다른 PC·다른 Windows 사용자 계정에서는 암호화된 API KEY를 다시 입력해야 할 수 있습니다.

시작 오류 로그

%LOCALAPPDATA%\Hanicare\HiraEFormUploader\startup-error.log

08 · HELP

문제 해결

HIRA Agent 연결에 실패합니다.

Agent가 같은 PC에 설치·실행되어 있는지, 기관 로그인 상태가 정상인지 확인합니다. Agent 환경설정에서 WebAPI 사용이 켜져 있고 Port가 1707인지 확인한 뒤 저장하세요. 업로더의 도구 → HIRA Agent 상태 확인에서 표시되는 메시지를 확인하세요.

환자나 방문점검 자료가 조회되지 않습니다.

기관기호와 API KEY가 같은 기관의 값인지 확인합니다. 이미 전송 완료된 환자는 기본 조회 대상에서 제외될 수 있고, 방문점검은 하니케어에서 작성 완료된 서식이 대상입니다.

환자등록 후 발급된 심평원 환자 일련번호가 아직 저장되지 않았다면 방문점검이 보류될 수 있습니다. 로그의 보류 사유와 하니케어 상태를 확인해 주세요.

전송 성공 후에도 실패 폴더로 이동했습니다.

HIRA 처리는 완료됐지만 하니케어 완료 상태 반영이 실패했을 수 있습니다. .result.json, .error.txt와 로그를 확인하고, 실제 접수 상태를 확인하기 전에 같은 자료를 반복 전송하지 마세요.

업데이트를 받았는데 버전이 그대로입니다.

전송과 예약 작업을 마치고 설정·편집 창을 닫은 뒤 메인 창을 최소화하거나 트레이로 숨기세요. 적용 조건을 만족하면 자동 재시작합니다. 설치형 버전인지와 도움말 → 업데이트 확인 결과도 확인해 주세요.

프로그램을 닫았는데 예약 전송이 실행됩니다.

닫기(X)는 트레이로 숨기는 동작입니다. 예약 전송을 중지하려면 설정에서 자동 실행을 끄거나 트레이 메뉴의 프로그램 종료로 완전히 종료하세요.

기존 자료 가져오기가 되지 않습니다.

기존 프로그램을 완전히 종료하고 appsettings.json이 들어 있는 기존 data 폴더를 선택했는지 확인합니다. 대상 경로에 이미 자료가 있다면 자동 덮어쓰기는 하지 않습니다. 원본과 복구용 폴더를 보관한 채 담당자에게 문의해 주세요.

문의할 때는 프로그램 버전, 오류 발생 시각과 오류코드를 함께 알려주세요. API KEY와 주민등록번호 등 개인정보는 가린 뒤 전달해 주세요. 소담소프트 문의 →

09 · SHORTCUTS

주요 메뉴와 단축키

기능메뉴·단축키
API 자료 조회가져오기 → API에서 환자 가져오기 · F5
JSON 파일 가져오기파일 → JSON 파일 가져오기 · Ctrl + O
선택 자료 검증전송 → 선택 자료 검증 · Ctrl + L
선택 자료 전송전송 → 선택 자료 전송 · Ctrl + Enter
API 조회·연속 전송전송 → API 가져오기 + 전송 · F6
Agent 상태 확인도구 → HIRA Agent 상태 확인 · F7
기관 설정도구 → 설정 · Ctrl + ,
업데이트 확인도움말 → 업데이트 확인
버전 확인도움말 → 프로그램 정보