DEXT-DOC 연동 가이드

1 API 개요 및 구성

  개요

문서 변환 솔루션은 파일을 PDF 또는 이미지 파일로 변환할 수 있는 HTTP 프로토콜 기반의 API를 제공합니다.
API는 REST FUL과 유사한 형식으로 제공됩니다. 문서 변환 솔루션은 윈도우 서버 2012 R2 이상의 환경에서 동작합니다.

  구성

API는 아래와 같은 내용으로 구성되어 있습니다.

• 1. 변환 요청 API: 파일 변환을 서버에 요청합니다. 서버에서의 요청 결과는 XML형식으로 반환됩니다.
• 2. 변환 결과 요청 API: 변환 결과 요청 API를 통해 변환된 파일을 가져올 수 있습니다.

API는 기본적으로 HTTP의 GET 메소드를 사용하여 요청됩니다

• * 요청 예제

• Server Address : 서버 접속 주소, ex) http://localhost:8080
• Query String : GET 방식 요청 시 사용되는 파라미터

2 지원 포맷

DEXT-DOC Standard

DEXT-DOC Pro

3 프로세스

4 Conversion Inquiry API

문서 변환 서버로 파일 변환을 요청하는 API 입니다.

Conversion Inquiry API 예시

로컬 C:\1.docx 파일을 PDF 파일로 변환 요청

Return XML 예시

서버에서 Conversion Inquiry API 에 대한 변환 결과를 XML 형식으로 리턴합니다.

<response>
    <status>0</status>
    <serverIndex>1</serverIndex>
    <totProcessTime>00:00:02.3710840</totProcessTime>
    <from>docx</from>
    <to>pdf</to>
    <saveRootLocation>C:\Converted\</saveRootLocation>
    <serverLocation>http://localhost:8080/Views/result.aspx?fileName=</serverLocation>
    <convertedVirtualDirectoryName>/ConvertFile/</convertedVirtualDirectoryName>
    <PdfViewerUrl>http://localhost/pdf-preview/MjAyMC8wNy8yOSBwMDAwYml20SO4ZDkwL
TQwNjQtYThmOC1jZmRI0DM4Y2Q2ZWluZG9jeCOwMDAxLnBkZg==</PdfViewerUrl>
    <pageTotalCount>1</pageTotalCount>
    <cachedStatus>0</cachedStatus>
    <resources>
        <convertFile>2020/07/29/0000bb69-8d90-4064-a8f8-cfde838cd63b.docx-0001.pdf</convertFile>
    </resources>
</response>

XML 세부사항

각각의 노드들은 특정 의미를 가지고 있습니다.
문서 변환을 요청한(Conversion Inquiry API 를 call한)코드단에서 서버에서
리턴된 XML 데이터를 파싱하여 변환 결과 요청 API Query String 를 구성할 수 있습니다.

<response>
    <status>0</status>
    <serverIndex>1</serverIndex>
    <totProcessTime>00:00:02.3710840</totProcessTime> 변환에 소요된 총 시간
    <from>docx</from>
    <to>pdf</to>
    <saveRootLocation>C:\Converted\</saveRootLocation> 변환된 파일이 저장되는 ROOT 경로
    <serverLocation>http://localhost:8080/Views/result.aspx?fileName=</serverLocation> 
외부 시스템에서 스트리밍 방식으로 변환된 데이터를 가져가기 위한 주소
    <convertedVirtualDirectoryName>/ConvertFile/</convertedVirtualDirectoryName>
    <PdfViewerUrl>http://localhost/pdf-preview/MjAyMC8wNy8yOSBwMDAwYml20SO4ZDkwLTQwNjQtYThmOC1jZmRI0DM4Y2Q2ZWluZG9jeCOwMDAxLnBkZg==
</PdfViewerUrl> PDF Viewer 호출을 위한 주소
    <pageTotalCount>1</pageTotalCount>
    <cachedStatus>0</cachedStatus>
    <resources>
        <convertFile>2020/07/29/0000bb69-8d90-4064-a8f8-cfde838cd63b.docx-0001.pdf</convertFile> 변환된 파일이 저장되는 SUB 경로
    </resources> 
