라이선스

Exchange는 @univerjs-pro/exchange-node를 실행하는 서버 프로세스에서 라이선스를 읽습니다. 변환 방법은 Office 파일 가져오기 및 내보내기를 참고하세요.

인증 설정

라이선스는 환경 변수 UNIVER_LICENSE와 UNIVER_LICENSE_KEY로 한 쌍으로 제공하는 것을 권장합니다. configureExchange를 호출할 필요는 없습니다. SDK는 첫 내보내기 또는 할당량 조회 시 환경 변수를 한 번 읽고 이후 그 설정을 재사용합니다. 환경에 자격 증명이 없으면 Free가 적용됩니다. 제공되었지만 유효하지 않은 자격 증명은 오류를 반환하며 내보내기에 사용할 수 없습니다.

명시적으로 설정하려면 configureExchange({ license, licenseKey })를 사용합니다. Promise<void>를 반환하며 환경 변수를 완전히 무시합니다. 새 자격 증명을 사용할 내보내기는 설정이 끝날 때까지 기다린 뒤 시작하세요.

import { configureExchange, getExportQuota } from '@univerjs-pro/exchange-node'await configureExchange({  license: '<license content>',  licenseKey: '<licenseKey content>',})const quota = await getExportQuota()

license와 licenseKey에는 라이선스 제공자에게 받은 전체 내용을 넣습니다. 파일 경로가 아닙니다. 두 값을 한 쌍으로, 애플리케이션의 시크릿 관리 시스템을 통해 제공하세요.

완전한 환경 설정을 한 번 읽으면 이후 작업이 실패하더라도 고정됩니다. 실행 중에 기본 자격 증명을 바꾸려면 configureExchange를 명시적으로 호출하고 완료를 기다리세요. 설정에 실패하면 이전 설정이 유지되므로, 오류를 처리한 뒤 새 내보내기를 시작하세요.

같은 JavaScript 컨텍스트의 ESM과 CommonJS는 설정을 공유합니다. 각 worker_threads Worker는 따로 설정하거나 환경 변수로 초기화해야 합니다. 내보내기는 공개 내보내기 메서드를 호출한 시점의 설정을 사용하며, 이후 자격 증명을 바꿔도 이미 시작된 내보내기에는 영향을 주지 않습니다.

한 번의 작업에 인증 지정

내보내기 API나 getExportQuota의 옵션에 완전한 license와 licenseKey 쌍을 전달하면 기본 설정을 바꾸지 않고 그 작업만 인증할 수 있습니다. 예를 들어 같은 자격 증명으로 할당량을 조회하고 내보냅니다.

import { UniverInstanceType } from '@univerjs/core'import { ExchangeFormat, exportToBuffer, getExportQuota } from '@univerjs-pro/exchange-node'const credentials = { license: '<license content>', licenseKey: '<licenseKey content>' }const quota = await getExportQuota(credentials)const output = await exportToBuffer(workbook, {  type: UniverInstanceType.UNIVER_SHEET,  format: ExchangeFormat.XLSX,  ...credentials,})

파일 내보내기, Snapshot 내보내기, 선택적 PDF 내보내기에도 똑같이 적용됩니다. 두 필드를 모두 생략하면 기본 설정을 사용하고, 하나만 제공하면 INVALID_ARGUMENT를 반환합니다. 명시한 쌍은 기본 설정이나 환경 변수로 보완되지 않으며, 빈 문자열도 생략으로 간주하지 않습니다. 유효하지 않은 자격 증명은 LICENSE_INVALID를 반환하고 기본 상용 라이선스로 대체하지 않습니다.

선택적 PDF 지원

PDF 확장 패키지를 설치하고, 인증을 설정하기 전에 해당 진입점을 가져옵니다.

pnpm add @univerjs-pro/exchange-node @univerjs-pro/exchange-pdf-node-binding

import '@univerjs-pro/exchange-node/pdf'import { configureExchange, getExportQuota } from '@univerjs-pro/exchange-node'await configureExchange({  license: '<license content>',  licenseKey: '<licenseKey content>',})const quota = await getExportQuota()

이 진입점은 PDF 지원을 등록하며, 네이티브 구성 요소는 사용할 때 불러옵니다. PDF도 같은 importBuffer, importFile, exportToBuffer, exportToFile과 해당 Snapshot API를 사용하고 UniverInstanceType.UNIVER_PDF와 ExchangeFormat.PDF를 지정합니다. PDF만 처리하는 애플리케이션은 Office 네이티브 구성 요소를 불러올 필요가 없습니다. 환경 변수 설정은 PDF에도 적용됩니다.

남은 할당량 조회

