Licencia

Exchange lee la licencia en el proceso de servidor que ejecuta @univerjs-pro/exchange-node. Consulta Importación y exportación de archivos de Office para la conversión.

Configurar la autorización

Proporciona la licencia mediante las variables de entorno UNIVER_LICENSE y UNIVER_LICENSE_KEY. Llamar a configureExchange es opcional: el SDK lee el entorno una vez en la primera exportación o consulta de cuota y reutiliza esa configuración. Sin credenciales en el entorno se aplica Free. Unas credenciales proporcionadas pero no válidas devuelven un error y no se pueden usar para exportar.

Para una configuración explícita, configureExchange({ license, licenseKey }) devuelve Promise<void> e ignora por completo el entorno. Espera a que termine antes de iniciar las exportaciones que deban usar las nuevas credenciales.

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

Usa el contenido completo de license y licenseKey que te entregue el proveedor de la licencia, no rutas de archivo. Configura ambos juntos mediante el sistema de gestión de secretos de tu aplicación.

Una vez leída una configuración de entorno completa, queda fijada aunque una operación posterior falle. Para sustituir las credenciales predeterminadas en tiempo de ejecución, llama explícitamente a configureExchange y espera a que termine. Si la configuración falla, sigue vigente la anterior; gestiona el error antes de iniciar nuevas exportaciones.

ESM y CommonJS comparten la configuración dentro del mismo contexto de JavaScript. Cada Worker de worker_threads debe configurarse por sí mismo o inicializarse desde su entorno. Las exportaciones usan la configuración vigente al llamar al método público de exportación; los cambios posteriores de credenciales no afectan a las exportaciones ya iniciadas.

Autorizar una sola operación

Pasa un par completo de license y licenseKey en las opciones de una API de exportación o de getExportQuota para autorizar solo esa operación sin cambiar la configuración predeterminada. Por ejemplo, consulta la cuota y exporta con las mismas credenciales:

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,})

Esto se aplica también a las exportaciones a archivo, de Snapshot y a las exportaciones PDF opcionales. Omitir ambos campos usa la configuración predeterminada; aportar solo uno devuelve INVALID_ARGUMENT. Un par explícito nunca se completa con la configuración predeterminada ni con el entorno, y las cadenas vacías no cuentan como omitidas. Unas credenciales no válidas devuelven LICENSE_INVALID sin recurrir a la licencia comercial predeterminada.

Compatibilidad opcional con PDF

Instala el paquete de extensión PDF e importa su punto de entrada antes de configurar la autorización:

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()

Este punto de entrada registra la compatibilidad con PDF; los componentes nativos se cargan al usarse. PDF usa las mismas API importBuffer, importFile, exportToBuffer, exportToFile y sus equivalentes de Snapshot con UniverInstanceType.UNIVER_PDF y ExchangeFormat.PDF. Una aplicación que solo trabaja con PDF no necesita cargar el componente nativo de Office. La configuración por entorno también se aplica a PDF.

Consultar la cuota restante

getExportQuota({ license, licenseKey }) devuelve Promise<ExportQuota> con la cuota que la autorización comparte entre Office y PDF. Sin credenciales, consulta la configuración predeterminada. No acepta un tipo de Unit ni comprueba el permiso para exportar un tipo concreto; esa comprobación se hace durante la exportación.

Las consultas no consumen ni reservan cuota, y no comprueban la versión del SDK, la fecha de activación ni el derecho por tipo de exportación. Con saldo cero también devuelven una instantánea correcta. Otras solicitudes pueden consumir cuota después, así que gestiona también los errores de la exportación real.

Antes de que empiece la autorización, una consulta con cuota limitada devuelve el primer mes de autorización con un periodStart futuro. Una consulta correcta o un estado valid no conceden permiso para exportar. La versión, la activación, el derecho por tipo, la cuota disponible y la concurrencia se comprueban durante la exportación.

periodEnd marca el inicio del siguiente periodo mensual de cuota; expiresAt marca el fin de la suscripción de exportación. Una suscripción válida siempre usa la cuota comercial. Agotarla nunca selecciona Free, y un nuevo periodo de cuota comercial empieza el mes siguiente. Solo la caducidad de la suscripción selecciona la cuota Free restante, sin restablecerla ni volver a concederla.

Ejemplo de instantánea con cuota limitada:

{  "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"}

Uso de la cuota de exportación

Free permite 10 exportaciones correctas por mes de autorización. La cuota, la concurrencia y las versiones de una licencia comercial dependen de la licencia adquirida. Ni Free ni las licencias comerciales imponen límites de tamaño de archivo o de número de celdas. Usa la respuesta de la consulta para conocer el periodo actual y la cuota restante. La cuota mensual no usada no se acumula.

Las importaciones no requieren autorización de exportación ni consumen cuota de exportación. Las exportaciones de Office y PDF que usan la misma licencia comercial dentro de un despliegue comparten cuota. Consulta Importación y exportación de archivos de Office para los formatos de conversión de Exchange.

Cada conversión correcta consume una exportación. Devolver un Buffer cuenta como éxito. Un fallo posterior al escribir, subir o descargar el archivo no devuelve esa exportación; otra conversión correcta consume otra. Cuando el periodo actual no tiene cuota restante, se rechazan las nuevas exportaciones. Espera al siguiente periodo de autorización o usa una licencia válida con más cuota; una licencia comercial válida agotada no usa la cuota Free.

Gestionar errores

Identifica los errores por el code estructurado en lugar de analizar el texto de message. Tu interfaz puede asociar los códigos a mensajes localizados. Conserva la información de diagnóstico para el soporte técnico.

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) {    // Muestra el mensaje de error.code, p. ej. LICENSE_EXPORT_QUOTA_EXCEEDED cuando se agota la cuota    console.error(error.code)  } else {    throw error  }}

La tabla distingue las consultas de cuota (getExportQuota) de las exportaciones reales. Ambas API devuelven Promises; gestiona los fallos con await y try/catch.

Las aplicaciones pueden generar avisos de caducidad a partir de licenseStatus y expiresAt; el SDK no devuelve una lista de avisos aparte.

Tras un error de procesamiento del uso de la licencia, no deduzcas el cómputo solo a partir del error. Conserva el error completo y contacta con el soporte técnico.