# Listar documentos

{% hint style="warning" %}
This endpoint is cached by default with a TTL of 60 seconds.
{% endhint %}

## Listar documentos

<mark style="color:blue;">`GET`</mark> `https://api.zapsign.com.br/api/v1/docs/?page=1`

Este endpoint permite listar todos los documentos de su cuenta. Por defecto, los resultados se devuelven de forma paginada.

***

#### Parámetros de URL (Query Params)

| **Parámetro**     | **Tipo**  | **Descripción**                                                                       |
| ----------------- | --------- | ------------------------------------------------------------------------------------- |
| `page`            | `integer` | Número de página para la navegación (ej: `?page=2`).                                  |
| `status`          | `string`  | Filtra por estado: `pending` (en curso), `signed` (firmado) o `refused` (rechazado).  |
| `folder_path`     | `string`  | Filtra documentos en una carpeta específica. Use `/` para la raíz.                    |
| `deleted`         | `boolean` | `true` para listar solo eliminados; `false` para activos.                             |
| `signer_email`    | `string`  | Filtra documentos que tengan un firmante con este correo electrónico.                 |
| `created_from`    | `string`  | Fecha inicial (formato `YYYY-MM-DD`).                                                 |
| `created_to`      | `string`  | Fecha final (formato `YYYY-MM-DD`).                                                   |
| `sort_order`      | `string`  | Orden por fecha de creación: `asc` (antiguos) o `desc` (nuevos).                      |
| `include_signers` | `boolean` | (Nuevo) Use `true`, `1` o `yes` para incluir el array de firmantes en cada documento. |

***

#### Headers (Encabezados)

| **Nombre**        | **Tipo** | **Descripción**                                                                                                               |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `Authorization`\* | `string` | <p>API token precedido por la palabra "Bearer".</p><p><br></p><p>Ej: <code>Bearer c7f35c84-7893-4087-b4fb-d1f06c23</code></p> |

***

#### Detalles del parámetro `include_signers`

Al activar este parámetro, la API devolverá el campo `signers` dentro de cada documento, con información detallada:

* Campos incluidos: Nombre, email, teléfono, modo de autenticación (`auth_mode`), flag de certificado digital, timestamps de interacción, URL de firma y orden de firma (si el orden está activo).
* Estado del Firmante: Expuesto a través de un enum estable:
  * `nao_abriu` (no abrió)
  * `abriu` (abrió)
  * `assinou` (firmó)
  * `recusou` (rechazó)
  * `expirou` (expiró)
  * `cancelado` (cancelado)

    *(Nota: Los estados a nivel de documento tienen precedencia sobre el estado individual cuando corresponda).*

***

#### Notas importantes

* Consistencia JSON: Los strings vacíos se normalizan a `null` en la respuesta de la API.
* Rendimiento Optimizado: El endpoint utiliza `prefetch_related` para evitar problemas de consultas N+1 al solicitar los firmantes, garantizando respuestas rápidas incluso en listados voluminosos.
* Enlaces Temporales: Los campos `original_file` y `signed_file` devuelven enlaces que expiran en 60 minutos.
* Caché: Existe un caché de 60 segundos para este endpoint. Si acaba de crear un documento, puede tardar hasta un minuto en aparecer en esta lista.

***

#### Ejemplos de Respuesta (JSON)

**Ejemplo con `include_signers = True`**

```json
{
    "count": 120,
    "next": "https://api.zapsign.com.br/api/v1/docs/?page=2",
    "previous": null,
    "results": [
        {
            "token": "4f9e-a1b2-c3d4",
            "name": "Contrato de Prestación de Servicios",
            "status": "pending",
            "original_file": "https://s3.amazonaws.com/...",
            "signed_file": null,
            "created_at": "2024-03-25T14:30:00Z",
            "folder_path": "/",
            "signers": [
                {
                    "name": "Juan Pérez",
                    "email": "juan@email.com",
                    "status": "abriu",
                    "auth_mode": "assinatura_tela",
                    "signing_url": "https://zapsign.com.br/sign/...",
                    "has_certificate": false,
                    "order": 1
                }
            ]
        }
    ]
}
```

{% hint style="info" %}
Consejo: En lugar de consultar los documentos varias veces al día, utilice nuestros Webhooks. Además de ahorrar capacidad computacional en nuestros servidores y los suyos, podrá dar feedback en tiempo real a su usuario.
{% endhint %}

{% hint style="warning" %}
Atención: Los enlaces devueltos en `original_file` y `signed_file` son temporales y duran 60 minutos. Si su sistema necesita guardar estos enlaces, se recomienda descargarlos en una CDN propia o consultar este endpoint siempre para asegurar que el usuario reciba un enlace válido.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zapsign.com.br/espanol/documentos/listar-documentos.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.