Listar documentos

Este endpoint permite obtener una lista paginada de documentos, con posibilidad de aplicar filtros, ordenamientos y expansiones para obtener información relacionada como firmantes, tracking y usuario creador.

Endpoint

GET

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

Headers

Nombre	Tipo	Descripción	Límites
Authorization *	string	Token de acceso obtenido en el login, con el prefijo 'Bearer'.	Obligatorio
Content-Type	string	Especifica el tipo de contenido del cuerpo de la solicitud HTTP. Para las peticiones que incluyen datos JSON	'application/json'

Parámetros de búsqueda

Nombre	Tipo	Descripción	Límites
sort_order	string	Orden de resultados: 'asc' o 'desc'.	Opcional
sort_by	string	Campo por el cual ordenar, por ejemplo 'name' o 'created_at'.	Opcional
page	integer	Página actual del resultado.	Opcional
per_page	integer	Cantidad de resultados por página. Por defecto 25.	Opcional
name	string	Filtro por nombre del documento (búsqueda parcial).	Opcional
folder_id	string	Token de la carpeta para filtrar documentos dentro de ella.	Opcional
include[]	array	Permite incluir relaciones: 'user', 'signers', 'tracking', 'signers.tracking'.	Opcional

Ejemplo de respuesta

{
  "items": [
    {
      "external_id": null,
      "token": "a3d6e1c4-9f82-4b53-91c4-68f9b7a2e3d5",
      "name": "Acuerdo_Mantenimiento_2025.pdf",
      "folder": null,
      "status": "signed",
      "lang": "es",
      "size": "2859412",
      "original_file": "https://docs.empresaglobal.com/files/a3d6e1c4-9f82-4b53-91c4-68f9b7a2e3d5",
      "signed_file": "https://docs.empresaglobal.com/files/signed/a3d6e1c4-9f82-4b53-91c4-68f9b7a2e3d5",
      "signatures_made": 2,
      "signature_deadline": null,
      "created_by": { "email": "[email protected]" },
      "created_through": "web",
      "reminder_every_n_days": 0,
      "send_automatic_invitations": true,
      "send_signed_document_by_whatsapp": false,
      "is_rejection_allowed": false,
      "is_signature_order_active": false,
      "redirect_link": null,
      "observers": null,
      "metadata": null,
      "created_at": "2024-12-14T10:25:48.000000Z",
      "updated_at": "2024-12-14T10:27:03.000000Z"
    }
  ],
  "pagination": {
    "total_items": 27,
    "total_pages": 2,
    "current_page": 1,
    "per_page": 25
  }
}

Campos devueltos por documento

Nombre	Tipo	Descripción
external_id	string	ID externo asignado por el cliente.
token	string	Identificador único del documento.
name	string	Nombre del archivo.
folder	object	Carpeta asociada si aplica.
status	string	Estado del documento ('pending', 'signed', 'expired', etc).
lang	string	Idioma del documento.
size	string	Tamaño del archivo en bytes.
original_file	string	URL para descargar el archivo original.
signed_file	string	URL del archivo ya firmado.
signatures_made	integer	Número de firmas realizadas.
signature_deadline	datetime	Fecha límite de firma (UTC ISO 8601).
created_by.email	string	Email del usuario que creó el documento.
created_through	string	Origen de creación ('api' o 'web').
reminder_every_n_days	integer	Frecuencia para enviar recordatorios.
send_automatic_invitations	boolean	Si se envían invitaciones automáticas.
send_signed_document_by_whatsapp	boolean	Si se envía el documento firmado por WhatsApp.
is_rejection_allowed	boolean	Si el firmante puede rechazar el documento.
is_signature_order_active	boolean	Indica si la firma es secuencial.
redirect_link	string	URL de redirección tras firmar.
observers	array	Lista de emails de observadores.
metadata	object	Metadatos personalizados para webhooks.
created_at	datetime	Fecha de creación.
updated_at	datetime	Fecha de última actualización.

Paginación

La respuesta incluye un objeto pagination para manejar la navegación entre resultados:

"pagination": {
  "total_items": 27,
  "total_pages": 2,
  "current_page": 1,
  "per_page": 25,
  "next_page_url": "https://api.empresaglobal.com/v1/documents?page=2",
  "first_page_url": "https://api.empresaglobal.com/v1/documents?page=1",
  "last_page_url": "https://api.empresaglobal.com/v1/documents?page=2"
}

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.