Archivos adjuntos

El servicio de archivos sube capturas, registros o documentos para adjuntarlos después a un ticket de soporte o a uno de sus mensajes. Los archivos se guardan en el almacenamiento de archivos de tu organización, asociados a tu aplicación externa. Funciona con la clave de tu aplicación externa, siempre desde tu servidor.

Antes de empezar

Antes que el scope se comprueba el plan: sin el aplicativo Gestor de archivos, la respuesta es un 403 MODULE_NOT_ENABLED.

Subir un archivo

Qué puedes pasar como archivo depende del lenguaje:

• JavaScript: un File (en el navegador o en Node.js 20 o superior) o un Blob. Si es un Blob sin nombre, el SDK usa el de name o, si no lo das, file.
• Python: una ruta (str o Path), que el SDK abre y cierra por ti, o un objeto de archivo binario (IO[bytes], por ejemplo BytesIO).

Opciones comunes: name (nombre que se guardará, 255 caracteres como máximo), metadata (datos libres) y una función de progreso, onProgress (on_progress), que recibe el porcentaje de 0 a 100.

import { readFile } from 'node:fs/promises';
 
const blob = new Blob([await readFile('./registro-errores.log')], { type: 'text/plain' });
 
const uploaded = await sdk.files.upload(blob, {
  name: 'errores-produccion.log',
  metadata: { origen: 'sistema-pagos' },
  onProgress: (percent) => console.log(`Subida: ${percent}%`),
});
 
console.log(uploaded.id); // úsalo en attachmentIds

La respuesta trae id, originalName (original_name), mimeType (mime_type), size en bytes, downloadUrl (download_url) y createdAt (created_at). Pasa el id en attachmentIds al abrir un ticket o al añadir un mensaje.

Descargar y consultar la cuota

getUrl devuelve directamente la dirección temporal de descarga, como texto. getQuota devuelve el espacio usado y el total (usedBytes y maxBytes), el tamaño máximo de cada archivo (maxFileSizeBytes) y el porcentaje de uso (usagePercent).

const url = await sdk.files.getUrl(uploaded.id);
 
const quota = await sdk.files.getQuota();
console.log(`Uso: ${quota.usagePercent}%`);
console.log(`Máximo por archivo: ${(quota.maxFileSizeBytes / 1024 / 1024).toFixed(1)} MB`);

El tamaño máximo por archivo y el espacio total son los de tu aplicación externa. Un archivo que los supera se rechaza con un error de validación que dice cuál es el máximo permitido.

Siguiente paso

• Tickets de soporteAdjunta los archivos al abrir un ticket o al responder.
• Límites y validacionesQué comprueba el SDK antes de subir y qué rechaza el servidor.