Files API

파일 하나에 대한 동작입니다. 파일과 폴더가 공유하는 리소스 모델, 목록 endpoint, 버전 이력, 잠금은 Common conventions에 있습니다. 이 페이지는 파일에만 해당하는 내용을 다룹니다.

Base URL과 scope

/api/external/v1/files

읽기 동작은 api:read가 필요합니다. 업로드·삭제·이름 변경·이동·복제는 api:write가 추가로 필요합니다.

파일 다운로드

GET /api/external/v1/files/{resourceSeq}/download

파라미터	Type	필수	설명
`resourceSeq`	long	Yes	path 파라미터 - 내려받을 파일
`ss`	integer	No	공유 사용자 seq

Request
curl -X GET "https://drive.example.com/api/external/v1/files/{resourceSeq}/download?ss=21" \
  -H "Authorization: Bearer replace-with-your-api-key"

성공하면 JSON 공통 구조가 아니라 파일 자체가 반환됩니다.

HTTP 200 OK
Content-Type: {contentType}
Content-Disposition: attachment; filename={fileName}

브라우저로 다운로드 위임

서버가 아니라 사용자 브라우저가 파일을 내려받게 하려면, 먼저 수명이 짧은 토큰을 발급받아 반환된 경로를 브라우저에 넘깁니다. 토큰이 인가를 담고 있으므로 두 번째 요청에는 Authorization 헤더가 필요 없습니다.

GET /api/external/v1/files/{resourceSeq}/download-token

파라미터	Type	필수	설명
`resourceSeq`	long	Yes	path 파라미터 - 내려받을 파일
`ss`	integer	No	공유 사용자 seq

Token response
{
  "result": true,
  "code": 200,
  "message": "OK",
  "data": {
    "linkUrl": "/files/download?dt={token}"
  }
}

그다음 아래 경로를 호출합니다.

GET /api/external/v1/files/download?dt={dt}

여러 리소스를 하나의 아카이브로 내려받는 방법은 Common conventions의 멀티 다운로드를 참고합니다.

파일 미리보기

GET /api/external/v1/files/{resourceSeq}/view

파라미터	Type	필수	설명
`resourceSeq`	long	Yes	path 파라미터 - 미리 볼 파일
`ss`	integer	No	공유 사용자 seq

렌더링된 미리보기를 바이너리 스트림으로 반환합니다.

파일 업로드

api:write 필요

POST /api/external/v1/files

파일은 multipart/form-data로 보냅니다.

파라미터	Type	필수	설명
`file`	file	Yes	업로드할 파일
`pfs`	long	No	부모 폴더 seq. 공유 사용자가 업로드할 때 필수
`ss`	integer	No	공유 사용자 seq. 본인 드라이브면 `null`
`st`	enum	No	이름 충돌 정책 - `duplicate`는 복사본 번호를 붙이며 기본값, `version`은 새 버전으로 추가, `overwrite`는 덮어쓰기
`rs`	long	No	대상 리소스 seq. `st`가 `version` 또는 `overwrite`일 때 필수

Request
curl -X POST "https://drive.example.com/api/external/v1/files" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@report.docx" \
  -F "pfs=1"

Upload response
{
  "result": true,
  "code": 201,
  "message": "Created",
  "data": {
    "resourceSeq": 283,
    "resourceName": "report.docx"
  }
}

계정 용량을 초과해 업로드하면 RESOURCE_015로 실패합니다.

파일 이름 변경

api:write 필요

PATCH /api/external/v1/files/{resourceSeq}/rename

파라미터	Type	필수	설명
`resourceSeq`	long	Yes	path 파라미터 - 이름을 바꿀 파일
`rn`	string	Yes	새 이름
`ncp`	enum	No	이름 충돌 정책 - `NONE`은 중복 이름을 거부, `AUTO`는 번호를 붙임
`pfs`	long	No	부모 폴더 seq. `ncp`가 `AUTO`면 사용하지 않음
`ss`	integer	No	공유 사용자 seq

Request
curl -X PATCH "https://drive.example.com/api/external/v1/files/{resourceSeq}/rename" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"ss": 21, "rn": "quarterly-report", "ncp": "AUTO"}'