</response>

5 Conversion Result API

직접 가져오는 방법

WAS단에서 문서변환 서버에서 변환된 파일을 직접 엑세스합니다. 속도, 리소스 측면에서 권장하는 방법 입니다.

<response>
    <status>0</status>
    <serverIndex>1</serverIndex>
    <totProcessTime>00:00:02.3710840</totProcessTime>
    <from>docx</from>
    <to>pdf</to>
    <saveRootLocation>C:\Converted\</saveRootLocation>
    <serverLocation>http://localhost:8080/Views/result.aspx?fileName=</serverLocation>
    <convertedVirtualDirectoryName>/ConvertFile/</convertedVirtualDirectoryName>
    <PdfViewerUrl>http://localhost/pdf-preview/MjAyMC8wNy8yOSBwMDAwYml20SO4ZDkwLTQwNjQtYThmOC1jZmRI0DM4Y2Q2ZWluZG9jeCOwMDAxLnBkZg==
</PdfViewerUrl>
    <pageTotalCount>1</pageTotalCount>
    <cachedStatus>0</cachedStatus>
    <resources>
        <convertFile>2020/07/29/0000bb69-8d90-4064-a8f8-cfde838cd63b.docx-0001.pdf</convertFile>
    </resources>
</response>

Conversion result API 예시

저장된 0000bb69-8d90-4064-a8f8-cfde838cd6eb.docx-0001.pdf 파일을 가져옵니다.
serverLocation + convertFile 값을 조합합니다. 네트워트 드라이브로 연동된 환경도 상관없습니다.

문서 변환 서버의 스트리밍 방법을 이용하여 가져오는 방법

서버에서 변환된 결과 파일을 요청합니다. 저장된 파일에 직접 엑세스 불가능 할 때 사용합니다.
직접 접근이 가능하다면 전 페이지에 나오는 방법을 이용하세요.

<response>
    <status>0</status>
    <serverIndex>1</serverIndex>
    <totProcessTime>00:00:02.3710840</totProcessTime>
    <from>docx</from>
    <to>pdf</to>
    <saveRootLocation>C:\Converted\</saveRootLocation>
    <serverLocation>http://localhost:8080/Views/result.aspx?fileName=</serverLocation>
    <convertedVirtualDirectoryName>/ConvertFile/</convertedVirtualDirectoryName>
    <PdfViewerUrl>http://localhost/pdf-preview/MjAyMC8wNy8yOSBwMDAwYml20SO4ZDkwLTQwNjQtYThmOC1jZmRI0DM4Y2Q2ZWluZG9jeCOwMDAxLnBkZg==
</PdfViewerUrl>
    <pageTotalCount>1</pageTotalCount>
    <cachedStatus>0</cachedStatus>
    <resources>
        <convertFile>2020/07/29/0000bb69-8d90-4064-a8f8-cfde838cd63b.docx-0001.pdf</convertFile>
    </resources>
</response>

Conversion Inquiry API 예시

서버에 저장된 0000bb69-8d90-4064-a8f8-cfde838cd6eb.docx-0001.pdf 파일을 가져옵니다.
saveRootLocation + convertFile 값을 조합합니다.

6 Return XML 요소 설명

7 예외처리 (Status Codes)

변환 요청에 대한 처리결과 인덱스

XML 데이터의 status값으로 나타냅니다.
Status 값이 “0”일때 변환된 파일을 가져오거나 해당 작업을 수행하도록 코드를 구성합니다.
“0”값이 아닐때는 변환 요청을 3회 정도 retry 하거나 에러를 파악하여 Conversion Inquiry API 를 수정합니다.

1 Conversion Inquiry API

문서 변환 서버로 웹 페이지 URL 및 HTML파일을 PDF 또는 이미지 파일로 변환을 요청하는 API 입니다.

URL Conversion Inquiry API 예시

