Última modificación: 22 de agosto de 2025
Utiliza el administrador de archivos para gestionar y almacenar tus archivos en HubSpot. Los archivos alojados en el administrador pueden subirse y usarse tanto en HubSpot como en el contenido externo. Además, pueden adjuntarse a los registros mediante la API de interacciones. Si tu empresa está creando su sitio web usando CMS Hub, puedes usar la API de archivos para subir y almacenar recursos en HubSpot. Estos archivos se pueden distribuir y compartir a través de CMS Hub. Puedes acceder a la herramienta de archivos desde HubSpot o a través de la API de archivos. A continuación, aprende sobre la API de archivos y cómo subir y eliminar archivos. Para obtener una lista completa de endpoints de la API de archivos, consulta esta documentación de referencia.

​
Subir un archivo

Los archivos se pueden subir usando una solicitud de datos de formulario multiparte (multipart/form-data, en inglés) POST a files/v3/files con los siguientes campos. Si bien no es obligatorio incluir un ID de folder específico al subir archivos, se recomienda hacerlo dentro de una carpeta en lugar de subirlos directamente al directorio principal. Los requisitos de las carpetas para subir archivos están sujetos a cambios en el futuro.
CampoDescripción
fileEl archivo que se va a subir (requerido).
optionsUn objeto JSON que define la privacidad e indexabilidad del archivo, y está compuesto por dos campos: access, que es necesario, y ttl, que establece un período de tiempo después del cual el archivo se eliminará automáticamente. Si utilizas el campo ttl:
  • el plazo mínimo que se debe usar es de 1 día.
  • El plazo máximo que se puede usar es de 1 año.
  • Después del período establecido, el archivo se eliminará de forma permanente. Después de eliminado, el archivo no se puede recuperar ni restaurar.

folderIdEl ID de la carpeta a la que se subirá el archivo. En tu solicitud, se debe proporcionar este campo o folderPath (pero no ambos).
folderPathLa ruta de la carpeta en la que se subirá el archivo. En tu solicitud, se debe proporcionar este campo o folderId (pero no ambos).
fileNameEl nombre del archivo. Si no se especifica, se generará un nombre a partir del contenido del archivo.
charsetHunchCodificación del conjunto de caracteres para el archivo subido. Si no se proporciona, se obtendrá del archivo.
A manera de ejemplo, si quisieras subir un archivo con los siguientes criterios a tu cuenta de HubSpot:
  • Nombre del archivo: cat.png
  • Carpeta de destino en el administrador de archivos de HubSpot: /library/cat_archive
  • Accesibilidad del archivos en HubSpot: acceso privado
Los siguientes encabezados y el cuerpo de la solicitud deben incluirse: 
curl --request POST \
  --url 'https://api.hubapi.com/files/v3/files?=' \
  --header 'Authorization: Bearer pat-na1-00000000-0000-0000-0000-000000000000' \
  --header 'Content-type: multipart/form-data' \
  --form file=@/Users/person/Downloads/cat.png \
  --form 'options={"access": "PRIVATE"}' \
  --form folderPath=/library/cat_archive
La respuesta resultante incluirá el id y el parentFolderId del archivo subido, que puedes utilizar para obtener el archivo a través de una solicitud GET. 
// 201 Response from successful file upload
{
  "id": "122692044085",
  "createdAt": "2023-06-28T17:56:45.393Z",
  "updatedAt": "2023-06-28T17:56:45.393Z",
  "archived": false,
  "parentFolderId": "122692510820",
  "name": "cat",
  "path": "/library/cat_archive/cat.png",
  "size": 24574,
  "height": 219,
  "width": 225,
  "encoding": "png",
  "type": "IMG",
  "extension": "png",
  "defaultHostingUrl": "https://12345.fs1.hubspotusercontent-na1.net/hubfs/12345/library/cat_archive/cat.png",
  "url": "https://12345.fs1.hubspotusercontent-na1.net/hubfs/12345/library/cat_archive/cat.png",
  "isUsableInContent": true,
  "access": "PRIVATE"
}

​
Comprobar el estado de subida de un archivo

Si vas a importar un archivo desde una URL a tu administrador de archivos mediante una solicitud POST a files/v3/files/import-from-url/async, puedes revisar el estado de subida del archivo. Para hacerlo, usa una solicitud GET a files/v3/files/import-from-url/async/tasks/{taskId}/status. Después de hacer esta solicitud, recibirás una de las siguientes respuestas:
  • PENDING: el archivo está en la cola de espera para subirse. El proceso de importación aún no ha comenzado.
  • PROCESSING: el archivo está en proceso de subirse.
  • CANCELED: la subida del archivo se ha cancelado y no se completará. Para importar el archivo a tu cuenta de HubSpot, tendrás que subirlo de nuevo.
  • COMPLETE: el archivo se subió correctamente en la herramienta de archivos. El archivo subido aparecerá en tu herramienta de archivos.