응답의 data.name은 실제로 적용된 이름입니다. AUTO가 충돌을 해소한 경우 rn과 다를 수 있습니다.

파일 이동

api:write 필요

POST /api/external/v1/files/{resourceSeq}/move

파라미터	Type	필수	설명
`resourceSeq`	long	Yes	path 파라미터 - 이동할 파일
`ts`	integer	No	대상 사용자 seq. 호출자가 공유를 만든 당사자가 아니면 필수
`pfs`	long	No	이동할 폴더 seq. 호출자가 공유를 만든 당사자가 아니면 필수
`ss`	integer	No	공유 사용자 seq

Request
curl -X POST "https://drive.example.com/api/external/v1/files/{resourceSeq}/move" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"ts": 1, "pfs": 367}'

파일 복제

api:write 필요

POST /api/external/v1/files/{resourceSeq}/copy

파라미터	Type	필수	설명
`resourceSeq`	long	Yes	path 파라미터 - 복제할 파일
`ts`	integer	No	복제 대상 사용자 seq. 호출자가 공유 제공자면 `null`
`pfs`	long	No	복제할 폴더 seq. 공유 제공 사용자와 다르면 필수
`ss`	integer	No	공유 사용자 seq. 호출자가 공유 제공자면 `null`

Accept-Language 헤더를 선택적으로 받습니다. 성공하면 201 Created와 새 resourceSeq를 반환합니다. 계정 용량을 초과하면 RESOURCE_015로 실패합니다.

파일 삭제

api:write 필요

PATCH /api/external/v1/files/{resourceSeq}/delete

파라미터	Type	필수	설명
`resourceSeq`	long	Yes	path 파라미터 - 삭제할 파일

파일은 완전히 제거되지 않고 휴지통으로 이동합니다. 휴지통 목록·복원·영구 삭제는 Users를 참고합니다.

새 Office 문서 생성

api:write 필요

파일을 업로드하지 않고 내장 템플릿으로 빈 Word·Spreadsheet·Presentation·노트 문서를 만듭니다.

POST /api/external/v1/documents

파라미터	Type	필수	설명
`tt`	enum	Yes	템플릿 유형 - `word`, `excel`, `ppt`, `note`
`pfs`	long	No	부모 폴더 seq. 공유 리소스면 필수
`ss`	integer	No	공유 사용자 seq. 본인 드라이브에 만들면 `null`

Accept-Language 헤더가 템플릿 언어를 결정합니다. 현재 한국어와 미국 영어 템플릿이 제공됩니다.

Request
curl -X POST "https://drive.example.com/api/external/v1/documents" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"ss": 21, "pfs": 5, "tt": "word"}'

Create response
{
  "result": true,
  "code": 201,
  "message": "Created",
  "data": {
    "resourceSeq": 4699,
    "userSeq": 1
  }
}

계정 용량을 초과하면 QUOTA_003, 대상 폴더에 접근 권한이 없으면 PERMISSION_002로 실패합니다.

편집기 세션 endpoint

web-office endpoint는 브라우저 편집 세션을 뒷받침합니다. 편집기가 문서 메타데이터를 읽고, 파일을 가져오고, 편집하는 동안 잠그고, 다시 쓰고, 잠금을 해제합니다. Thinkfree 편집기를 직접 호스팅할 때 사용합니다. 지원되는 SDK로 편집기를 임베드하려면 Editor SDK를 참고합니다.

GET  /api/external/v1/web-office/{loginUserSeq}/info
GET  /api/external/v1/web-office/{loginUserSeq}/get
POST /api/external/v1/web-office/{loginUserSeq}/lock
PUT  /api/external/v1/web-office/{loginUserSeq}/put
POST /api/external/v1/web-office/{loginUserSeq}/unlock

호출자가 행위 주체를 지정함

loginUserSeq는 API Key에서 유도되지 않고 호출자가 직접 지정합니다. 서버는 지정된 사용자가 키와 같은 tenant에 속하는지만 확인하며, 그 사용자가 키의 계정과 일치하는지는 확인하지 않습니다. 따라서 키 보유자는 이 endpoint를 통해 해당 tenant의 어떤 사용자로도 행위할 수 있습니다. 이 endpoint에 도달할 수 있는 키는 tenant 전체 권한을 가진 credential로 취급하고, 브라우저가 보낸 loginUserSeq를 그대로 전달하지 말고 호출자가 어떤 사용자로 행위할 수 있는지 서버에서 결정합니다.

