Лицензия

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 и дождитесь его завершения. При ошибке настройки продолжает действовать прежняя конфигурация; обработайте ошибку, прежде чем запускать новые экспорты.

ESM и CommonJS используют общую конфигурацию в одном контексте JavaScript. Каждый Worker из worker_threads должен настраиваться сам или инициализироваться из своего окружения. Экспорт использует конфигурацию на момент вызова публичного метода экспорта; последующая смена учётных данных не влияет на уже запущенные экспорты.

Авторизация одной операции

Передайте полную пару license и licenseKey в параметрах API экспорта или getExportQuota, чтобы авторизовать только эту операцию, не меняя конфигурацию по умолчанию. Например, запросите квоту и выполните экспорт с одними и теми же учётными данными:

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 применяются те же API importBuffer, importFile, exportToBuffer, exportToFile и соответствующие API Snapshot с UniverInstanceType.UNIVER_PDF и ExchangeFormat.PDF. Приложению, работающему только с PDF, не нужно загружать нативный компонент Office. Настройка через окружение действует и для PDF.

Запрос оставшейся квоты

getExportQuota({ license, licenseKey }) возвращает Promise<ExportQuota> с квотой, общей для Office и PDF в рамках авторизации. Без учётных данных запрашивается конфигурация по умолчанию. Метод не принимает тип Unit и не проверяет право на экспорт конкретного типа; эта проверка выполняется при экспорте.

Запросы не расходуют и не резервируют квоту и не проверяют версию SDK, дату активации или право на тип экспорта. При нулевом остатке запрос всё равно успешно возвращает снимок. Другие запросы могут израсходовать квоту позже, поэтому обрабатывайте и ошибки самого экспорта.

До начала авторизации запрос с ограниченной квотой возвращает первый месяц авторизации с periodStart в будущем. Успешный запрос или состояние valid не дают права на экспорт. Версия, активация, право на тип, доступная квота и параллельность проверяются при экспорте.

periodEnd отмечает начало следующего месячного периода квоты; expiresAt — окончание подписки на экспорт. Действующая подписка всегда использует коммерческую квоту. Её исчерпание никогда не переключает на 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.

Каждая успешная конвертация расходует один экспорт. Возврат Buffer считается успехом. Последующая ошибка записи, загрузки или скачивания файла не возвращает этот экспорт; новая успешная конвертация расходует ещё один. Когда в текущем периоде квота закончилась, новые экспорты отклоняются. Дождитесь следующего периода авторизации или используйте действующую лицензию с большей квотой; исчерпанная действующая коммерческая лицензия не использует квоту Free.

Обработка ошибок

Определяйте ошибки по структурированному code, а не разбирая текст message. Интерфейс может сопоставлять коды ошибок с локализованными сообщениями. Сохраняйте диагностическую информацию для технической поддержки.

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 не возвращает отдельный список уведомлений.

После ошибки обработки использования лицензии не делайте выводов об учёте только по ошибке. Сохраните полную ошибку и обратитесь в техническую поддержку.