API 연동 가이드

사이냅 오피스 – API 연동 가이드

목차
1. 새 문서 ··························································································································································································2
2. 문서 열기 ······················································································································································································4

2-1. URL 로 문서 열기······························································································································································4

2-2. 로컬 문서 열기··································································································································································6

3. 편집 상태 조회 ···········································································································································································8
4. 에러 페이지··············································································································································································· 10
5. 연동 예제 ··················································································································································································· 11

5-1. 새문서 열기 ····································································································································································· 11

5-2. 파일 열기·········································································································································································· 12

5-3. 문서 아이디로 열기······················································································································································ 13

5-4. 문서 저장·········································································································································································· 14

Synapsoft 1
사이냅 오피스 – API 연동 가이드

1. 새 문서
MS Format의 워드, 셀, 슬라이드 새 문서를 제공하는 API입니다.

[Request]

GET
/api/newDoc.cmd?fileName={filename}&saveUrl= {saveUrl}&userName={userName}&userId
= {userId} HTTP/1.1
Host: api.synapoffice.com

Ex) fileName : api테스트.docx, userName : 홍길동, userId : hongildong

<a href ='http://api.synapoffice.com/api/newDoc.cmd?fileName=
api%ED%85%8C%EC%8A%A4%ED%8A%B8.docx&saveUrl=http://service.com/saveOfficeFile.do&userName=
%ED%99%8D%EA%B8%B8%EB%8F%99&userId=hongildong' target='_blank'>새 문서</a>

파라미터 타입 설명 필수 기본 값

문서의 제목
fileName String O
encodeURIComponent 적용 필요
문서가 저장 될 위치 지정
saveUrl String O
편집 내용 저장 시 MultipartFile 문서로 젂송
사용자 이름
userName String O
encodeURIComponent 적용 필요

userId String 사용자 아이디 O

Synapsoft 2
사이냅 오피스 – API 연동 가이드

[Response]
정상적으로 새 문서 요청하는 경우 편집 뷰를 반환합니다.

HTTP/1.1 302 Found

Content-Length: 0
Location: /api/word/editor.cmd?docId={docId}
Host: api.synapoffice.com

Synapsoft 3
사이냅 오피스 – API 연동 가이드

2. 문서 열기
MS Format의 워드, 셀, 슬라이드 문서 열기를 제공하는 API입니다.

2-1. URL로 문서 열기
[Request]

GET
/api/openDoc.cmd?fileName={fileName}&saveUrl={saveUrl}&userName={userName}&&userId={user
Id}&downloadFileUrl={downloadFileUrl} HTTP/1.1
Host: api.synapoffice.com

Ex) 파일명 : 테스트.docx, userName : 홍길동, userId : hongildong

<a
href=’http://api.synapoffice.com/api/openDc.cmd?fileName=%ED%85%8C%EC%8A%A4%ED%8A%B8.docx
&saveUrl=&username=%ED%99%8D%EA%B8%B8%EB%8F%99&downloadFileUrl=http://www.synapoffice.c
om/download?fileName=test.docx&userId=hongildong’ target=’_blank’>문서 열기</a>

downloadFileUrl을 통해 다운로드 받고 해당 문서를 웹오피스로 엽니다.

파라미터 타입 설명 필수 기본 값

fileName String 문서의 제목 O

문서가 저장 될 위치 지정
saveUrl String O
편집 내용 저장 시 MultipartFile 문서로 젂송
userName String 사용자 이름 O
userId String 사용자 아이디 O
다운로드가 가능한 full URL
ex)
downloadFileUrl String O
downloadFileUrl=http://www.synapoffice.com/d
ownload?fileName=test.docx

Synapsoft 4
사이냅 오피스 – API 연동 가이드

[Response]
정상적으로 문서 열기를 요청하면 편집 뷰를 반환합니다.

HTTP/1.1 302 Found

Content-Length: 0
Location: /api/word/editor.cmd?docId={docId}

Synapsoft 5
사이냅 오피스 – API 연동 가이드

2-2. 로컬 문서 열기
[Request]

POST
/api/openDoc.cmd?fileName={fileName}&saveUrl={saveUrl}&userName={userName}&userId={userId}
HTTP/1.1
Host: api.synapoffice.com

MulitpartHttpSer vletRequest를 받아서 문서를 엽니다.

파라미터 타입 설명 필수 기본 값

fileName String 문서의 제목 O

문서가 저장 될 위치 지정
saveUrl String O
편집 내용 저장 시 MultipartFile 문서로 젂송
userName String 사용자 이름 O
userId String 사용자 아이디 O

