버전: 개발 버전 (최신)

ePA 전송 API (v2)

ePA 전송 API는 현재(active) cycle 의 건강 데이터를 fbeta ePA-Service(/send-document/)를 통해 ePA(독일 전자건강기록, elektronische Patientenakte)로 실제 전송하는 v2 endpoint입니다. 데이터는 FHIR/MIO Bundle(xml)로 직렬화되어 전송됩니다.

핵심

채널 = EPA: FHIR/MIO Bundle 을 ePA로 전송합니다. 사용자 직접 다운로드는 로컬 export(POST /local)를 사용합니다.
기본 포맷 = xml: format 미지정 시 xml(ePA MIO Bundle). (로컬 다운로드용 POST /local 은 기본 pdf.)
전송 실패 = 200 status=FAILED: 실제 ePA 전송 단계의 실패(EpaSendFailedError)는 500이 아니라 200 status=FAILED 로 매핑됩니다(FAILED 로그 적재). 반면 사전조건 위반(404/409)은 HTTP 에러로 전파됩니다.
멱등 재전송: 동일 문서 재전송(DOC_UPLOAD_DUPLICATE)은 멱등 성공으로 처리됩니다.
stub 환경: EPA_SERVICE_STUB=true 환경에서는 실제 전송 대신 stub 처리됩니다.

전송 사전조건 (409)

ePA 전송은 KVNR 연동 + ACTIVE eID(GesundheitsID) 링크 + FdV 앱에서의 DiGA 접근 승인 이 모두 충족되어야 합니다. 하나라도 미충족이면 409 CONFLICT 로 응답하며(status=FAILED 가 아님), 클라이언트는 재인증/승인 유도가 필요합니다.

`POST /v2/health-data/export/epa` ⭐

현재(active) cycle 데이터를 ePA로 즉시 전송합니다.

Path: POST /v2/health-data/export/epa
인증: User Access Token (JwtAuthGuard)
Rate Limit: 60/분 (전역 default)
🔗 라이브 명세 (Swagger UI): dev

Request

Header	Value
`Authorization`	`Bearer <accessToken>` (필수)

Request Body — `EpaExportRequestDto`

필드	타입	필수	제약	설명
`format`	string	No	`xml` \| `pdf`	export 포맷. 미지정 시 `xml`(ePA MIO Bundle)

{
  "format": "xml"
}

동작

JwtAuthGuard로 access token을 검증하고 payload에서 userId를 확정합니다.
사용자의 현재(active) cycle 데이터를 조회해 export 도메인 모델을 생성합니다 — active cycle 없으면 404, 데이터 없으면 404.
전송 사전조건을 검증합니다 — KVNR 연동(없으면 409 EPA_KVNR_NOT_FOUND), ACTIVE eID 링크(없으면 409 EPA_EID_NOT_ACTIVE), FdV DiGA 접근 승인(없으면 409 EPA_NOT_ENTITLED).
FHIR/MIO Bundle 을 직렬화해 fbeta ePA-Service /send-document/ 로 전송합니다.
전송 성공이면 status=SUCCEEDED. 전송 단계 실패(EpaSendFailedError)는 200 status=FAILED 로 매핑하며 FAILED 로그를 적재합니다. 직렬화 실패는 500(EXPORT_SERIALIZATION_FAILED).

Response 200 OK — `EpaExportResponseDto`

// 전송 위임 성공
{
  "status": "SUCCEEDED",
  "submittedAt": 1749031200000
}

// ePA 전송 실패 (200 으로 매핑, FAILED 로그 적재됨)
{
  "status": "FAILED",
  "submittedAt": 1749031200000
}

필드	타입	필수	설명
`status`	string	Yes	`SUCCEEDED`(전송 위임 성공) \| `FAILED`(ePA 전송 실패, 200 매핑)
`submittedAt`	number	Yes	전송(위임) 시각 unix timestamp(ms, 13자리)

Errors

HTTP	code	message	발생 조건
400	1001	Bad Request	`format` 이 `pdf`/`xml` 외 값 (ValidationPipe)
401	1000	Authentication token not found	Bearer access token 미제공 (`JwtAuthGuard`)
401	1000	Invalid or expired token	access token 만료/서명·검증 실패 (`JwtAuthGuard`)
401	1000	Invalid token: missing subject (user ID)	payload에 `userId`(sub) 없음
401	1000	User ID not found in request	guard 통과했으나 `req.user.userId` 부재 (컨트롤러)
404	21100	EXPORT_USER_INFO_NOT_FOUND	요청 사용자의 활성(active) cycle 없음
404	21102	EXPORT_NO_DATA	내보낼 임상 데이터 없음
409	21101	EPA_KVNR_NOT_FOUND	KVNR 미연동 — `model.subject` 에 KVNR 식별자 없음
409	21103	EPA_EID_NOT_ACTIVE	ACTIVE eID(GesundheitsID) 링크 없음 — 재인증 필요
409	21104	EPA_NOT_ENTITLED	FdV 앱에서 DiGA 접근(쓰기) 미승인 — 승인 유도 필요
500	21200	EXPORT_SERIALIZATION_FAILED	모델/파일 생성(직렬화) 실패

ePA 전송 단계 실패(21300)는 500이 아니라 200 status=FAILED 로 반환됩니다. 사전조건 위반(404/409)·직렬화 실패(500)만 HTTP 에러로 전파됩니다.

다음 단계

자동 주기 전송 설정: ePA 주기 export 스케줄 (POST .../epa/schedule).
최근 전송 결과 확인: 최신 export 기록 조회 (GET .../epa/latest).
사용자 직접 다운로드: 로컬 export (POST /local).

POST /v2/health-data/export/epa ⭐​

Request​

Request Body — EpaExportRequestDto​

동작​

Response 200 OK — EpaExportResponseDto​

Errors​

다음 단계​