Amazon 웹 페이지를 다양한 옵션을 조합하여 변환 요청을 하는 예시입니다.

http://localhost:8080/views/convert.aspx?filepath=https://www.amazon.com&type=pdf&pagesize=a4&landscape=false&htmlzoom=1.0&useprintmedia=false&noscript=false&nolink=false

옵션에 대한 설명은 다음장을 참고하세요.

변환된 파일을 가져오는 방법은 Conversion Result API 과 동일합니다.
앞에 설명한 Conversion Result API 내용을 참고하세요.

PDF 변환시 원하는 양식으로 페이지 분할을 원할시, page-break 를 사용해주세요.

2 Options

웹 페이지를 PDF 또는 이미지로 변환 할때 다양한 options를 조합할 수 있습니다.
아래 설명된 파라미터 이외에 left margin, top margin, right margin, bottom margin, header, footer, grayscale,
max load wait time, page number 설정에 대해서는 별도 문의를 주십시오.

1Conversion Inquiry API 및 Options

CAD 포맷중 2D 형식의 DWG, DXF 포맷을 지원합니다. PDF 변환 시 워터마크를 삽입할 수 있습니다. 텍스트, 이미지 기반 워터마크를 지원합니다.

DWG, DXF 포맷의 경우 변환 타입은 PDF 포맷을 권고합니다. 이미지로 변환하면 해상도 문제,
큰 이미지를 지원하지 않는 구형 디바이스의 경우 메모리 관련 오류가 발생할 수 있습니다.
변환 요청 형식은 Common Conversion Inquiry API 와 동일합니다.

dwg, dxf 도면의 경우 페이지 사이즈가 큰 관계로 변환시 아래와 같은 다양한 페이지 사이즈가 옵션으로 지원됩니다.
용지 사이즈가 커질수록 변환 시간은 더 소요되지만, 도면의 정밀도는 올라갑니다.
ex) http://localhost:8080/Views/convert.aspx?filepath=C:\TestFile\1.dwg&type=pdf&PageSize=a0

2 Image Watermark

PDF 변환 시 이미지 기반의 워터마크를 생성할 때 옵션을 설정할 수 있습니다.

3 Text Watermark

PDF 변환 시 텍스트 기반의 워터마크를 생성할 때 옵션을 설정할 수 있습니다.
wmprefixtype, wmopacity, wmrotationtype, wmmargin 값은 이미지 기반의 워터 마크의 옵션값과 동일하며 해당 모드의 옵션값을 참고 바랍니다.

1 Conversion Inquiry API

HWP, MS-OFFICE 및 이미지 파일에 대한 워터마크를 지원합니다.
Watermark 변환의 경우 캐싱 기능을 지원하지 않습니다. 캐싱 기능을 활성화한 경우 기존에 원본 파일을 성공적으로 pdf 또는 이미지로 변환했다면,
watermark 변환 요청은 무조건 캐싱 처리 됩니다. 따라서, 워터마크가 적용되지 않은 pdf 또는 이미지 값이 반환됩니다.

Watermark로 사용될 이미지는 투명 값이 적용된 png 포맷을 사용해 주세요.

Watermark Conversion Inquiry API 예시

Watermark 에 사용될 이미지 위치 = D:\TestFile\watermark.png
변환된 PDF에 Watermark가 적용될 위치값 = fix 0
Watermark 투명도 = 50%
Watermark 회전값 = 0도
Watermark 여백 = 20

http://localhost:8080/Views/convert.aspx?filepath=D:\TestFile\1.hwp&type=pdf&wmimagepath=D:\TestFile\watermark.png&wmprefixtype=0&wmopacity=50&wmrotationtype=1&wmmargin=20

옵션에 대한 설명은 다음장을 참고하세요.

변환된 파일을 가져오는 방법은 Conversion Result API 과 동일합니다.
앞에 설명한 Conversion Result API 내용을 참고하세요.

2 Options

PDF 변환 시 이미지 기반의 워터마크를 생성할 때 옵션을 설정할 수 있습니다.

1 API 개요 및 구성

