Listar Carpetas

GET {{base_url}}/v1/folders

Listar Carpetas

Este endpoint permite obtener un listado completo de las carpetas registradas en la cuenta, permitiendo aplicar filtros, paginación y ordenamiento según necesidad.

Autenticación

Se requiere enviar el token de autenticación obtenido previamente:

Authorization: Bearer {{access}}

Headers

Para autorizar el acceso a la API es necesario incluir el token de autenticación en el encabezado Authorization, utilizando el esquema Bearer. Además, el encabezado Content-Type debe especificar que el cuerpo de la solicitud (si lo hubiera) se envía en formato JSON.

Parámetro	Tipo	Descripción	Límites
`Authorization*`	string	Token de acceso obtenido en el login, con el prefijo 'Bearer'.	Obligatorio
`Content-Type`	string	Formato de datos enviados.	'application/json'

Parámetros de búsqueda

Estos parámetros permiten personalizar los resultados de la búsqueda de carpetas. Es posible filtrar por nombre, estado, jerarquía, fechas de creación, e incluir datos adicionales como las subcarpetas o la carpeta padre. Todos los parámetros son opcionales y pueden combinarse según necesidad.

Parámetro	Tipo	Descripción	Límites
`external_id`	string	Filtrar carpetas por su identificador externo asignado por el cliente.	Opcional
`parent_token`	string	Filtrar carpetas hijas de una carpeta padre específica.	Opcional
`name`	string	Filtrar carpetas por nombre (búsqueda parcial).	Opcional
`active`	boolean	Filtra carpetas activas (true) o eliminadas (false).	Opcional
`sort_by`	string	Campo por el cual ordenar (por defecto created_at).	Opcional
`sort_order`	string	Orden de los resultados: asc o desc.	Opcional
`page`	integer	Página actual de resultados (paginación).	Opcional
`per_page`	integer	Cantidad de resultados por página (por defecto 25).	Opcional

Ejemplo de respuesta

{
  "items": [
    {
      "external_id": "d4b7c8f1-27e4-4f92-b35a-5a3b81e0cf98",
      "token": "6a42e1b0-3f7c-45d2-8db4-12a7f3b52a61",
      "name": "Contrato Horizonte Azul",
      "description": "Acuerdo de colaboración para el suministro y soporte de infraestructura tecnológica",
      "document_count": 3,
      "signed_documents_count": 1,
      "in_progress_documents_count": 1,
      "not_started_documents_count": 1,
      "created_at": "2024-08-21T09:15:47.000000Z",
      "updated_at": "2024-09-05T16:42:30.000000Z",
      "deleted": false,
      "children": [],
      "parent": null
    }
  ],
  "pagination": {
    "total_items": 5,
    "total_pages": 1,
    "current_page": 1,
    "per_page": 25,
    "first_page_url": "https://app.ejemplo.com/api/v1/folders?page=1",
    "last_page_url": "https://app.ejemplo.com/api/v1/folders?page=1"
  }
}

Campos devueltos por carpeta

Cada elemento del listado de carpetas incluye el detalle completo de la carpeta, con los siguientes campos disponibles en la respuesta. Estos datos permiten identificar la carpeta, conocer su estado, su jerarquía (si corresponde), y la cantidad de documentos que contiene.

Nombre	Tipo	Descripción
`external_id`	string	ID externo asignado por el cliente.
`token`	string	Token único interno que es asignado por Firmeasy.
`name`	string	Nombre de la carpeta.
`description`	string	Descripción de la carpeta.
`document_count`	integer	Cantidad total de documentos.
`signed_documents_count`	integer	Documentos firmados.
`in_progress_documents_count`	integer	Documentos en progreso.
`not_started_documents_count`	integer	Documentos aún no iniciados.
`created_at`	datetime	Fecha de creación.
`updated_at`	datetime	Fecha de última modificación.
`deleted`	boolean	Indica si está eliminada lógicamente.
`children`	array	Lista de subcarpetas.
`parent`	object/null	Carpeta padre (si existe).

Paginación

La respuesta incluye siempre un bloque de paginación que permite conocer el estado completo de la consulta actual:

Nombre	Tipo	Descripción
`total_items`	integer	Cantidad total de carpetas que cumplen los filtros aplicados.
`total_pages`	integer	Cantidad total de páginas disponibles con la configuración de `per_page` actual.
`current_page`	integer	Número de la página actual.
`per_page`	integer	Cantidad de registros retornados por página en esta consulta.
`first_page_url`	string	URL completa de la primera página de resultados.
`last_page_url`	string	URL completa de la última página de resultados.

Errores posibles

Código	Descripción
400	Request inválido (parámetros incorrectos o faltantes).
401	No autorizado (token inválido o ausente).
500	Error interno inesperado.