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.

Endpoint

GET

https://app.firmeasy.legal/api/v1/folders

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.

Nombre	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.

Nombre	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.