# Listar documentos por estado

Fuente: /document-management/list-documents/

Este endpoint lista los documentos que creaste en una carpeta de trabajo. Con el filtro `sign_status` puedes traer solo los firmados, solo los pendientes o cualquier combinación de estados.

**Método:**  GET `https://api.digitafirma.com/v1/documents`

### Query Parameters

| Campo | Tipo | Requerido | Descripción |
| :- | :- | :- | :- |
| `company_id` | `string` | Sí | ID de la carpeta de trabajo (consulta [Listar carpetas de trabajo](/work-folders/work-folders-list)). |
| `searchName` | `string` | Sí | Texto que debe contener el nombre del archivo. Envíalo vacío (`searchName=`) para no filtrar por nombre. |
| `sign_status` | `integer` | No | Estado de firma del documento. Puedes enviar varios. Si lo omites, regresa todos los estados. |
| `page` | `integer` | No | Página a consultar. Empieza en `0`. |
| `size` | `integer` | No | Documentos por página. Por defecto `20`. |
| `sort` | `string` | No | Orden de los resultados, por ejemplo `createdAt,desc` para ver primero los más recientes. |

***

### Estados de firma (`sign_status`)

| Valor | Estado | Significa |
| :- | :- | :- |
| `1` | Sin firmar | Ningún firmante ha firmado todavía. |
| `2` | Firmado parcialmente | Al menos un firmante ya firmó, pero faltan otros. |
| `3` | Firmado | Todos los firmantes firmaron. |
| `4` | Rechazado | Un firmante rechazó el documento. |

Cada documento de la respuesta trae su estado en `attributes.sign_status`. El atributo `attributes.signed` es `true` solo cuando `sign_status` es `3`.

#### Filtros más comunes

| Quiero listar… | Parámetros |
| :- | :- |
| Firmados | `sign_status=3` |
| Pendientes de firma (sin firmar y parciales) | `sign_status=1&sign_status=2` |
| Sin ninguna firma | `sign_status=1` |
| Rechazados | `sign_status=4` |
| Todos | *(omite `sign_status`)* |

> **Varios estados a la vez**
>
> Para filtrar por varios estados repite el parámetro (`sign_status=1&sign_status=2`) o sepáralos con comas (`sign_status=1,2`). Las dos formas dan el mismo resultado.

***

### Qué incluye el listado

**Solo tus documentos**

Regresa los documentos que creó el usuario de la `X-Api-Key` en esa carpeta. Los que crearon otros miembros de la carpeta no aparecen.

**Sin archivados ni eliminados**

Los documentos archivados se consultan en [Listar documentos archivados](/document-management/list-archive-document). Los eliminados ya no aparecen en ningún listado.

**Documentos donde eres firmante**

Si otra cuenta te invitó a firmar, esos documentos se consultan en [Listar documentos invitados](/document-management/list-invited-documents).

**Paginado**

La respuesta trae una página a la vez. Revisa `meta` para saber cuántas páginas y documentos hay en total.

***

### Paginación

La información de paginación viene en `meta[0].page`:

| Campo | Descripción |
| :- | :- |
| `total` | Total de páginas. |
| `totalItems` | Total de documentos que cumplen el filtro. |
| `initialItem` | Posición del primer documento de la página, calculada como `page × 20`. |

> **initialItem asume páginas de 20**
>
> `initialItem` siempre se calcula con 20 documentos por página, aunque envíes otro `size`. Si cambias `size`, calcula la posición tú mismo con `page × size`.

Para recorrer todos los resultados, pide `page=0`, `page=1`… hasta llegar a `total - 1`.

***

### Ejemplo de integración

**Firmados**

```bash
curl --location 'https://api.digitafirma.com/v1/documents?company_id={company_id}&searchName=&sign_status=3&sort=createdAt,desc' \
--header 'X-Api-Key: {X-API-KEY}'
```

**Pendientes**

```bash
curl --location 'https://api.digitafirma.com/v1/documents?company_id={company_id}&searchName=&sign_status=1&sign_status=2&sort=createdAt,desc' \
--header 'X-Api-Key: {X-API-KEY}'
```

**Respuesta Exitosa (200 OK)**

Cada documento tiene la misma estructura que en [Mostrar un documento](/document-management/show-document). Aquí se muestran solo algunos atributos.

```json
{
  "data": [
    {
      "type": "documents",
      "id": "ac110005-9df4-1d1b-819d-f60440bc003c",
      "links": {
        "self": "/documents/ac110005-9df4-1d1b-819d-f60440bc003c"
      },
      "attributes": {
        "file_name": "contrato-servicios.pdf",
        "sign_status": 3,
        "signed": true,
        "owner": "Juan Pérez <juan.perez@ejemplo.com>",
        "isOwner": true,
        "signed_at": "2026-05-06T10:15:32.481920",
        "created_at": "2026-05-04T20:42:47.172839"
      },
      "relationships": {
        "signatories": {
          "data": [
            {
              "type": "signatures",
              "id": "ac110005-9df4-1d1b-819d-f60440c7003d",
              "attributes": {
                "name": "María López",
                "email": "maria.lopez@ejemplo.com",
                "sign_status": "SIGNED"
              }
            }
          ]
        }
      }
    }
  ],
  "meta": [
    {
      "page": {
        "total": 3,
        "initialItem": 0,
        "totalItems": 47
      }
    }
  ],
  "links": {
    "self": "/documents"
  }
}
```

**Error (400)**

```json
{
  "errors": [
    {
      "status": 400,
      "title": "Domain Error",
      "detail": "La compañia no pudo ser encontrada"
    }
  ]
}
```

***

### Errores comunes

| Código | Mensaje | Causa |
| :- | :- | :- |
| 400 | `La compañia no pudo ser encontrada` | El `company_id` no existe. |
| 400 | — | Falta `company_id` o `searchName` en la petición. |
| 401 | — | Falta la `X-Api-Key` o no es válida. |