본문으로 건너뛰기
버전: 개발 버전 (최신)

로컬 export API (v2)

로컬 export API는 현재(active) cycle 의 건강 데이터를 선택한 포맷(pdf | xml)으로 생성해 GCS(EU, europe-west3)에 업로드하고, 1분 만료 signed URL 을 반환하는 v2 endpoint입니다. ePA로 전송하지 않고 사용자가 직접 내려받도록 하는 LOCAL 채널이며, xml 은 ePA 정본과 동일한 FHIR/MIO Bundle 직렬화 결과입니다.

핵심
  • 채널 = LOCAL: ePA 전송 없이 signed URL 로 다운로드만 제공합니다. ePA로 실제 전송하려면 ePA 전송(POST /epa)을 사용합니다.
  • 기본 포맷 = pdf: format 미지정 시 pdf. (ePA 전송용 POST /epa 는 기본 xml.)
  • xml = ePA MIO Bundle: xml 선택 시 ePA로 넘기는 것과 동일한 FHIR/MIO Bundle 이 생성됩니다.
  • PII 보호: 응답 바디의 downloadUrl 은 로그에서 제외됩니다(bodyExcludedPaths('*health-data/export*')).
인증 정책 (v2 공통)
  • 인증 채널은 Authorization: Bearer <accessToken> 한 줄(JwtAuthGuard).
  • 신원은 access token payload(userId)로 확정하므로 요청 본문에 사용자 식별자를 넣지 않습니다.

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

현재(active) cycle 데이터를 선택한 포맷으로 생성해 다운로드용 signed URL 을 반환합니다.

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

Request​

HeaderValue
AuthorizationBearer <accessToken> (필수)

Request Body — LocalExportRequestDto​

필드타입필수제약설명
formatstringNopdf | xmlexport 포맷. 미지정 시 pdf. xml 은 ePA 용 FHIR/MIO Bundle
{
  "format": "pdf"
}

동작​

  1. JwtAuthGuard로 access token을 검증하고 payload에서 userId를 확정합니다.
  2. 사용자의 현재(active) cycle 데이터를 조회해 export 도메인 모델을 생성합니다 — active cycle 없으면 404(EXPORT_USER_INFO_NOT_FOUND), 내보낼 데이터 없으면 404(EXPORT_NO_DATA).
  3. 선택 포맷(pdf | xml)으로 산출물을 렌더링합니다.
  4. GCS(EU, europe-west3)에 업로드하고 1분 만료 v4 signed URL 을 발급합니다.
  5. downloadUrl·fileName·expiresAt 을 반환합니다. 렌더/업로드 실패 시 FAILED export 로그가 먼저 기록됩니다.

Response 200 OK — LocalExportResponseDto​

{
  "downloadUrl": "https://storage.googleapis.com/dta-cloud-de-dev-health-data-export/health-export/...&X-Goog-Signature=...",
  "fileName": "health-export-20260601.pdf",
  "expiresAt": 1748768460000
}
필드타입필수설명
downloadUrlstringYesv4 signed URL (1분 만료)
fileNamestringYes다운로드 파일명
expiresAtnumberYessigned URL 만료 시각 unix timestamp(ms, 13자리)

Errors​

HTTPcodemessage발생 조건
4001001Bad Requestformat 이 pdf/xml 외 값 (ValidationPipe)
4011000Authentication token not foundBearer access token 미제공 (JwtAuthGuard)
4011000Invalid or expired tokenaccess token 만료/서명·검증 실패 (JwtAuthGuard)
4011000Invalid token: missing subject (user ID)payload에 userId(sub) 없음
4011000User ID not found in requestguard 통과했으나 req.user.userId 부재 (컨트롤러)
40421100EXPORT_USER_INFO_NOT_FOUND요청 사용자의 활성(active) cycle 없음
40421102EXPORT_NO_DATA내보낼 임상 데이터 없음 (model.isEmpty())
50021200EXPORT_SERIALIZATION_FAILED산출물 생성 실패 — 도메인 모델 생성 또는 PDF/XML 렌더
50021201EXPORT_UPLOAD_FAILEDGCS 업로드 / signed URL 발급 실패
5001000An unexpected error occurred그 외 미처리 서버 오류 (global exception filter fallback)

실패(500) 시 FAILED export 로그가 먼저 기록됩니다. EXPORT_NO_DATA(21102)는 무로그입니다.

다음 단계​