Convierte documentos subidos a PDF y guárdalos en Box

Conclusiones clave

Restringe las subidas a los tipos de documento que la ruta de conversión elegida realmente admite.
Convierte el origen aceptado a PDF antes de exportarlo a una ruta de Box específica del caso o del proyecto.
Mantén el acceso a Box en credenciales de Template y deja la selección de carpetas bajo el control de la aplicación de confianza.

La incorporación de documentos suele comenzar con una mezcla de DOCX, PPTX, ODT y otros formatos de oficina, mientras que los revisores esperan un PDF estable. Enviar el original directamente a una carpeta de colaboración deja las reglas de conversión y los nombres inconsistentes. Un flujo de trabajo guardado hace que el derivado en PDF y su destino sean predecibles sin convertir a Box en el servicio de procesamiento de subidas.

Elige un contrato de recepción de documentos acotado

Una carpeta llena de «documentos» no es un solo formato técnico. Define los formatos de entrada, el límite de bytes, las expectativas de páginas y los requisitos de fidelidad antes de aceptar subidas. /document/convert puede crear PDF a partir de formatos de oficina, texto, HTML y presentaciones compatibles.

Mantén los PDF existentes fuera de esta rama de conversión, ya que /document/convert no es una herramienta genérica de PDF a cualquier cosa. Si el producto acepta tanto PDF como archivos de oficina convertibles, enrútalos deliberadamente: conserva los PDF aceptados y convierte solo los formatos que necesitan normalización.

Crea el Template de PDF a Box

El Template recibe un documento subido como :original, lo convierte a PDF y pasa solo ese PDF a /box/store. La ruta de destino incluye un identificador de caso o proyecto aprobado por la aplicación más valores únicos de la Assembly. Esto evita que dos usuarios que suban report.docx se sobrescriban entre sí.

Establece create_sharing_link en false. Un enlace de colaboración compartido es una decisión de autorización y retención, no un efecto secundario de la conversión. Si el producto lo necesita más adelante, créalo solo después de que la aplicación confirme el destino en Box, la audiencia prevista y la política de expiración o revocación.

Convertir un documento de oficina subido y exportar el PDF a Box

{
  "allow_steps_override": false,
  "auth": {
    "max_number_of_files": 1,
    "max_size": 104857600
  },
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "review_pdf": {
      "use": ":original",
      "robot": "/document/convert",
      "format": "pdf"
    },
    "box_export": {
      "use": "review_pdf",
      "robot": "/box/store",
      "credentials": "box-documents",
      "path": "cases/${fields.case_id}/${unique_prefix}/${file.url_name}",
      "create_sharing_link": false,
      "result": true
    }
  }
}

Controla las rutas, las credenciales y las identidades duraderas

Guarda el acceso a Box en credenciales de Template y haz referencia al nombre de la credencial desde el Template guardado. No permitas que un cliente no confiable elija una credencial, una carpeta arbitraria o una ruta de reemplazo. El servidor debería autorizar al usuario contra el registro del caso o proyecto y proporcionar un identificador acotado que el Template pueda incluir en su ruta.

Los nombres de carpeta son presentación, no identidad duradera. Mantén juntos el ID del documento de la aplicación, la versión de origen, el ID de la Assembly, la identidad del resultado en Box y la versión del flujo de trabajo. Esos campos sobreviven a un traslado posterior de carpeta y permiten a los operadores distinguir una reejecución de una versión nueva del documento.

Identidad de la aplicación

Los identificadores estables de documento, caso, inquilino y versión.

Identidad de procesamiento

La versión del flujo de trabajo y el ID de la Assembly que produjeron el PDF.

Identidad de almacenamiento

La identidad y ruta del archivo en Box devueltas por la exportación exitosa.

Verifica la conversión antes de marcar el documento como listo

Una Assembly en verde es necesaria, pero no suficiente, para documentos de alto riesgo. Haz que la aplicación inspeccione el tipo MIME y el número de páginas del PDF exportado, y luego usa datos de prueba representativos para revisar fuentes, tablas, saltos de página, encabezados, pies de página, enlaces y texto no latino. Una tarea exitosa de /document/convert no establece por sí sola que el resultado coincida con la aplicación de origen. Decide si una discrepancia bloquea el flujo de trabajo o envía el archivo a revisión manual.

Completa el registro de la aplicación solo después de que exista la exportación a Box y corresponda a la Assembly esperada. Procesa los webhooks de forma idempotente y concilia los registros activos con el Assembly Status cuando una notificación se retrase o se pierda.

Pon a prueba los fallos de almacenamiento y recuperación

