API 가이드

호출 서버는 원본 문서의 URL만 이 API에 넘기면 됩니다. 문서 전체를 보여주고 싶으면 뷰어 API, 목록/카드 UI에 미리보기 이미지만 필요하면 썸네일 API를 쓰면 됩니다.

1. 인증

모든 요청에 X-API-Key 헤더가 필요합니다. 키는 Setting 페이지(관리자 로그인 필요)에서 발급합니다.

X-API-Key: dvk_xxxxxxxxxxxxxxxxxxxxxxxx

2. 뷰어 API — 문서 등록하고 뷰어 URL 받기

POST /api/v1/view

요청

POST /api/v1/view HTTP/1.1
Host: your-viewer-host
Content-Type: application/json
X-API-Key: dvk_xxxxxxxxxxxxxxxxxxxxxxxx

{
  "url": "https://your-server.com/files/report.docx",
  "filename": "report.docx"   // 선택. 생략 시 URL/Content-Disposition에서 추론
}

응답 (200)

{
  "doc_id": "b6f1e2a0-...",
  "view_url": "https://your-viewer-host/view/b6f1e2a0-...",
  "type": "office",            // hwp | office | spreadsheet | pdf | image | video | eml
  "name": "report.docx",
  "expires_at": "2026-08-03T13:00:00.000Z"
}

curl 예시

curl -X POST https://your-viewer-host/api/v1/view \
  -H "X-API-Key: dvk_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.com/files/report.docx"}'

뷰어 임베드

응답의 view_url을 iframe에 그대로 넣으면 됩니다. hwp/hwpx와 eml은 브라우저에서 직접 파싱/렌더링, 오피스·PDF·엑셀류는 PDF 변환 후 페이지 썸네일 그리드로, 이미지는 그대로, 동영상은 <video>로 재생됩니다. 썸네일 클릭 시 전체 화면 미리보기(라이트박스)가 열리고, 엑셀류는 속성 패널의 SPREADSHEET 배지로 실제 시트 표(스타일 포함) 보기로 전환할 수 있습니다. 형식별 세부 사항은 지원 포맷 페이지를 참고하세요.

<iframe
  src="https://your-viewer-host/view/b6f1e2a0-..."
  style="width:100%;height:80vh;border:0"
  allow="fullscreen">
</iframe>

allow="fullscreen"이 없으면 브라우저가 iframe 내부의 전체 화면 요청을 막아, 썸네일 클릭 시 미리보기가 iframe 영역 안에서만 표시됩니다.

특정 도메인에서만 임베드를 허용하려면 Setting의 "임베드 허용 Origin"에 호출 서버 도메인을 등록하세요(비워두면 제한 없음).

3. 썸네일 API — 미리보기 이미지 바로 받기

POST /api/v1/thumbnail

문서 전체를 뷰잉할 필요 없이, 목록 화면 등에 쓸 썸네일 이미지 1장이 필요할 때 사용합니다. 뷰어 API처럼 doc_id를 만들지 않고, 요청 1번에 PNG 이미지 바이트를 바로 응답으로 돌려줍니다.

요청

POST /api/v1/thumbnail HTTP/1.1
Host: your-viewer-host
Content-Type: application/json
X-API-Key: dvk_xxxxxxxxxxxxxxxxxxxxxxxx

{
  "url": "https://your-server.com/files/report.pptx",
  "filename": "report.pptx",   // 선택
  "width": 320                 // 선택, 기본 320px (32~1024)
}

응답 (200)

Content-Type: image/png — 첫 페이지(또는 이미지 원본)를 지정 폭으로 리사이즈한 PNG 바이트를 그대로 응답 본문에 담아 돌려줍니다.

curl 예시

curl -X POST https://your-viewer-host/api/v1/thumbnail \
  -H "X-API-Key: dvk_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.com/files/report.pptx","width":240}' \
  -o thumb.png

HTML 예시(서버에서 프록시해서 표시)

호출 서버가 이 API를 서버 사이드에서 호출해 받은 PNG를 자기 쪽 정적 URL로 재서빙하는 방식을 권장합니다 (API Key를 브라우저에 노출하지 않기 위해).

<img src="/your-server/thumbs/report.png" alt="report.pptx 미리보기">

페이지별 처리 방식 및 제약

형식별 썸네일 생성 방식과 제약은 지원 포맷 페이지의 표에 전부 정리해뒀습니다.

4. 공통 오류 응답

5. 지원 형식 및 처리 방식 (뷰어 API)

지원하는 모든 확장자와 처리 방식, 그리고 지원하지 않는 포맷 목록까지 지원 포맷 페이지에서 한 번에 확인할 수 있습니다.

허용 확장자/최대 파일 크기/보관 기간은 Setting에서 조정할 수 있습니다.

6. 문서 보관

뷰어 API로 등록된 문서는 응답의 expires_at 시점까지만 조회 가능하며, 이후 자동 삭제됩니다 (기본 보관 시간은 Setting에서 조정). 썸네일 API는 문서를 저장하지 않고 요청마다 즉시 생성 후 폐기합니다.