> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar Documentos

> Liste os documentos enviados para análise, com filtros e paginação

## Query Params

<ParamField query="cpf" type="string">
  CPF do titular, com ou sem máscara.

  **Exemplo**: `12345678909`
</ParamField>

<ParamField query="name" type="string">
  Nome do titular. A busca é parcial e não diferencia maiúsculas de minúsculas.

  **Exemplo**: `JOAO`
</ParamField>

<ParamField query="workflowPresetAlias" type="string">
  Alias do preset de workflow, em correspondência exata.

  **Exemplo**: `documentoscopia_auto_base_face_15min`
</ParamField>

<ParamField query="status" type="string">
  Status atual do documento. Valores possíveis: `PENDING`, `MERGING`, `UPLOADING`, `SENDING`, `SENT`, `PROCESSING`, `COMPLETED`, `ERROR`, `FAILED` e `TIMEOUT`.

  **Exemplo**: `COMPLETED`
</ParamField>

<ParamField query="consolidatedStatus" type="string">
  Status consolidado do documento. Valores possíveis: `processing`, `error`, `approved`, `rejected` e `pending`.

  **Exemplo**: `approved`
</ParamField>

<ParamField query="createdFrom" type="string">
  Início do intervalo de criação, em ISO 8601.

  **Exemplo**: `2026-01-01T00:00:00.000Z`
</ParamField>

<ParamField query="createdTo" type="string">
  Fim do intervalo de criação, em ISO 8601.

  **Exemplo**: `2026-12-31T23:59:59.999Z`
</ParamField>

<ParamField query="sortBy" type="string" default="createdAt">
  Campo usado na ordenação. Valores possíveis: `createdAt`, `updatedAt`, `sentAt`, `finishedAt`, `status`, `cpf`, `name` e `workflowPresetAlias`.

  **Exemplo**: `createdAt`
</ParamField>

<ParamField query="sortOrder" type="string" default="desc">
  Direção da ordenação: `asc` ou `desc`.

  **Exemplo**: `desc`
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Quantidade máxima de itens por página, de 1 a 100.

  **Exemplo**: `20`
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Número de itens a pular na paginação.

  **Exemplo**: `0`
</ParamField>

## Response

<ResponseField name="items" type="array">
  Documentos encontrados. Cada item segue a mesma estrutura de [Consultar Documento](/plataforma/documentoscopia/api/get-document-by-id).
</ResponseField>

<ResponseField name="pagination.total" type="integer">
  Total de documentos que atendem aos filtros.

  **Exemplo**: `1`
</ResponseField>

<ResponseField name="pagination.limit" type="integer">
  Quantidade máxima de itens por página aplicada.

  **Exemplo**: `20`
</ResponseField>

<ResponseField name="pagination.offset" type="integer">
  Número de itens ignorados na paginação.

  **Exemplo**: `0`
</ResponseField>

<ResponseExample>
  ```json 200 theme={"theme":"catppuccin-latte"}
  {
    "items": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "organizationId": "123e4567-e89b-12d3-a456-426614174001",
        "projectId": "123e4567-e89b-12d3-a456-426614174002",
        "productId": "123e4567-e89b-12d3-a456-426614174003",
        "cpf": "12345678909",
        "status": "COMPLETED",
        "type": "docs",
        "createdAt": "2026-06-01T12:00:00.000Z",
        "updatedAt": "2026-06-01T12:05:00.000Z",
        "sentAt": "2026-06-01T12:00:01.000Z",
        "sentToBackofficeAt": "2026-06-01T12:00:02.000Z",
        "finishedAt": "2026-06-01T12:05:00.000Z",
        "errorMessage": null,
        "errorCode": null,
        "backofficeBatchId": "229462",
        "requestId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
        "name": "JOAO DA SILVA",
        "workflowPresetAlias": "documentoscopia_auto_base_face_15min",
        "result": {
          "id": "223e4567-e89b-12d3-a456-426614174001",
          "documentId": "123e4567-e89b-12d3-a456-426614174000",
          "status": "APPROVED",
          "confidenceScore": 98.5,
          "raw_response": {},
          "processedBy": "backoffice",
          "createdAt": "2026-06-01T12:05:00.000Z"
        }
      }
    ],
    "pagination": {
      "total": 1,
      "limit": 20,
      "offset": 0
    }
  }
  ```

  ```json 500 theme={"theme":"catppuccin-latte"}
  {
    "error": "INTERNAL_ERROR",
    "message": "Failed to list documents",
    "requestId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
    "timestamp": "2026-06-01T12:00:00.000Z"
  }
  ```
</ResponseExample>