[sample code]

<form method="post" target="_blank" enctype="multipart/form-data"

action="http://api.synapoffice.com/api/openDoc.cmd ">
<div>
<span>파일명</span> <input name="fileName">
</div>
<div>
<span>사용자명</span> <input name="userName">
</div>
<div>
<span>사용자 아이디</span> <input name="userId">
</div>
<div>
<span저장 될 주소</span> <input name="saveUrl">
</div>
<input type="file" name="officeFile"> <br>
<input type="submit" value="열기">
</form>

Synapsoft 6
사이냅 오피스 – API 연동 가이드

[Response]
정상적으로 문서 열기를 요청하면 편집 뷰를 반환합니다.

HTTP/1.1 302 Found

Content-Length: 0
Location: /api/word/editor.cmd?docId={docId}

Synapsoft 7
사이냅 오피스 – API 연동 가이드

3. 편집 상태 조회
문서의 편집상태를 조회합니다.
[Request]
Method : GET or POST (url이 긴 경우 POST 권장)

GET /api/editInfo.cmd?docIds={document IDs} HTTP/1.1

Host: api.synapoffice.com

파라미터 타입 설명 필수 기본 값

문서 아이디를 콤마로 구분하여 호출하면 각 문서

docIds String O
의 편집 상태 제공

[Response]
필드 타입 설명 필수

hasClient Boolean 문서에 접속 중인 클라이언트 존재 여부 O

clientList Array 문서에 접속 중인 클라이언트 리스트 O
docType String 문서 종류 [word|slide|cell] O
userId String 사용자 아이디 O
userName String 사용자명 O
브라우저 클라이언트 아이디
clientId String 동일 사용자가 편집화면을 여러 개 띄우는 경우 O
별도로 아이디 부여
docId String 문서 아이디 O

Synapsoft 8
사이냅 오피스 – API 연동 가이드

[response sample]

{
"success": true,
"message": "editing client list API",
"data": [
{
"hasClients": true,
"clientList": [
{
"docType": "slide",
"userId": "apiUser1",
"userName": "사용자1",
"clientId": "AD410C39-832B-4AA7-8DC0-7A0DBB881D45"
},
{
"docType": "slide",
"userId": "apiUser2",
"userName": "사용자2",
"clientId": "AD410C39-832B-4AA7-8DC0-7A0DBB881D45"
}
],
"docId": "MjZkOWNlZWEtNDJhMS00ZTU1LThlNDItMjIyNDA1MjI1YmM2"
},
{
"hasClients": false,
"clientList": [],
"docId": "testDocId"
}
],
"exception": "",
"resultcode": 0,
"errorCode": 0
}

Synapsoft 9
사이냅 오피스 – API 연동 가이드

4. 에러 페이지
유효하지 않는 인증 키로 API 요청 시 에러 페이지를 반환합니다.
HTTP/1.1 200 OK

파라미터가 누락되거나 잘못된 값으로 문서 열기 요청 시 에러 페이지를 반환합니다.

HTTP/1.1 400 Bad Request

Synapsoft 10
 사이냅 오피스 – API 연동 가이드

5. 연동 예제
5-1. 새문서 열기

/**
*
* http://{APP_SERVER}/office/{DOC_TYPE}/newDoc.cmd?fileName={FILE_NAME}&saveUrl={SAVE_URL}
* ex)
http://www.wehago.com/office/word/newDoc.cmd?fileName=Untitled.docx&saveUrl=http://www.wehago.com/office/saveDoc.cmd
*/

@RequestMapping("{docType}/newDoc.cmd")
public RedirectView newDoc(
@PathVariable("docType") String docType,
@RequestParam("fileName") String fileName,
@RequestParam("saveUrl") String saveUrl
) throws IOException {
URL url = new URL(String.format("{OFFICE_SERVER}/api/%s/newDoc.cmd?fileName=%s&saveUrl=%s", docType,
URLEncoder.encode(fileName, "UTF-8"), saveUrl));
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setInstanceFollowRedirects(false);
conn.setRequestProperty("OFFICE_USER_ID", "{USER_ID}"); // 사용자 아이디
conn.setRequestProperty("OFFICE_USER_NAME", "{USER_NAME}"); // 사용자 이름

Map<String, List<String>> headers = conn.getHeaderFields();

return new RedirectView(String.format("%s&authToken=%s",
headers.get("Location").get(0),
headers.get(API_AUTH_TOKEN).get(0))
);
}

Synapsoft 11
 사이냅 오피스 – API 연동 가이드

