Upload & Edit

스토리지 연결 없이 문서를 업로드하고 편집할 수 있습니다. 백엔드에서 Office 파일 하나를 보내고 응답의 browser.openUrl로 대상 사용자의 브라우저에서 문서를 엽니다.

Developer Console API 키와 지원되는 Office 파일 하나가 필요합니다. 아직 키가 없다면 API 키 준비부터 시작하세요. 브라우저 코드가 아닌 백엔드에 키를 보관하세요.

최대 업로드 크기는 100 MB(104,857,600바이트, 100 MiB)입니다. 지원 확장자는 doc, docx, odt, xls, xlsx, ods, ppt, pptx, odp입니다. 파일은 확장자 계열과 일치하는 OOXML/ODF ZIP 또는 legacy OLE container signature를 가져야 합니다. 임의 파일의 확장자만 바꾸어도 Office 문서가 되는 것은 아닙니다. 업로드한 임시 파일은 장기 보관에 사용하지 마세요.

API로 저장하고 다운로드하기

문서 열기에 성공한 뒤 백엔드에서 세션을 만든 API 키로 api.downloadUrl을 호출할 수 있습니다. Editor 세션의 api.saveUrl은 POST로 호출합니다. 문서를 닫으면 두 작업을 사용할 수 없습니다.

작업 흐름

고객 서비스의 백엔드는 file과 request JSON(clientType: "BROWSER", mode: "EDITOR")을 포함한 multipart/form-data 요청을 보냅니다. request part의 Content-Type은 application/json으로 지정합니다. 읽기 전용으로 열려면 VIEWER를 선택합니다.
대상 사용자의 브라우저에서 browser.openUrl을 엽니다.
사용자가 Office 안에서 문서를 편집하고 저장합니다.
백엔드는 api.statusUrl을 호출해 마지막으로 전달받은 문서 상태를 확인합니다. 반복 조회한다면 조회 간격과 전체 대기 시간을 제한하세요.
사용자가 문서를 닫기 전에 백엔드는 POST api.saveUrl로 저장을 요청하거나 GET api.downloadUrl로 파일 바이트를 받을 수 있습니다. 저장한 뒤 다운로드하려면 data.saved: true를 확인하고 다운로드를 요청하세요.

curl --fail-with-body \
  -X POST https://api.thinkfree.com/api/office/v1/client-sessions \
  -H "Authorization: Bearer tfoak-replace-with-your-key" \
  -F "file=@./sample.docx" \
  -F 'request={"clientType":"BROWSER","mode":"EDITOR","fileDisplayName":"customer-proposal.docx","userId":"user-1042","docId":"upload-2026-0081"};type=application/json'

multipart 파일에 이미 파일 이름이 있으면 fileDisplayName은 선택 사항입니다. 이 값은 Office에 표시할 이름을 정하며 확장자로 문서 앱을 선택합니다. 파일 내용과 일치하는 확장자를 사용하세요. request에는 storageId와 documentPath를 넣지 않습니다.

예제는 고객 서비스의 사용자를 user-1042, 이번에 업로드한 사본을 upload-2026-0081로 식별합니다. 고객 서비스의 레코드에 연결한 ID로 바꾸세요. 같은 사용자의 ID는 업로드가 달라져도 유지하고, 별도로 업로드한 사본에는 별도 문서 ID를 배정합니다. 업로드할 때마다 별도의 임시 원본 파일을 만듭니다. 이름이나 내용이 같다는 이유로 같은 문서로 간주하지 마세요. 이 API는 docId로 이전 업로드를 다시 여는 기능을 제공하지 않습니다.

userId와 docId는 선택 항목입니다. 생략하면 독립된 세션 사이에 사용자나 문서의 식별자가 유지되지 않습니다. ID 재사용과 생략 규칙을 참고하세요. 같은 저장 문서를 반복해서 열거나 공동 편집해야 한다면 Bring Your Own Storage를 사용하세요.

응답

요청이 성공하면 HTTP 201 Created가 반환됩니다. 아래는 Editor 세션의 응답 예제입니다. browser.openUrl은 Office를 여는 주소이며, api에는 백엔드에서 상태 조회·저장·다운로드에 사용할 주소가 포함됩니다. Viewer 응답에서는 api.saveUrl이 생략됩니다.

{
  "success": true,
  "code": 0,
  "codeDescription": "SUCCESS",
  "data": {
    "clientSessionId": "9169250d-5328-4d45-844b-9a37cb52f7ac",
    "clientType": "BROWSER",
    "documentSourceType": "UPLOAD",
    "documentLifecycleId": "0d102ee8-cbdd-4667-a5cf-f2e3a1007927",
    "mode": "EDITOR",
    "status": "CREATED",
    "creditsCharged": 0,
    "createdAt": "2026-08-11T10:00:00Z",
    "browser": {
      "openUrl": "https://office.developers.thinkfree.com/cloud-office/api/open-document?ticket=<ticket>",
      "openUrlExpiresAt": "2026-08-11T10:05:00Z"
    },
    "api": {
      "statusUrl": "https://api.thinkfree.com/api/office/v1/client-sessions/9169250d-5328-4d45-844b-9a37cb52f7ac",
      "saveUrl": "https://api.thinkfree.com/api/office/v1/client-sessions/9169250d-5328-4d45-844b-9a37cb52f7ac/save",
      "downloadUrl": "https://api.thinkfree.com/api/office/v1/client-sessions/9169250d-5328-4d45-844b-9a37cb52f7ac/download"
    }
  }
}

