HWP Parser API 문서

1. 서비스키 발급

변환 API를 호출하려면 먼저 서비스키를 발급받아야 합니다. 데모 페이지(한글파서·한글생성기)에서 바로 신청할 수 있으며, 발급된 키는 입력한 이메일로 발송되고 데모 페이지의 서비스키 칸에 자동 입력됩니다.

발급 절차

데모 페이지에서 “서비스키 발급받기” 버튼을 누르면 발급 신청 창이 열립니다.
이름·연락처·이메일·사용용도·사용도메인을 입력하고 “발급 신청”을 누릅니다. (사용도메인은 키가 동작할 도메인 — 예: localhost, www.edenit.co.kr)
발급된 서비스키가 입력한 이메일로 발송되며, 데모 페이지의 서비스키 입력란에 자동으로 채워져 바로 변환을 사용할 수 있습니다.
이후 변환 API 호출 시 이 키를 serviceKey 파라미터(또는 X-Service-Key 헤더)로 전송합니다.

발급 신청 화면 예시

▲ 데모 페이지의 “서비스키 발급받기” 버튼을 누르면 나타나는 발급 신청 화면

신청 엔드포인트 발급 신청은 인증이 필요 없는 공개 경로 POST /api/v1/public/service-key/apply 로 전송됩니다. (일단위 키 발급)

발급된 키 사용법

발급된 서비스키는 다음 두 방식 중 하나로 전송합니다. 브라우저에서는 URL 파라미터 방식이 CORS 프리플라이트(OPTIONS)를 일으키지 않아 간편합니다.

방식	위치	예
URL 파라미터 (권장)	query	`?serviceKey=발급받은키`
헤더	header	`X-Service-Key: 발급받은키`

2. HWP → HTML 변환 (hwptohtml-api)

Base URL	`https://hwptohtml-api.edenit.co.kr`
엔드포인트	POST/api/v1/hwp-to-html

업로드한 HWP 파일을 HTML(+CSS·이미지)로 변환하고, 변환 통계와 다운로드 경로를 JSON으로 반환합니다.

파라미터	위치	필수	설명
`file`	form-data	O	변환할 HWP 파일 (.hwp)
`serviceKey`	query / header	O	발급받은 서비스키

JavaScript(fetch) 예시 — 서비스키는 URL 파라미터로 전송:

const fd = new FormData();
fd.append("file", hwpFile);                 // <input type="file"> 에서 얻은 File

const serviceKey = "발급받은_서비스키";       // 발급 시 자동 입력되는 키
const base = "https://hwptohtml-api.edenit.co.kr";

const res = await fetch(
  `${base}/api/v1/hwp-to-html?serviceKey=${encodeURIComponent(serviceKey)}`,
  { method: "POST", body: fd }      // 파라미터 방식은 커스텀 헤더 없음 → 프리플라이트 미발생
);
const json = await res.json();
// json.htmlDownloadUrl / json.cssDownloadUrl 로 결과를 다시 받아 표시
// (다운로드 URL 에도 serviceKey 파라미터를 붙여 요청)

헤더 방식을 쓸 때 headers: { "X-Service-Key": serviceKey } 를 추가하면 됩니다. 단, 커스텀 헤더는 CORS 프리플라이트(OPTIONS)를 유발하므로 서버가 OPTIONS를 처리해야 합니다.

응답(JSON) 예시:

{
  "success": true,
  "htmlDownloadUrl": "/api/v1/download?path=/data/out/abc/sample.html",
  "cssDownloadUrl":  "/api/v1/download?path=/data/out/abc/sample.css",
  "htmlFile": "/data/out/abc/sample.html",
  "statistics": {
    "sectionCount": 3, "paragraphCount": 128,
    "characterCount": 5240, "controlCount": 12, "imageCount": 4
  },
  "durationMs": 842
}

변환 결과(HTML/CSS/이미지)는 동일 호스트의 GET /api/v1/download?path=... 로 받으며, 이 요청에도 serviceKey 파라미터를 붙입니다.

3. HTML → HWP 변환 (htmltohwp-api)

Base URL	`https://htmltohwp-api.edenit.co.kr` (호스트가 다름)
엔드포인트	POST/api/v1/html-to-hwp

업로드한 HTML 파일을 HWP 파일로 변환하여 바이너리(.hwp)로 응답합니다. 파일명은 Content-Disposition 헤더로 전달됩니다.

파라미터	위치	필수	설명
`file`	form-data	O	변환할 HTML 파일 (.html / .htm)
`serviceKey`	query / header	O	발급받은 서비스키

이미지/수식 처리 HTML 내 이미지는 접근 가능한 절대 URL 또는 data URI 여야 하며, 수식은 \(...\) / \[...\] (LaTeX) 형식이면 HWP 수식 개체로 변환됩니다.

JavaScript(fetch) 예시 — 변환된 HWP 다운로드:

const fd = new FormData();
fd.append("file", htmlFile);

const serviceKey = "발급받은_서비스키";
const base = "https://htmltohwp-api.edenit.co.kr";   // ← HTML→HWP 전용 호스트

const res = await fetch(
  `${base}/api/v1/html-to-hwp?serviceKey=${encodeURIComponent(serviceKey)}`,
  { method: "POST", body: fd }
);
const blob = await res.blob();             // 응답은 .hwp 바이너리
const url = URL.createObjectURL(blob);
const a = document.createElement("a");
a.href = url; a.download = "converted.hwp"; a.click();
URL.revokeObjectURL(url);

이 변환은 한글생성기(HTML → HWP) 데모를 팝업으로 바로 시험해 볼 수 있습니다. HWP → HTML 은 한글파서 데모를 이용하세요.