5-2. 파일 열기

/**
* http://{APP_SERVER}/office/openDoc.cmd?fileName={FILE_NAME}&saveUrl={SAVE_URL} *
* ex)
http://www.wehago.com/office/openDoc.cmd?fileName=testDocument.docx&saveUrl=http://www.wehago.com/office/saveDoc.cmd
*/
@ResponseBody
@RequestMapping(value = "openDoc.cmd")
public RedirectView openDoc(
@RequestParam(value = "fileName", required = false) String orgFileName,
@RequestParam("saveUrl") String saveUrl) throws IOException {
FileInputStream fis = new FileInputStream(new File("{file_path}")); // 스토리지에서 다운로드 받은 파일
String fileName = StringUtils.isEmpty(orgFileName) ? file.getOriginalFilename() : orgFileName;
MultipartEntityBuilder builder = MultipartEntityBuilder.create()
.setMode(HttpMultipartMode.BROWSER_COMPATIBLE)
.setCharset(Charset.forName("UTF-8"))
.addBinaryBody("file", fis, ContentType.APPLICATION_OCTET_STREAM, fileName);

HttpPost post = new HttpPost(String.format("{OFFICE_SERVER}/api/openDoc.cmd?fileName=%s&saveUrl=%s",

URLEncoder.encode(fileName, "UTF-8"), saveUrl));

post.setHeader("OFFICE_USER_ID", "{USER_ID}"); // 사용자 아이디

post.setHeader("OFFICE_USER_NAME", "{USER_NAME}"); // 사용자 이름
post.setEntity(builder.build());

String token = "";

String returnUrl = "";
try (CloseableHttpResponse closeableHttpResponse = httpClient.execute(post)) {
token = closeableHttpResponse.getHeaders("OFFICE_API_TOKEN")[0].getValue();
returnUrl = closeableHttpResponse.getHeaders("location")[0].getValue();
} catch (IOException e) {
System.out.println(e.getMessage());
} finally {
post.releaseConnection();
}
return new RedirectView(String.format("%s&authToken=%s", returnUrl, token));
}

Synapsoft 12
 사이냅 오피스 – API 연동 가이드

5-3. 문서 아이디로 열기
/**
* http://{APP_SERVER}/office/openDocByDocId.cmd?docId={DOC_ID}
* ex)
http://www.wehago.com/office/openDocByDocId.cmd?DOC_ID=abcde-12341234-zxvcqwer
*/
@ResponseBody
@RequestMapping("openDocByDocId.cmd")
public RedirectView openDocByDocId(
@RequestParam("docId") String docId
) throws IOException {
URL url = new URL(String.format("{OFFICE_SERVER}/api/openDocByDocId.cmd?docId=%s", docId));
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setInstanceFollowRedirects(false);

conn.setRequestProperty("OFFICE_USER_ID", "{USER_ID}"); // 사용자 아이디

conn.setRequestProperty("OFFICE_USER_NAME", "{USER_NAME}"); // 사용자 이름

Map<String, List<String>> headers = conn.getHeaderFields();

return new RedirectView(String.format("%s&authToken=%s",
headers.get("Location").get(0),
headers.get(API_AUTH_TOKEN).get(0))
);
}

Synapsoft 13
사이냅 오피스 – API 연동 가이드

5-4. 문서 저장
/**
* 문서 저장 (오피스에서 저장 버튼 클릭 시 호출되는 페이지)
* 문서 열기 시 젂달할 saveUrl 주소
ex)
http://www.wehago.com/office/saveDoc.cmd
*/
@ResponseBody
@RequestMapping(value = {"/saveDoc.cmd"}, method = RequestMethod.POST)
public String saveOfficeDocument( MultipartHttpServletRequest multipartRequest ) throws IOException {
Map<String, MultipartFile> multiValueMap = multipartRequest.getFileMap();
MultipartFile multipartFile = multiValueMap.values().iterator().next();
String fileName = multipartFile.getOriginalFilename();
File targetFile = new File("/data/" + fileName);
String docId = multipartRequest.getParameter("docId");
String ownerId = multipartRequest.getParameter("ownerId");

System.out.println(String.format("fileName : %s", fileName));

System.out.println(String.format("docId : %s", docId));
System.out.println(String.format("ownerId : %s", ownerId));

try(
InputStream inputStream = multipartFile.getInputStream();
OutputStream outStream = new FileOutputStream(targetFile)
){
byte[] buffer = new byte[inputStream.available()];
inputStream.read(buffer);
outStream.write(buffer);
}
return "success";
}

Synapsoft 14