documentSourceType은 이 클라이언트 세션이 Upload & Edit를 통해 생성되었으므로 UPLOAD입니다. 이 값은 문서의 유입 경로를 나타내며, 요청의 mode와는 별개입니다.

Save As는 사용할 수 없습니다

Upload & Edit 문서를 다른 스토리지의 새 파일로 Save As할 수 없습니다.

예제의 <ticket>은 응답 URL에 포함된 티켓 값을 나타내는 자리 표시자입니다. 티켓을 직접 만들거나 Office URL에 API 키를 추가하지 마세요. browser.openUrl로 문서를 여세요. 각 티켓은 한 번만 사용할 수 있습니다. 모든 응답 필드는 API Reference에서 확인합니다.

링크를 만들 때는 크레딧을 차감하지 않으며 creditsCharged: 0을 반환합니다. 문서 열기가 성공하면 뷰어는 5크레딧, 편집기는 10크레딧을 차감합니다. 열기에 실패하면 차감하지 않습니다. 링크 발급 전에는 선택한 모드에 따라 뷰어(VIEWER)는 5크레딧, 에디터(EDITOR)는 10크레딧을 사용할 수 있는지 확인하며, 후불 사용에 동의한 계정은 허용 한도 내 초과 사용량을 포함합니다. 사용할 수 있는 크레딧이 부족하면 HTTP 402 / 4020 INSUFFICIENT_CREDIT를 반환합니다.

사용해 보세요

폐기할 수 있는 테스트용 API 키를 입력하고 Office 문서를 선택한 뒤 양식을 제출합니다. 성공하면 선택한 모드로 문서를 열거나 마지막으로 전달받은 상태를 조회할 수 있습니다. 이 폼에서는 문서 열기와 상태 조회를 확인합니다. 서버에서 저장·다운로드하려면 API 예제를 사용하세요. 키가 없다면 Developer Console의 API Keys에서 만듭니다.

대화형 API Explorer

문서를 업로드하고 Office 열기

저장 안 함

API Key는 저장되지 않습니다. 이 양식은 키를 현재 탭의 메모리에만 보관하고 브라우저 저장소에는 기록하지 않습니다. 브라우저의 네트워크 검사기에서는 키가 보이므로 폐기할 수 있는 테스트용 키를 사용하고, 프로덕션에서는 신뢰할 수 있는 백엔드에서 API를 호출하세요.

테스트용 API 키를 입력하고 Office 문서를 선택하세요.

브라우저에서 편집기 열기

EDITOR 모드에서는 사용자가 문서를 연 시각부터 최대 12시간 동안 편집할 수 있습니다. 12시간이 지나면 해당 세션에서 더 이상 편집할 수 없습니다. 이 제한은 URL을 처음 열 수 있는 5분 기한과 별개입니다.

API 키는 백엔드에 보관하고 업로드 요청도 백엔드에서 보냅니다. 백엔드는 로그인한 대상 사용자의 브라우저에 Office URL을 전달합니다. 사용자가 열기 버튼을 누르면 브라우저가 해당 URL을 엽니다. 편집하려면 에디터 열기, VIEWER로 생성한 세션에서는 뷰어 열기를 선택합니다. 이 URL을 가진 사람이 문서를 열 수 있으며, 티켓은 발급 후 5분이 지나면 만료됩니다. 의도한 로그인 사용자에게만 전달하고 로그, 분석, 지원 메시지 또는 영구 브라우저 저장소에 기록하지 않습니다.

브라우저는 API 키 헤더 없이 Office URL을 엽니다. 백엔드는 세션을 만든 API 키로 api.statusUrl을 호출합니다. 같은 계정의 다른 키로는 이 세션에 접근할 수 없습니다.

상태 확인은 백엔드에서 수행합니다. 아래 주소의 예제 ID 대신 업로드 응답의 clientSessionId를 사용하고, 세션을 만들 때 사용한 동일한 API 키를 전달합니다.

curl --fail-with-body \
  https://api.thinkfree.com/api/office/v1/client-sessions/YOUR_CLIENT_SESSION_ID \
  -H "Authorization: Bearer tfoak-replace-with-your-key"

lastSavedAt은 Office에서 받은 가장 최근의 저장 성공 시각입니다. 이 값만으로 현재 화면의 모든 편집 내용이 저장됐다고 판단할 수는 없습니다.

예상 결과

Office는 업로드한 문서를 선택한 모드로 엽니다. 백엔드는 세션을 만든 API 키로 마지막으로 전달받은 상태를 조회할 수 있습니다. 상태 조회 기한은 closedAt부터 1시간입니다. Office가 종료 성공을 보고하지 않았다면 documentOpenedAt부터 12시간, 열기 성공도 보고하지 않았다면 createdAt부터 12시간입니다.

저장·다운로드 API는 문서 상태와 사용 기한을 확인합니다. 문서를 닫은 뒤에는 두 API를 사용할 수 없습니다. 유효기간 비교를 참고하세요.

전체 필드는 Cloud Office API Reference에서 확인하세요. 고객 스토리지에 계속 보관할 문서는 Bring Your Own Storage를 사용하세요.

작업 흐름​

응답​

사용해 보세요​

문서를 업로드하고 Office 열기

브라우저에서 편집기 열기​

예상 결과​

작업 흐름

응답

사용해 보세요

브라우저에서 편집기 열기

예상 결과