Prueba credenciales revocadas o inválidas de la app de Box Server Authentication, una carpeta de destino faltante, permiso de escritura insuficiente, subidas con el mismo nombre, formatos de origen no admitidos, fallo de conversión y una conversión exitosa seguida de un fallo de exportación. El reintento seguro debería reutilizar el origen y el estado de la operación existentes en lugar de pedirle al usuario que vuelva a subir el archivo siempre que sea posible.

Define la retención de la subida original, el derivado en PDF y el registro de la aplicación por separado. Box puede ser la copia de colaboración duradera, pero la aplicación aún necesita suficiente estado de identidad y auditoría para explicar cómo se produjo el PDF y si sigue vigente.

Mantén explícitos los roles del origen y del PDF

Un PDF normalizado puede ser la copia de colaboración mientras el archivo de oficina editable sigue siendo la referencia. Alternativamente, un proceso de registros puede designar el PDF revisado como la versión fija. Documenta esa elección en la aplicación en lugar de permitir que el archivo que aparece en Box se convierta en la referencia por accidente.

Cuando se reemplaza el archivo de origen, crea una nueva versión de la aplicación y una nueva identidad de destino, o aplica un contrato de sobrescritura deliberado. Nunca asumas que una subida con el mismo nombre representa el mismo documento de negocio, y no elimines el archivo de origen anterior hasta que se hayan cumplido los requisitos de retención y reversión.

Detalles técnicos que conviene conocer

/document/convert puede convertir formatos de oficina y texto compatibles a PDF. PDF no es una entrada compatible, por lo que hay que enrutar los PDF existentes alrededor del Step de conversión.
/box/store acepta una ruta que contiene Assembly Variables y, cuando no se proporciona ninguna ruta, usa por defecto una ruta con prefijo único.
La opción de exportación de Box create_sharing_link tiene por defecto false. Habilitarla reemplaza la propiedad url del archivo de resultado por la URL de uso compartido.
Las credenciales de Template de Box usan Server Authentication con JWT. Los administradores de la aplicación deben mantener válidos esa autorización de la app y su material de claves.
Las credenciales de Template mantienen el acceso a Box fuera del JSON del Template y del paquete del navegador, aunque la aplicación debe seguir autorizando la carpeta de destino.
El PDF exportado es un nuevo derivado. Conservar o eliminar la subida original es una decisión de producto y gestión de registros independiente.

Un enfoque práctico

1
Define los formatos de oficina admitidos, el tamaño máximo, la política de carpeta de destino y la retención.
2
Crea credenciales de Template de Box con alcance limitado y guarda el Template bloqueado de tres Steps.
3
Sube documentos representativos y verifica el diseño de página, las fuentes, los nombres de archivo y la ubicación en Box.
4
Prueba PDF no admitidos, nombres duplicados, autorización revocada de la app de Box y fallos parciales de exportación.

Un flujo de trabajo multimedia de cuatro etapas

Cuándo resulta útil Transloadit

Usa este flujo de trabajo para la incorporación interactiva por usuario a una carpeta de colaboración de Box. Usa /upload/handle para la incorporación del usuario, /document/convert para la conversión compatible de oficina a PDF, y /box/store para la exportación duradera. Mantén el acceso a Box en credenciales de Template, usa una ruta de carpeta aprobada por la aplicación y deja desactivada la creación de enlaces para compartir a menos que el producto lo necesite explícitamente.

Límite de la arquitectura

Transloadit convierte y exporta el documento subido. La aplicación sigue siendo responsable del permiso del usuario, la identidad del caso o proyecto, la retención, la clasificación legal, la configuración de colaboración de Box y si un documento resultante puede compartirse.

Preguntas frecuentes

¿Puede este Template aceptar PDF como entrada?

/document/convert no acepta entrada en PDF. Enruta los PDF existentes evitando la conversión o usa un flujo de trabajo separado adecuado a la operación de PDF requerida.

¿Debería /box/store crear un enlace para compartir?

Por lo general, no durante la incorporación. Mantén create_sharing_link en false y convierte el uso compartido en una acción autorizada posterior, con una audiencia explícita y una política de revocación.

¿La conversión conserva todas las funciones del documento de oficina?

No. Verifica una selección representativa de fuentes, diseño, fórmulas, enlaces y funciones complejas específicas de la aplicación antes de confiar en el PDF como una representación de referencia.

¿Puede el navegador elegir la carpeta de Box?

El navegador puede enviar un identificador de aplicación acotado, pero un servidor de confianza debería autorizarlo, y el Template bloqueado debería controlar la ruta de destino real.

¿Qué debería almacenarse en la base de datos de la aplicación?

Conserva la identidad y versión del documento de origen, la versión del flujo de trabajo, el ID de la Assembly, la identidad del archivo en Box, la ruta de destino y el estado terminal del flujo de trabajo.