​
Ver los detalles del archivo

Para revisar los detalles de un archivo que se ha subido en la herramienta de archivos, haz una solicitud GET a files/v3/files/{fileId}. Esto devolverá el archivo con detalles como el nombre, el alto y el ancho, la codificación, el URL y mucho más. Por ejemplo, para obtener los detalles de un archivo: Si un archivo está privado, la URL devuelta generará un error 404. Para obtener una URL visible del archivo, puedes hacer una solicitud GET a /files/v3/files/{fileId}/signed-url. Al realizar esta solicitud, puedes incluir parámetros de property para obtener información de propiedades específicas como altura y anchura.

​
Eliminar un archivo

Para eliminar un archivo, haz una solicitud DELETE a files/v3/files/{fileId}. Esto marcará el archivo como eliminado y hará que el contenido del archivo no esté disponible. Para eliminar permanentemente un archivo, haz una solicitud DELETE a files/v3/files/{fileId}/gdpr-delete. Esto eliminará permanentemente el contenido y los metadatos del archivo en 7 días. Si un archivo no se elimina conforme al RGPD, su contenido permanecerá en los servidores de HubSpot en un estado privado donde nadie puede acceder a él. Para garantizar que el contenido del archivo se elimine completamente, usa la funcionalidad de eliminación conforme al RGPD.

​
Crear una carpeta

Para crear una carpeta, haz una solicitud POST a files/v3/folders. Al realizar la solicitud, puedes incluir los siguientes campos.
CampoObligatorioDescripción
nameSíNombre de la carpeta que quieres crear.
parentFolderIdNoPara crear la carpeta dentro de una carpeta existente, incluye este campo con el ID de la carpeta existente. Los campos parentFolderId y parentFolderPath no se pueden definir al mismo tiempo.
parentFolderPathNoPara crear la carpeta dentro de una carpeta existente, incluye este campo con la ruta de la carpeta existente. Los campos parentFolderId y parentFolderPath no se pueden definir al mismo tiempo.
//Example request body of POST request to /files/v3/folders
{
  "name": "myNewFolder",
  "parentFolderId": 12345
}

​
Cambios en la v3

Si usas la versión anterior de esta API, la versión 3 tiene los siguientes cambios:
  • Todos los archivos subidos a través de la API serán visibles en el panel de archivos y el selector de archivos. No se pueden crear archivos ocultos. Sin embargo, se pueden crear archivos privados y archivos no indexables.
  • Los listados de archivos no devolverán los archivos ocultos o eliminados. Sin embargo, se puede aplicar un rango mucho más amplio de filtros. Los archivos ocultos se pueden obtener por el ID, pero requieren un nuevo permiso: files_ui_hidden.read.
  • No se pueden subir varios archivos en una sola solicitud.
  • Las acciones de actualización de carpetas, como mover y cambiar el nombre, ahora son asincrónicas. Cada solicitud devolverá un token que se puede usar para comprobar el estado de la edición de la carpeta.
  • Los endpoints que crean o reemplazan archivos equieren que establezcas los niveles de acceso para los archivos. Estos niveles de acceso son:
    • PUBLIC_INDEXABLE: el archivo se puede acceder públicamente por cualquiera que tenga la URL. Los motores de búsqueda pueden indexar el archivo.
    • PUBLIC_NOT_INDEXABLE: el archivo se puede acceder públicamente por cualquiera que tenga la URL. La etiqueta X-Robots: es el encabezado noindex que se enviará cada vez que se obtenga el archivo, indicando a los motores de búsqueda que no lo indexen.
    • PRIVATE: el archivo no se puede acceder públicamente. Requiere una URL firmada para mostrar el contenido. Los motores de búsqueda no pueden indexar el archivo.
  • Los endpoints que crean archivos permiten un nivel de detección de duplicados como parte de las opciones de subida del archivo.
    • ENTIRE_PORTAL: busca un archivo duplicado en la cuenta.
    • EXACT_FOLDER: busca un archivo duplicado en la carpeta proporcionada.
    • NONE: no ejecuta ninguna validación de duplicados.
    • REJECT: rechaza la subida del archivo si se encuentra un duplicado.
    • RETURN_EXISTING: si se encuentra un archivo duplicado, no carga un nuevo archivo. En su lugar, devuelve el duplicado encontrado.
    • La detección de duplicados funciona en duplicateValidationScope, que modifica cómo buscamos un duplicado.
    • También requiere una duplicateValidationStrategy, que determina lo que sucede si se encuentra un duplicado.