Cloud Office API
고객 서비스의 백엔드가 문서 URL을 요청하고, 사용자가 브라우저에서 문서를 보거나 편집합니다. Office 서버는 Thinkfree가 운영합니다. 고객 서비스는 별도 Cloud Office 패키지를 설치하지 않고 HTTP 클라이언트로 REST API를 호출합니다.
고객 서비스는 API로 브라우저 클라이언트 세션을 만들고 Office가 보고한 문서 상태를 조회합니다. 사용자는 Office 안에서 변경 내용을 저장할 수 있습니다. API로 Editor 문서를 저장하거나 현재 문서를 다운로드할 수 있습니다.
API를 호출하기 전에
- API 키 준비에 따라 키를 만듭니다.
- 백엔드에 키를 보관합니다. 아래 예제는 서버 환경변수
THINKFREE_API_KEY에서 키를 읽습니다. - 활성 스토리지의 문서를 선택하거나, Upload & Edit로 파일 하나를 업로드합니다.
- 고객 서비스에서 사용자를 인증하고, 해당 사용자가 문서에 접근할 수 있는지 확인한 뒤 문서 URL을 요청합니다.
브라우저 JavaScript, 모바일 앱, 문서 URL, 소스 코드나 로그에 키를 넣지 마세요. API 키는 Developer Console 계정을 식별합니다. 고객 서비스에 가입한 개별 사용자의 신원이나 문서 접근 권한은 고객 서비스에서 확인해야 합니다.
인증과 응답
기본 주소는 https://api.thinkfree.com입니다. 각 API 요청에 다음 헤더를 보냅니다.
Authorization: Bearer tfoak-replace-with-your-key
성공한 JSON 응답은 { "success": true, "code": 0, "codeDescription": "SUCCESS", "data": { ... } } 형식입니다.
결과는 data에서 읽습니다. 실패하면 HTTP 상태와 숫자 code로 오류를 구분하고, errorMessage로 실패 내용을 확인합니다.
문구는 바뀔 수 있으므로 메시지 문자열로 동작을 결정하지 마세요.
전체 필드는 응답 형식과 오류 코드를 참고하세요.
브라우저 화면과 API 호출 구분
고객 서비스는 POST /api/office/v1/client-sessions로 세션을 만듭니다. 저장소 문서는 JSON으로,
업로드 문서는 file과 request를 포함한 multipart로 보냅니다. request part의 Content-Type은 application/json으로 지정합니다.
브라우저는 browser.openUrl로 Office를 엽니다. 고객 서비스의 백엔드는 세션을 만든 API 키로 api.statusUrl을 호출합니다.
api 그룹에는 저장·다운로드 주소도 포함됩니다. Office 화면의 저장·다운로드 버튼은 별도의 브라우저 동작입니다.
사용자·문서 ID 준비
세션을 만들기 전에 백엔드가 관리하는 사용자·문서 대응 관계에서 userId와 docId를 읽습니다. 같은 사용자나 문서에는 같은 값을 재사용하고, 다른 사용자와 문서에는 다른 값을 배정하세요. 사용자의 표시 이름·이메일과 문서의 표시 파일 이름은 식별자가 아닙니다.
두 필드는 선택 항목이지만, 생략하면 독립된 세션 사이에 사용자나 문서 식별자가 유지되지 않습니다. 세션 생성에 성공할 때마다 새 clientSessionId를 반환합니다. 반복 열기나 공동 편집을 연동하기 전에 ID 역할과 재사용 사례를 확인하세요.
1. 문서 URL 요청하기
연결된 스토리지의 문서 열기
먼저 API 키 계정이 소유한 스토리지 목록을 조회합니다.
curl --fail-with-body \
https://api.thinkfree.com/api/office/v1/storages \
-H "Authorization: Bearer $THINKFREE_API_KEY"
ACTIVE 상태인 스토리지의 고정 식별자 storageId와 그 스토리지 안의 문서 상대 경로를 보냅니다.
사용자가 바꿀 수 있는 스토리지 이름은 API 식별자로 사용하지 않습니다.
curl --fail-with-body \
https://api.thinkfree.com/api/office/v1/client-sessions \
-H "Authorization: Bearer $THINKFREE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"clientType": "BROWSER",
"mode": "EDITOR",
"storageId": "74a73536-3024-48c2-a850-76cf7872323f",
"documentPath": "proposals/proposal-2026-0042.docx",
"userId": "user-1042",
"docId": "proposal-2026-0042",
"userDisplayName": "Alex Kim",
"language": "en_US"
}'
스토리지 ID와 경로를 실제 값으로 바꾸세요. 이 예제에서 Alex는 항상 user-1042를 사용하고, 이 제안서를 열 때는 매번 proposal-2026-0042를 사용합니다. 다른 공동 편집 참여자는 자신의 userId를 사용하되 문서 ID와 경로는 이 예제와 동일하게 보냅니다.
userDisplayName, userEmail, userAvatarUrl은 선택 입력하는 프로필 정보입니다. userAvatarUrl에는 로그인·인증 헤더·인증 쿠키 없이 누구나 읽을 수 있는 공개 HTTPS 이미지 주소를 사용하세요. 이 필드는 Beta이며, Office 프로필 아이콘 표시에는 아직 적용되지 않습니다.
Office는 편집한 문서를 연결된 스토리지에 저장합니다. 고객 서버도 열기 성공 후 종료 전에 api.saveUrl이나 api.downloadUrl을 호출할 수 있습니다.
파일을 업로드해서 열기
Upload & Edit에는 스토리지 설정이 필요하지 않습니다. 파일을 multipart로 보내고, 경계 문자열은 HTTP 클라이언트가 설정하도록 두세요.
curl --fail-with-body \
https://api.thinkfree.com/api/office/v1/client-sessions \
-H "Authorization: Bearer $THINKFREE_API_KEY" \
-F "file=@./sample.docx" \
-F 'request={"clientType":"BROWSER","mode":"EDITOR","userId":"user-1042","docId":"upload-2026-0081","userDisplayName":"Alex Kim"};type=application/json'
여기서 upload-2026-0081은 업로드한 사본을, user-1042는 동일한 사용자 Alex를 식별합니다. 별도로 업로드한 사본에는 별도 문서 ID가 필요합니다. 파일 이름이 같다는 이유로 스토리지의 제안서나 이전 업로드와 같은 문서로 간주하지 마세요.
두 요청 형식 모두 HTTP 201을 반환합니다. 응답의 data 안에서 clientSessionId, mode, browser.openUrl, browser.openUrlExpiresAt, api.statusUrl, api.downloadUrl을 확인합니다. EDITOR 세션에는 api.saveUrl도 있습니다. 저장·다운로드 API는 문서를 연 뒤 호출합니다. 지원 파일, 크기 제한과 전체 응답 예제는
업로드 가이드에서 확인하세요.
2. 선택한 URL을 브라우저에서 열기
고객 서비스는 로그인한 대상 사용자에게 응답의 browser.openUrl을 전달합니다. 브라우저는 API 키 헤더 없이 이 URL을
직접 열거나 Office iframe에 넣습니다. 각 URL의 티켓은 한 번만 사용할 수 있으며, 현재 발급 후 5분이 지나면
만료됩니다. 사용자가 문서를 열 준비가 되었을 때 URL을 요청하세요. URL을 로그, 분석 도구나 지원 메시지에 남기지 마세요.
최초 열기 티켓이 만료되었거나 이미 사용했다면 새 브라우저 클라이언트 세션을 요청합니다. Upload & Edit에서는 파일을
다시 업로드해야 합니다. 파일이나 docId를 다시 보내 이전 편집 내용을 복구하는 기능은 제공하지 않습니다.
세션을 만들 때 mode를 선택합니다. 편집이 필요하면 처음부터 EDITOR를 선택하세요. 이미 만든 Viewer 세션의 모드를 변경하는 API는 제공하지 않습니다.
EDITOR 모드에서는 사용자가 문서를 연 시각부터 최대 12시간 동안 편집할 수 있습니다. 12시간이 지나면 해당 세션에서 더 이상 편집할 수 없습니다. 이 제한은 URL을 처음 열 수 있는 5분 기한과 별개입니다.
3. 마지막으로 전달받은 상태 조회하기
백엔드는 세션을 만든 API 키로 응답의 api.statusUrl을 호출합니다. 같은 계정의 다른 키로는 이 세션에 접근할 수 없습니다. 아래 예제 ID를 실제 clientSessionId로 바꾸세요.
curl --fail-with-body \
https://api.thinkfree.com/api/office/v1/client-sessions/YOUR_CLIENT_SESSION_ID \
-H "Authorization: Bearer $THINKFREE_API_KEY"
status는 CREATED, OPEN, FAILED, CLOSED 중 하나입니다. lastSavedAt과 saveCount는 Office에서 전달받은
저장 성공 이벤트를 나타냅니다. 응답은 마지막으로 전달받은 상태이며, 브라우저의 실시간 상태나 현재 편집 내용의
저장 완료를 보장하지 않습니다. 반복 조회할 때는 조회 간격과 전체 대기 시간을 제한하세요. 값이 바뀌지 않았다는
이유만으로 문서 열기나 저장에 실패했다고 판단하지 마세요.
4. API로 저장하거나 다운로드하기
두 문서 제공 방식의 응답에는 api.downloadUrl이 포함되며, EDITOR 세션에는 api.saveUrl도 포함됩니다.
문서 열기에 성공한 뒤 세션을 만든 API 키로 POST api.saveUrl을 호출해 Editor 문서를 저장하거나, GET api.downloadUrl을 호출해 파일 바이트를 받습니다. 종료한 문서나 12시간의 작업 기한이 지난 문서에는 두 API를 사용할 수 없습니다.
두 endpoint는 세션을 만든 API 키, 문서 상태, 스토리지 상태와 사용 기한을 검사합니다. Viewer 세션은 저장 endpoint를 사용할 수 없습니다. 요청 조건과 응답 형식은 API Reference에서 확인하세요.
어떤 만료 시각을 확인해야 하나요?
| 항목 | 사용 가능한 기간 |
|---|---|
browser.openUrl | browser.openUrlExpiresAt 이전에 한 번만 열 수 있습니다. 문서를 처음 열 수 있는 기한입니다. |
| Editor 세션 | 문서를 연 시각부터 최대 12시간 동안 편집할 수 있습니다. 이후에는 해당 세션에서 편집할 수 없습니다. |
api.statusUrl | closedAt부터 1시간까지입니다. 종료 성공 기록이 없으면 documentOpenedAt부터 12시간, 열기 성공 기록도 없으면 createdAt부터 12시간까지입니다. |
| 저장·다운로드 API | 열기 성공 기록이 필요하며, 종료 성공을 보고받거나 documentOpenedAt부터 12시간이 지나면 요청을 거절합니다. |
| API 키 | API를 호출할 때마다 유효해야 합니다. API 키의 만료·폐기와 위 기한은 별개입니다. |
documentOpenedAt과 closedAt은 Office가 보고한 이벤트 발생 시각이며, Developers가 이벤트를 받은 시각과 다릅니다. Developers는 API 요청을 검사할 때 사용 기한을 확인합니다.
업로드한 임시 파일은 장기 보관에 사용하지 마세요. 각 필드는 API Reference에서 확인하세요.
문서 열기에 사용하는 크레딧
링크를 만들 때는 크레딧을 차감하지 않으며 creditsCharged: 0을 반환합니다. 최초 링크 발급 시에는 선택한 모드에 따라 뷰어(VIEWER)는 5크레딧, 에디터(EDITOR)는 10크레딧을 사용할 수 있는지 확인합니다. 문서 열기에 성공하면 Viewer는 5크레딧, Editor는 10크레딧을 차감합니다. 열기에 실패하면 차감하지 않습니다.
사용 가능한 크레딧에는 허용 한도 안의 후불 사용량도 포함됩니다. 크레딧이 부족하면 HTTP 402, 코드
4020 INSUFFICIENT_CREDIT를 반환합니다. 잔액과 만료일은 Credits에서,
요금제와 후불 설정은 Billing에서 확인하세요.
API 목록
| 메서드 | 경로 | 하는 일 |
|---|---|---|
GET | /api/office/v1/storages | 계정 소유 스토리지 목록을 조회합니다. 스토리지의 비밀정보는 응답에서 제외합니다. |
POST | /api/office/v1/client-sessions | 저장소 문서(JSON) 또는 업로드 파일(multipart)의 세션 생성 |
GET | /api/office/v1/client-sessions/{clientSessionId} | 문서에 대해 마지막으로 전달받은 상태를 조회합니다. |
POST | /api/office/v1/client-sessions/{clientSessionId}/save | Editor 문서 저장 |
GET | /api/office/v1/client-sessions/{clientSessionId}/download | 현재 문서 다운로드 |
상태 조회 API의 응답 필드와 조회 조건을 확인하세요.
직접 호출해 보기
아래 도구는 테스트 키를 현재 탭의 메모리에만 보관합니다. 폐기할 수 있는 테스트 키를 사용하세요. 실제 고객 서비스에서는 백엔드에서 API를 호출해야 합니다.
Cloud Office API 호출
키는 tfoak-로 시작해야 합니다.
스토리지 연결 목록 조회
이 키의 계정이 소유한 연결의 비밀 정보가 없는 요약만 반환합니다.
GET /api/office/v1/storages브라우저 클라이언트 세션 만들기
활성 스토리지 연결을 사용하거나, 연결을 만들지 않고 단기 보관 문서 하나를 업로드합니다.
클라이언트 세션 옵션(선택 사항)
선택 값은 입력한 경우에만 Office로 전달합니다. docId를 생략하면 Developers가 세션마다 새 문서 ID를 만듭니다. language와 skin을 생략하면 Office의 언어·스킨 설정을 사용합니다. 연결된 스토리지의 문서를 공동 편집하려면 같은 문서에 동일한 docId 접미사를 사용하고, 참여자마다 서로 다른 고정 userId를 사용하세요.
POST /api/office/v1/client-sessions예제를 사용하려면 테스트용 API 키를 입력하세요.