Administrador de archivos

ResumenPuntos de terminación

Usa la herramienta de archivos de HubSpot para administrar y almacenar archivos en HubSpot. Los archivos alojados en HubSpot se pueden cargar y usar tanto en HubSpot como en contenido externo. También pueden adjuntarse a los registros con 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 servir y compartir a través de CMS Hub.

Puedes acceder a la herramienta archivos desde HubSpot o a través de la API de archivos. A continuación, aprende sobre los archivos API y cómo cargar y eliminar archivos. Para ver una lista completa de puntos e terminación de API de archivos, haz clic en la pestaña Puntos de terminación arriba.

Cargar un archivo

Los archivos se pueden cargar usando una solicitud multipart/form-data POST para files/v3/files con los siguientes campos. Si bien un ID de carpeta específico no es obligatorio en la carga, se recomienda cargar archivos en una carpeta y no en el directorio raíz. Los requisitos de carpeta en la carga están sujetos a cambios en el futuro. 

Use this table to describe parameters / fields
CampoDescription
file

El archivo para subir (requerido).

options

Un objeto JSON que controla la privacidad e indexabilidad del archivo y contiene dos campos: access, que es obligatorio, y ttl, que especifica un período de tiempo después del cual el archivo se eliminará automáticamente.

Si estás usando el campo ttl:

  • El plazo mínimo que se debe fijar es de 1 día.
  • El plazo máximo que se puede fijar es de 1 año.
  • Después del periodo establecido, el archivo se eliminará permanentemente. Después de la eliminación, el archivo no se puede recuperar ni restaurar.

folderId

El ID de la carpeta a la que se subirá el archivo. En tu solicitud, se debe proporcionar este campo o folderPath (pero no ambos).

folderPath

La ruta de la carpeta en la que se subirá el archivo. En tu solicitud, se debe proporcionar este campo o folderId (pero no ambos).

fileName

El nombre del archivo. Si no se especifica ningún nombre, se generará un nombre a partir del contenido del archivo.

charsetHunch

Codificación de conjunto de caracteres para el archivo cargado. Si no se proporciona, se obtendrá del archivo.

Por ejemplo, si quieres 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 de archivos en HubSpot: acceso privado

Los siguientes encabezados y el cuerpo de la solicitud deberían formar parte de tu solicitud:

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 parentFolderId del archivo subido, que puedes utilizar para recuperar 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 para subir. El proceso de importación aún no ha comenzado. 
  • PROCESSING: el archivo está en proceso de subir.
  • CANCELED: la subida se ha cancelado y el archivo no se subirá. Para importar el archivo a tu cuenta de HubSpot, tendrás que subirlo de nuevo.  
  • COMPLETE: el archivo se ha subido 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, realiza una solicitud GET a files/v3/files/{fileId}. Esto devolverá el archivo con detalles como nombre, alto y ancho, codificación, URL y más.

Por ejemplo, para recuperar los detalles de un archivo:  

Si un archivo está establecido como privado, la URL devuelta ocasionará 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 propiedad para devolver propiedades específicas como alto y ancho.

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 sea accesible.

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 no se elimina el 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 de 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. 

Use this table to describe parameters / fields
CampoRequeridoDescription
name
Yes

Nombre de la carpeta que deseas crear.

parentFolderId
No

Para crear la carpeta dentro de una carpeta existente, incluye este campo con el ID de la carpeta existente. parentFolderId y parentFolderPath no se pueden establecer al mismo tiempo.

parentFolderPath
No

Para crear la carpeta dentro de una carpeta existente, incluye este campo con la ruta de la carpeta existente. parentFolderId y parentFolderPath no se pueden establecer al mismo tiempo.
JSON 
//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, v3 tiene los siguientes cambios:

  • Todos los archivos cargados 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. 
  • Enumerar archivos no devolverá los archivos ocultos o eliminados. Sin embargo, se puede aplicar un rango mucho más amplio de filtros. Los archivos ocultos aún se pueden recuperar por ID, pero requieren un nuevo alcance: files_ui_hidden.read.
  • No se pueden cargar varios archivos con una sola solicitud. 
  • Las acciones de actualización de carpeta como mover y cambiar el nombre son ahora asíncronas. Cada solicitud devolverá un token que se puede usar para comprobar el estado de la edición de la carpeta.
  • Los puntos finales que crean o reemplazan archivos requieren que proporciones niveles de acceso para los archivos. Estos niveles de acceso son:
    • PUBLIC_INDEXABLE: el archivo es accesible públicamente por cualquiera que tenga la URL. Los motores de búsqueda pueden indexar el archivo.
    • PUBLIC_NOT_INDEXABLE: el archivo es accesible públicamente por cualquiera que tenga la URL. Las X-Robots-Tag: el encabezado noindex se enviará cada vez que se recupere el archivo, indicando a los motores de búsqueda que no indexen el archivo.
    • PRIVATE: el archivo no es accesible públicamente. Requiere una URL firmada para mostrar el contenido. Los motores de búsqueda no pueden indexar el archivo.
  • Los puntos finales que crean archivos permiten un nivel de detecciones duplicadas como parte de las opciones de carga del archivo. 
    • ENTIRE_PORTAL: busca un archivo duplicado en la cuenta.
    • EXACT_FOLDER: busca un archivo duplicado en la carpeta proporcionada.
    • NONE: no ejecutes ninguna validación duplicada.
    • REJECT: rechaza la carga si se encuentra un duplicado.
    • RETURN_EXISTING: si se encuentra un archivo duplicado, no cargues un nuevo archivo y, en su lugar, devuelve el duplicado encontrado.
    • La detección duplicada funciona en duplicateValidationScope, que afecta cómo buscamos un duplicado.
    • Esto también requiere una duplicateValidationStrategy, lo que determina qué sucede si se encuentra un duplicado.
¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.