이 endpoint는 scope 검사를 거치지 않음

5개 모두 편집기 세션 흐름을 위해 scope 검사에서 제외되어 있습니다. api:read만 가진 키로도 저장 내용을 바꾸는 lock, put, unlock을 호출할 수 있습니다.

공통 파라미터

파라미터	Type	필수	설명
`loginUserSeq`	long	Yes	path 파라미터 - 세션이 행위할 사용자
`docId`	string	Yes	문서 식별자. 공유 사용자 seq와 리소스 seq를 하이픈으로 이은 값
`app`	enum	Yes	편집기 화면. 예: `WORD_EDITOR`, `CELL_VIEWER`, `SHOW_WATCHER`. `info`, `get`, `put`에 필수
`user_id`	string	Yes	로그인 계정 이름. `info`, `get`, `put`에 필수
`lang`	string	No	세션 언어. 예: `ko_KR`

app 값은 애플리케이션과 모드를 함께 나타냅니다. 애플리케이션은 WORD, CELL, SHOW, HWP, PDF이고, 모드는 EDITOR, VIEWER, WATCHER입니다.

문서 메타데이터 조회

GET /api/external/v1/web-office/{loginUserSeq}/info

JSON이 아니라 XML 문서를 반환하며, 파일 이름·크기·리비전·권한·잠금 상태와 공동 작업자 커서 이름·색상을 담고 있습니다.

Request
curl -X GET "https://drive.example.com/api/external/v1/web-office/{loginUserSeq}/info?app=WORD_EDITOR&user_id={user_id}&docId=21-512&lang=ko_KR" \
  -H "Authorization: Bearer replace-with-your-api-key"

지정한 사용자에게 공유되지 않은 리소스는 SHARE_001로 실패합니다.

문서 가져오기와 저장

GET /api/external/v1/web-office/{loginUserSeq}/get
PUT /api/external/v1/web-office/{loginUserSeq}/put

get은 파일을 application/octet-stream으로 스트리밍합니다. put은 교체할 본문을 application/octet-stream으로 업로드하고 docId를 평문으로 반환합니다.

파라미터	Type	필수	설명
`size`	long	Yes	업로드할 문서의 바이트 크기. `put` 전용
`type`	enum	No	저장 사유 - `save`, `saveAs`, `autoSave`, 세션 비정상 종료 시 `autoPut`, 문서를 닫을 때 `close`. 없을 수도 있음
`openTimestamp`	string	No	받기는 하지만 현재 사용하지 않음

문서 잠금과 잠금 해제

POST /api/external/v1/web-office/{loginUserSeq}/lock
POST /api/external/v1/web-office/{loginUserSeq}/unlock

둘 다 docId를 받고 본문 없이 200 OK를 반환합니다.

평문 실패 응답

이 reference의 다른 endpoint와 달리, lock과 unlock이 실패하면 JSON 공통 구조도 errorCode도 없는 평문 메시지가 반환됩니다. web-office endpoint의 권한 실패도 HTTP 403과 함께 평문으로 반환됩니다. 이 응답들은 본문이 아니라 상태 코드로 판별합니다.

에러

이 endpoint들이 반환하는 코드 전체 목록은 Errors를 참고합니다.

Base URL과 scope​

파일 다운로드​

브라우저로 다운로드 위임​

파일 미리보기​

파일 업로드​

파일 이름 변경​

파일 이동​

파일 복제​

파일 삭제​

새 Office 문서 생성​

편집기 세션 endpoint​

공통 파라미터​

문서 메타데이터 조회​

문서 가져오기와 저장​

문서 잠금과 잠금 해제​

에러​

Base URL과 scope

파일 다운로드

브라우저로 다운로드 위임

파일 미리보기

파일 업로드

파일 이름 변경

파일 이동

파일 복제

파일 삭제

새 Office 문서 생성

편집기 세션 endpoint

공통 파라미터

문서 메타데이터 조회

문서 가져오기와 저장

문서 잠금과 잠금 해제

에러