> This page is for Plataforma, version Heredado. > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 experimental: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - Heredado: https://next.developer.frame.io/platform/v2/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://next.developer.frame.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server. # Leer el árbol de archivos ## Información general Independientemente de si el objetivo final es la publicación, la edición o el envío de activos a través de una fase del flujo de trabajo, muchas integraciones más profundas con Frame.io implicarán enumerar el contexto del usuario y, en última instancia, una vista de directorio. Esta es la jerarquía básica de recursos (o archivos) dentro de Frame.io: #### Cuenta > Equipo > Proyecto > Activos En este artículo se explica cómo interactuar con el árbol de archivos mediante llamadas API secuenciales. Una estrategia común para trabajar con archivos es acceder primero a un proyecto, enumerar las carpetas y luego trabajar con los activos y las pilas de versiones que contienen. ## Conceptos importantes ### Cada proyecto tiene un activo raíz único Las API RESTful normalmente describen recursos mediante el uso de identificadores únicos; el `root_asset_id` es el identificador único para el árbol de activos de su proyecto. Trátelo como una estructura especial que actúa como el nodo raíz de un proyecto: los activos restantes se apilan debajo de la raíz en un árbol descendente. root-asset-id En flujos de trabajo comunes, los usuarios de la API necesitan descender por el árbol para interactuar con activos más profundos en la jerarquía de archivos. ### Colaboradores y proyectos compartidos Un **usuario colaborador** es una función clave de usuario en Frame.io: estos usuarios tienen acceso al workspace de un proyecto, pero es posible que no pertenezcan a la cuenta general de ese proyecto. Dejando de lado los permisos distintos para [usuarios colaboradores e integrantes del equipo](https://support.frame.io/en/articles/6067-difference-between-team-members-vs-collaborators), la principal diferencia es que *el abono de un usuario colaborador es estrictamente a un proyecto y puede no tener relación con un equipo*. Esto crea una pequeña complicación para flujos de trabajo donde las listas de directorios son fundamentales. Aunque la jerarquía básica anterior (Cuenta > Equipo > Proyecto > Activos) debería funcionar para la mayoría de casos de uso, no describirá los proyectos en los que un usuario autenticado es un usuario colaborador, pero no un integrante del equipo. Para evitar este problema al enumerar directorios, puede hacer lo siguiente: * Recuperar los proyectos compartidos de un usuario, desempaquetar la jerarquía de equipo y cuenta, y unirlo todo * Recuperar los proyectos compartidos de un usuario y enumerarlos todos juntos como un contexto separado Ambos métodos funcionan bien; el último es un poco más fácil, pero el primero se acerca más a cómo la aplicación web de Frame.io presenta información similar. En cualquier caso, los métodos que se tratan en esta guía se aplican a ambos. ## Enumerar un directorio ### 1. Recuperar las cuentas del usuario `GET https://api.frame.io/v2/accounts` Realice la llamada anterior con un token de portador válido para obtener las cuentas de un usuario. Recibirá cada cuenta en la que el usuario tenga el estado de integrante del equipo, responsable de equipo o administrador. También puede recibir equipos para los que un usuario tenga derechos de facturación/administrador, pero no acceso al equipo, aunque esto es poco frecuente y se solucionará en el siguiente paso. La carga útil de la solicitud de cuentas es bastante detallada. A continuación, se muestra un resumen de los datos importantes que puede obtener de la respuesta: * `id` * `display_name` * `owner` (`email`, `name`) * (Opcionalmente) `image` *Nota:* La imagen de la cuenta que nuestra API devuelve será una clave S3 con firma previa, por lo que la URL devuelta caducará después de aproximadamente un día. Para solucionarlo, debe volver a recuperar la imagen cada vez que se cargue su servicio o, idealmente, almacenarla localmente. Tenga en cuenta que `id` y `owner.email` son los únicos campos obligatorios en una cuenta de usuario. Si está mostrando usuarios en otra aplicación, plantéese la posibilidad de escribir lógica condicional para presentar las cuentas de usuario. Nuestra recomendación es comprobarlo y, si no es *null*, mostrar la cuenta con el siguiente orden de preferencia: 1. "`display_name`" 2. Cuenta de "`owner.name`" 3. Cuenta de "`owner.email`" Una vez que su usuario elija una cuenta, lo más probable es que quiera presentar los equipos, lo que requiere una solicitud de API adicional. ### 2. Recuperar equipos dentro de la cuenta La solicitud `GET https://api.frame.io/v2/accounts/{{account_id}}/teams` para los equipos en Frame.io puede ser "pública" (es decir, detectable para cualquier integrante del equipo en la cuenta) o "privada" (detectable solo para miembros específicos del equipo). La API gestionará el contexto por usted, por lo que todo lo que necesita hacer es realizar una llamada válida especificando el `account_id` en la solicitud anterior. Aunque es poco probable que un usuario exista en muchas cuentas, los equipos son un recurso que puede crecer rápidamente. Los límites de frecuencia de la API de Frame.io son bastante altos, pero siempre es una buena práctica comprobar los encabezados de respuesta y, si es necesario, paginar. Puede encontrar más información sobre la paginación en [Paginación y errores](/docs/troubleshooting/troubleshooting). **De cada equipo, obtenga los siguientes atributos:** * `id` * `name` * (Opcionalmente) `team_image` Cuando se selecciona un equipo, lo ideal es mostrar sus proyectos constitutivos. **Nota**: Si lo desea, también puede realizar una solicitud `GET https://api.frame.io/v2/teams` para un usuario, y nuestra API devolverá cada equipo al que pertenece un usuario, independientemente del contexto de la cuenta. Aunque esto funciona técnicamente, corre el riesgo de perder su contexto a menos que siga otro paso para: 1. Reestablecer el contexto reflejando el nombre de la cuenta junto a cada equipo 2. Permitir que su usuario busque el texto de la lista Si está enumerando proyectos compartidos desde el nivel de cuenta hacia abajo, lo ideal es hacer una llamada adicional a `GET https://api.frame.io/v2/projects/shared`. Cada proyecto que se devuelve en la respuesta contendrá los siguientes atributos, que puede transferir al generar su directorio: * `id` (del proyecto mismo) * `team_id` * `team.account_id` También puede hacer una prestación para "Proyectos compartidos" simplemente añadiéndola como un "Equipo" en cualquier contexto de cuenta elegido. Si elige hacer eso, es útil para el usuario final si separa visualmente los proyectos compartidos de los proyectos con verdadero ámbito de equipo, ya que la lista única de proyectos compartidos puede incluir muchos contextos diferentes de cuenta y equipo verdaderos. ### 3. Recuperar los proyectos del equipo `GET https://api.frame.io/v2/teams/{{team_id}}/projects` Después, realice la llamada anterior y obtenga todos los proyectos que hay dentro del equipo. **Para cada proyecto, lo ideal es obtener:** * `id` * `name` * `root_asset_id` * (opcionalmente) `private`, en caso de que quiera diferenciar para el usuario en su IU Como se ha explicado al comienzo del artículo, `root_asset_id` es una parte importante de la arquitectura de recursos de Frame.io, en el sentido de que le permite desplazarse por el directorio de archivos y carpetas dentro de un proyecto. Repasemos rápidamente lo que hemos hecho hasta ahora: hemos establecido el contexto combinado de: | * Cuenta | * Equipo | * Proyectos del equipo (y root_asset_ids) | * Proyectos compartidos (y root_asset_ids) | Y eso es todo lo que necesitamos para crear o recuperar activos. ## Enumerar carpetas y activos ### 4. Generar la estructura inicial de carpetas Realice la solicitud `GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder`. Esto enumerará todas las carpetas que hay en un proyecto, comenzando desde el `root_asset_id`. Si no hay carpetas, obtendrá una lista vacía. Si desea incluir tanto archivos como carpetas (por ejemplo, si su siguiente paso sería realizar una solicitud `GET` a un activo desde Frame.io, simplemente omita el parámetro de cadena de consulta. Las otras dos opciones de filtro disponibles para el parámetro de tipo son file y version_stack. Los tres filtros son mutuamente excluyentes, y una llamada sin filtrar devolverá los tres tipos mezclados. ### 5. Navegar por el árbol de directorio **Para cada carpeta que se devuelve, necesitará capturar:** * `id` * `name` Como cada carpeta es un activo, su flujo de trabajo para navegar por una estructura de carpetas tendrá este aspecto: 1. `GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder` 1. Procesar los nombres de las carpetas en una lista 2. Cuando un usuario haga clic en una carpeta, pase el id de la carpeta a la siguiente consulta: 2. `GET https://api.frame.io/v2/assets/{{folder_id}}/children?type=folder` ### 6. Crear y cargar **En una carpeta:** Realice la solicitud `POST https://api.frame.io/v2/{{folder_id}}/children`. Una vez que tenga el id de la carpeta en la que le gustaría cargar, simplemente realice una solicitud `POST` a sus elementos secundarios, según la documentación del recurso y la guía. Esto creará un activo de marcador de posición, y (en función del método que elija), devolverá: * Un `uuid` destinado para casos de uso de seguimiento * Una lista de upload_urls que se puede usar para realizar una solicitud PUT de su archivo directamente en el almacenamiento de datos backend de Frame.io. **En una pila de versiones:** Las pilas de versiones presentan un flujo de trabajo similar, con un paso adicional cubierto en [esta guía](doc:managing-version-stacks), que se resume a continuación. Las claves son recordar que una pila de versiones es un contenedor que tiene un aspecto similar al de un activo, pero se comporta como una carpeta; luego, que tiene que cargar su activo primero y luego apilarlo en su pila de versiones como acciones separadas. Por lo tanto, **si quiere cargar un activo en una pila de versiones, necesitará:** * El `id` de la pila de versiones * El `parent_id` de la pila de versiones (por ejemplo, su carpeta contenedora o raíz del proyecto) Primero, realice la solicitud `POST https://api.frame.io/v2/assets/{{parent_id}}/children` para crear su activo nuevo. Capture el `id` nuevo en su respuesta. Ahora, puede usar el id de su activo nuevo y la solicitud `POST https://api.frame.io/v2/assets/{{version_stack_id}}/version`, con una carga útil del cuerpo de: ```json { "next_asset_id": "" } ```