문서 변환 솔루션이 지원하는 모든 파일들을 하나의 PDF 파일로 merge하는 API 입니다.(Standard, Pro 버전이 아닌 별도 요청 시 포함됩니다. )

2 프로세스

3 Merge info file(*.combine)

Step 1 *.combine 파일 생성

예 ) 로컬 c:\pdf-test에 위치한 1.pdf, 2.pdf, 3.pdf 파일들의 경우.
네트워크 드라이브상에 위치한 pdf 파일들도 문서 변환 서버에서 접근 가능한 경로이면 가능합니다.

4 Merge Inquiry API

Step 2 pdf 파일 합치기 요청

이제 문서 변환 서버로 pdf 파일 합치기를 요청합니다.

http://localhost:12348/Views/convert.aspx?filepath=C:\pdf-test\test.combine.

5 Merge Result API

Step 3 문서 변환 서버의 변환 결과 리턴

<response>
    <script/>
    <status>0</status>
    <serverIndex>1</serverIndex>
    <totProcessTime>00:00:05.2810668</totProcessTime>
    <engineName>CombinePDF.exe</engineName>
    <from>combine</from>
    <to>pdf</to>
    <saveRootLocation>C:\Converted\</saveRootLocation>
    <serverLocation>http://localhost:8080/Views/result.aspx?fileName=</serverLocation>
    <convertedVirtualDirectoryName>/ConvertFile/</convertedVirtualDirectoryName>
    <PdfViewerUrl>http://localhost:3003/pdf-preview/MjAyMC8wNy8xNS90ZXNOLmNvbWJpbmUtMDAwMS5wZGY=</PdfViewerUrl>
    <pageTotalCount>1</pageTotalCount>
    <cachedStatus>0</cachedStatus>
    <resources>
        <convertFile>2020/07/15/test.combine-0001.pdf</convertFile> 하나로 합쳐진 pdf 파일의 풀 패스 입니다. 
																	자세한 접근 방법은 이전파일 변환페이지를 참고 하세요
    </resources>
</response>

6 코딩 가이드

  C#

                //  merge info 파일의 풀 패스를 c:\pdf-test\test.combine 로 설정
                // 문서 변환 서버에서 file open이 가능한 경로여야 합니다.
    string strMergeInfoFilePath = @"c:\pdf-test\test.combine";

                // 유니코드 모드로 파일 스트림 생성
    System.IO.StreamWriter file = new System.IO.StreamWriter(strMergeInfoFilePath, true, Encoding.Unicode);

                // merge info 파일에 원본 파일 풀 패스 기입
                // 각각의 원본 파일 경로는 문서 변환 서버에서 file open이 가능한 경로여야 합니다.
    file.WriteLine(@"c:\pdf-test\1.pdf");
    file.WriteLine(@"c:\pdf-test\2.pdf");
    file.WriteLine(@"c:\pdf-test\3.pdf");
    file.Close();

                // merge 요청
    http://localhost:8080/Views/convert.aspx?filepath=C:\pdf-test\test.combine@autofit=a4&type=pdf

                // return 된 xml 데이터 파싱 및 데이터 처리

1 개요 및 구성

  개요

2 유저 인터페이스

어도비 아크로뱃 리더와 유사한 사용하기 편리한 인터페이스를 제공합니다.

3 특징

1. 안정적인 성능
- 기관, 기업 및 글로벌 사이트에서 안정적인 서비스 검증

2. 보안
- 브라우저를 닫으면 열람하고 있던 문서 데이터가 디바이스에 남지 않음
- HTML5 기반의 뷰어(Active X 없음)

3. 다양한 뷰잉 도구 지원
- 썸네일, 페이지 이동, 확대, 축소, 검색, 저장 등

4. PC 및 MOBILE 환경 대응
- 반응형 웹 방식으로 설계되어 웹 브라우저를 띄울 수 있는 어떤 디바이스(PC, ios, 안드로이드, 태블릿)에서도 열람 가능

