Ir al contenido
FirmEasy
← Inicio

Listar documentos

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

Listar documentos

Sección titulada «Listar documentos»

Devuelve un listado paginado con todos los documentos (sobres) creados por la organización. Por defecto, cada elemento incluye el contador de anexos; si necesitas recuperar el detalle completo de los anexos, puedes expandir la relación en la consulta.

Autenticación

Sección titulada «Autenticación»
Authorization
string
Token de autenticación Bearer.
Límites:Obligatorio (Bearer <token>)

Parámetros de Consulta

Sección titulada «Parámetros de Consulta»
include[]
string[]
Permite expandir relaciones del objeto. Usa children para poblar el array completo de anexos (extra_docs). Ej: ?include[]=children
Límites:Opcional

Respuesta Exitosa (200 OK)

Sección titulada «Respuesta Exitosa (200 OK)»

Devuelve una colección con los objetos de tipo Documento. En este ejemplo, el primer elemento muestra la estructura cuando no se solicita la expansión (valores de anexos en null) y el segundo muestra un elemento con la relación expandida.

[
  {
    "external_id": "ERP-123",
    "token": "abcdef01-...",
    "name": "CONTRATO DE PRESTACIÓN DE SERVICIOS N°9.pdf",
    "folder": { "token": "uuid", "name": "Carpeta" },
    "status": "pending",
    "lang": "es",
    "size": 245100,
    "original_file": "[https://api.firmeasy.legal/api/v1/files/...?intent=view&signature=](https://api.firmeasy.legal/api/v1/files/...?intent=view&signature=)...",
    "signed_file": null,
    "original_download_file": "[https://api.firmeasy.legal/api/v1/files/...?intent=download](https://api.firmeasy.legal/api/v1/files/...?intent=download)&...",
    "signed_download_file": null,
    "signatures_made": 0,
    "signature_deadline": "2026-12-31T23:59:59.000Z",
    "created_by": { "email": "[email protected]" },
    "extra_docs": null,
    "extra_docs_count": 2,
    "signers": [
      {
        "external_id": null,
        "token": "signer-api-id",
        "status": "pending",
        "name": "Jane Doe",
        "email": "[email protected]",
        "role": "signer",
        "link": "[https://app.firmeasy.legal/](https://app.firmeasy.legal/)...",
        "placements": [
          {
            "document_ref": "main",
            "type": "signature",
            "page_number": 1,
            "relative_position_left": 36.5,
            "relative_position_top": 39.25,
            "relative_size_width": 25,
            "relative_size_height": 8
          }
        ]
      }
    ],
    "created_through": "api",
    "metadata": { "order_id": "12345" },
    "created_at": "2026-06-23T10:00:00.000000Z",
    "updated_at": "2026-06-23T10:00:00.000000Z"
  },
  {
    "external_id": "ERP-124",
    "token": "789fgh02-...",
    "name": "ADENDA DE CONTRATO DE LOCACIÓN.pdf",
    "folder": null,
    "status": "signed",
    "lang": "es",
    "size": 124000,
    "original_file": "[https://api.firmeasy.legal/api/v1/files/...?intent=view&signature=](https://api.firmeasy.legal/api/v1/files/...?intent=view&signature=)...",
    "signed_file": "[https://api.firmeasy.legal/api/v1/files/...?intent=view&signature=](https://api.firmeasy.legal/api/v1/files/...?intent=view&signature=)...",
    "original_download_file": "[https://api.firmeasy.legal/api/v1/files/...?intent=download](https://api.firmeasy.legal/api/v1/files/...?intent=download)&...",
    "signed_download_file": "[https://api.firmeasy.legal/api/v1/files/...?intent=download](https://api.firmeasy.legal/api/v1/files/...?intent=download)&...",
    "signatures_made": 1,
    "signature_deadline": "2026-08-15T18:00:00.000Z",
    "created_by": { "email": "[email protected]" },
    "extra_docs": [
      {
        "token": "anexo-token-99",
        "name": "Anexo de Especificaciones Técnicas.pdf",
        "original_file": "[https://api.firmeasy.legal/api/v1/files/.../?intent=view](https://api.firmeasy.legal/api/v1/files/.../?intent=view)&...",
        "signed_file": null,
        "original_download_file": "[https://api.firmeasy.legal/api/v1/files/.../?intent=download](https://api.firmeasy.legal/api/v1/files/.../?intent=download)&...",
        "signed_download_file": null,
        "uploaded_by": { "email": "[email protected]" }
      }
    ],
    "extra_docs_count": 1,
    "signers": [
      {
        "external_id": null,
        "token": "signer-api-2",
        "status": "signed",
        "name": "James Smith",
        "email": "[email protected]",
        "role": "signer",
        "link": "[https://app.firmeasy.legal/](https://app.firmeasy.legal/)...",
        "placements": [
          {
            "document_ref": "main",
            "type": "signature",
            "page_number": 2,
            "relative_position_left": 10.0,
            "relative_position_top": 45.0,
            "relative_size_width": 20,
            "relative_size_height": 10
          }
        ]
      }
    ],
    "created_through": "api",
    "metadata": {},
    "created_at": "2026-06-24T08:30:00.000000Z",
    "updated_at": "2026-06-24T09:15:00.000000Z"
  }
]
external_id
string
Tu id externo (pass-through).
token
string (UUID)
Identificador del documento (úsalo en los demás endpoints).
name
string
Nombre del sobre (se normaliza a MAYÚSCULAS + .pdf).
folder
object
Carpeta destino conteniendo token y name.
status
string
Estado del documento: pending · signed · rejected.
lang
string
Idioma de la interfaz: es · en · pt.
size
integer
Tamaño del archivo en bytes.
original_file
string (URL)
URL de visualización temporal del archivo original (expira a los 60 min).
signed_file
string (URL)
URL de visualización temporal del archivo firmado (null hasta que haya >=1 firma, expira a los 60 min).
original_download_file
string (URL)
URL de descarga temporal del archivo original con nombre de archivo (expira a los 60 min).
signed_download_file
string (URL)
URL de descarga temporal del archivo firmado (expira a los 60 min).
signatures_made
integer
Nº de firmas aplicadas.
signature_deadline
string (ISO8601)
Fecha límite de firma en formato Y-m-d\TH:i:s.v\Z.
created_by
object
Creador del documento conteniendo el email.
extra_docs
array
Array de anexos (solo si el sobre tiene). Siempre presente en create y webhooks o expandido vía include.
extra_docs_count
integer
Cantidad de anexos. Siempre presente en el listado; señal barata sin traer el array.
signers
array
Colección de firmantes del sobre con sus respectivos flujos y placements.
tracking
array
Eventos de auditoría y seguimiento del documento.
created_through
string
Canal de creación: api · web.
reminder_every_n_days
integer
Frecuencia de recordatorios automáticos (0-30 días).
send_automatic_invitations
boolean
Indica si se envían invitaciones automáticas al crear.
send_signed_document_by_whatsapp
boolean
Indica si se envía el documento firmado por WhatsApp.
is_rejection_allowed
boolean
Permitir rechazo del documento por parte de los firmantes.
is_signature_order_active
boolean
Indica si se respeta estrictamente el orden de firma configurado.
redirect_link
string
Redirección post-firma.
observers
array
Emails de observadores (solo lectura).
metadata
object
Pass-through de datos libres en formato clave-valor.
created_at
string (ISO8601)
Fecha de creación del registro.
updated_at
string (ISO8601)
Fecha de la última actualización del registro.

Respuestas de Error Comunes

Sección titulada «Respuestas de Error Comunes»
Código Estado Descripción
401 Unauthorized El token de autenticación es inválido, expiró o no fue enviado.
422 Unprocessable Entity Los parámetros de ordenamiento, filtros o relaciones solicitadas en include no son válidos.