Listar documentos

GET {{base_url}}/v1/documents

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

Parámetro	Tipo	Descripción	Límites
`Authorization*`	string	Token de autenticación Bearer.	Obligatorio (Bearer <token>)

Parámetros de Consulta

Parámetro	Tipo	Descripción	Límites
`include[]`	string[]	Permite expandir relaciones del objeto. Usa children para poblar el array completo de anexos (extra_docs). Ej: ?include[]=children	Opcional

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": "[{{base_url}}/v1/files/...?intent=view&signature=]({{base_url}}/v1/files/...?intent=view&signature=)...",
    "signed_file": null,
    "original_download_file": "[{{base_url}}/v1/files/...?intent=download]({{base_url}}/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": "[{{base_url}}/v1/files/...?intent=view&signature=]({{base_url}}/v1/files/...?intent=view&signature=)...",
    "signed_file": "[{{base_url}}/v1/files/...?intent=view&signature=]({{base_url}}/v1/files/...?intent=view&signature=)...",
    "original_download_file": "[{{base_url}}/v1/files/...?intent=download]({{base_url}}/v1/files/...?intent=download)&...",
    "signed_download_file": "[{{base_url}}/v1/files/...?intent=download]({{base_url}}/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": "[{{base_url}}/v1/files/.../?intent=view]({{base_url}}/v1/files/.../?intent=view)&...",
        "signed_file": null,
        "original_download_file": "[{{base_url}}/v1/files/.../?intent=download]({{base_url}}/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"
  }
]

Nombre	Tipo	Descripción
`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

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.