5. 디바이스에 대한 독립성
- 웹 뷰어 방식이기 때문에 고객사 앱 업데이트나 디바이스 자체 OS 업데이트에 영향을 받지 않음
- 클라이언트 업데이트 관리 불필요

6. streaming 방식의 뷰잉 지원
- 문서 열람과 동시에 뷰잉을 지원하므로 모든 데이터 다운로드 후 뷰잉을 하는 기존의 뷰어들보다 빠른 뷰잉이 가능

7. 벡터 방식 지원
- 최종 뷰잉 데이터가 PDF 파일이기 때문에 이미지 기반 방식의 뷰어에서 나타나는 확대, 축소 시 폰트가 깨지는 문제를 근본적으로 해결

8. Watermark 지원
- PDF 열람 시 워터마크를 활성화하여 보안성을 높이고 문서의 상태(예: "기밀", "복사 금지")를 나타낼 수 있습니다.
- PDF 파일을 열 때마다 워터마크가 표시되며, 문서의 복제나 배포를 방지하는 데 유용합니다.

4 프로세스

5 파일 변환 요청 후 PDF Viewer 호출

Step 1 Coversion Inquiry API 생성 및 Call

Step 2 XML passing 및 뷰어 호출

<response>
    <status>0</status>
    <serverIndex>1</serverIndex>
    <totProcessTime>00:00:02.37108408</totProcessTime>
    <from>docx</from>
    <to>pdf</to>
    <saveRootLocation>C:\Converted\</saveRootLocation>
    <serverLocation>http://localhost:8080/Views/result.aspx?fileName=</serverLocation>
    <convertedVirtualDirectoryName>/ConvertFile/</convertedVirtualDirectoryName>
    <PdfViewerUrl>http://localhost:/pdf-
    preview/MjAyMC8wNy8yOSBwMDAwYml20S04ZDkwLTQwNjQtYThmOC1jZmRI0DM4Y2Q2ZWluZG9jeCOwMDAxLnBkZg==</PdfViewerUrl>
    <pageTotalCount>1</pageTotalCount>
    <cachedStatus>0</cachedStatus>
    <resources>
        <convertFile>2020/07/29/0000bb69-8d90-4064-a8f8-cfde838cd6eb.docx-0001.pdf</convertFile>
    </resources>
</response>
                    

6 Watermark 개요

  개요

7 Watermark Inquiry API

Step 1 뷰잉할 pdf 파일명 추출

<response>
    <status>0</status>
    <remarks>0</remarks>
    <serverIndex>1</serverIndex>
    <totProcessTime>00:00:08.2728723</totProcessTime>
    <from>docx</from>
    <to>pdf</to>
    <saveRootLocation>C:\Converted\</saveRootLocation>
    <serverLocation>http://211.232.104.138:8080/Views/result.aspx?fileName=</serverLocation>
    <convertedVirtualDirectoryName>/ConvertFile/</convertedVirtualDirectoryName>
    <PdfViewerUrl>http://localhost:/pdf-
    preview/MjAnC8wOS90T05WRVJULS0tNTU1ZDYzWmYtMDIxNS000TRkLTgxNWNtNTFkMDAxZDk2MmM5LmRvY3gtMDAwMS5wZGY=</PdfViewerUrl>
    <pageTotalCount>1</pageTotalCount>
    <cachedStatus>0</cachedStatus>
    <resources>
        <convertFile>2024/09/CONVERT---555d632f-0215-494d-815c-51d001d962c9.docx-001.pdf</convertFile>
    </resources>
</response>

8 Watermark 옵션

9 주의사항

Watermark는 세션 기반으로 작동합니다.

세션이 더 이상 유효하지 않을 때 워터마크 뷰어를 새로 고침하면 초기 화면인 timeout 페이지로 이동됩니다.
세션 종료 시 이동할 페이지를 web.config에서 변경할 수 있습니다.

(디폴드 : timeout.aspx)

<add key="TimeoutPage" value="/timeout.aspx" desc="Session timeout시 이동 페이지"/>

세션 값은 서버에 종속됩니다.