getExportQuota({ license, licenseKey })는 Promise<ExportQuota>를 반환하며, 해당 인증에서 Office와 PDF가 공유하는 할당량을 조회합니다. 자격 증명을 생략하면 기본 설정을 조회합니다. Unit 유형을 받지 않으며 특정 유형의 내보내기 권한도 확인하지 않습니다. 그 확인은 내보내기 시점에 이루어집니다.

조회는 할당량을 소비하거나 예약하지 않으며, SDK 버전, 활성화 시각, 내보내기 유형 권한도 확인하지 않습니다. 잔여량이 0이어도 조회는 성공하여 스냅샷을 반환합니다. 다른 요청이 그 뒤에 할당량을 사용할 수 있으므로 실제 내보내기 오류도 처리하세요.

인증이 시작되기 전에는 할당량이 제한된 경우 첫 인증 월의 스냅샷이 미래의 periodStart와 함께 반환됩니다. 조회 성공이나 valid 상태가 내보내기를 허용한다는 뜻은 아닙니다. 버전, 활성화 시각, 유형 권한, 사용 가능한 할당량, 동시 실행 확인은 내보내기 시점에 이루어집니다.

periodEnd는 다음 월 할당량 기간이 시작되는 시각이고, expiresAt은 내보내기 구독 전체가 끝나는 시각입니다. 유효한 구독은 항상 상용 할당량을 사용합니다. 다 써도 Free로 바뀌지 않으며 다음 달부터 새 상용 할당량 기간이 시작됩니다. 구독이 만료된 경우에만 기존 Free 잔여량을 사용하며, Free 할당량을 초기화하거나 다시 지급하지 않습니다.

할당량이 제한된 스냅샷 예시:

{  "licenseStatus": "valid",  "expiresAt": "2027-10-19T23:59:59Z",  "observedAt": "2026-10-21T09:00:00Z",  "limit": 500,  "used": 20,  "reserved": 1,  "remaining": 479,  "periodStart": "2026-10-19T00:00:00Z",  "periodEnd": "2026-11-19T00:00:00Z"}

할당량 사용

Free는 인증 월마다 내보내기 성공 10회를 허용합니다. 상용 라이선스의 내보내기 할당량, 동시 실행 수, 버전 범위는 구매한 라이선스에 따릅니다. Free와 상용 라이선스 모두 파일 크기나 셀 수 제한을 두지 않습니다. 현재 기간과 남은 할당량은 조회 결과로 확인하세요. 사용하지 않은 월 할당량은 이월되지 않습니다.

가져오기에는 내보내기 인증이 필요 없으며 내보내기 할당량도 소비하지 않습니다. 같은 배포에서 같은 상용 라이선스를 사용하는 Office와 PDF 내보내기는 할당량을 공유합니다. Exchange 변환 형식은 Office 파일 가져오기 및 내보내기를 참고하세요.

변환에 한 번 성공할 때마다 내보내기 1회를 소비합니다. Buffer를 반환하면 성공으로 봅니다. 이후 파일 쓰기, 업로드, 다운로드가 실패해도 반환되지 않으며, 다시 변환에 성공하면 1회를 더 소비합니다. 현재 기간에 남은 할당량이 없으면 새 내보내기는 거부됩니다. 다음 인증 기간을 기다리거나 할당량이 더 큰 유효한 라이선스를 사용하세요. 다 쓴 유효한 상용 라이선스는 Free 할당량을 사용하지 않습니다.

오류 처리

message 텍스트를 파싱하지 말고 구조화된 code로 오류를 식별하세요. UI에서는 오류 코드를 현지화된 메시지에 연결할 수 있습니다. 진단 정보는 기술 지원을 위해 보관하세요.

import { UniverInstanceType } from '@univerjs/core'import { ExchangeError, ExchangeFormat, exportToBuffer } from '@univerjs-pro/exchange-node'try {  const output = await exportToBuffer(workbook, {    type: UniverInstanceType.UNIVER_SHEET,    format: ExchangeFormat.XLSX,  })} catch (error) {  if (error instanceof ExchangeError) {    // error.code에 맞는 메시지를 표시. 할당량이 부족하면 LICENSE_EXPORT_QUOTA_EXCEEDED    console.error(error.code)  } else {    throw error  }}

아래 표는 할당량 조회(getExportQuota)와 실제 내보내기에서 오류가 발생하는 시점을 구분합니다. 두 API 모두 Promise를 반환하므로 await와 try/catch로 실패를 처리하세요.

만료 알림은 애플리케이션이 licenseStatus와 expiresAt으로 직접 만들 수 있습니다. SDK는 별도의 알림 목록을 반환하지 않습니다.

라이선스 사용량 처리 오류가 발생하면 오류만으로 계산 여부를 추측하지 마세요. 전체 오류를 보관하고 기술 지원에 문의하세요.