Ir al contenido
FirmEasy
← Inicio

Listar Carpetas

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

Listar Carpetas

Sección titulada «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

Sección titulada «Autenticación»

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

Authorization: Bearer {access}

Headers

Sección titulada «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.

Authorization
string
Token de acceso obtenido en el login, con el prefijo 'Bearer'.
Límites:Obligatorio
Content-Type
string
Formato de datos enviados.
Límites:'application/json'

Parámetros de búsqueda

Sección titulada «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.

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

Ejemplo de respuesta

Sección titulada «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

Sección titulada «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.

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

Sección titulada «Paginación»

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

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

Sección titulada «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.