> ## 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 envelopes

> Lista todos os envelopes do seu projeto com filtros e paginação.

Lista envelopes com suporte a filtros (estado, CPF de signatário, código externo) e paginação.

## Parâmetros de query

<ParamField query="state" type="enum">
  Filtrar por estado: `CREATED`, `AWAITING_SIGNATURE`, `SIGNING_IN_PROGRESS`, `FINISHED`, `CANCELLED`, `EXPIRED`, `REFUSED`.
</ParamField>

<ParamField query="externalCode" type="string">
  Filtrar por código externo do seu sistema.
</ParamField>

<ParamField query="signerCpf" type="string">
  Filtrar por CPF de um signatário (formato sem dígitos, ex: `"12345678901"`).
</ParamField>

<ParamField query="page" type="integer">
  Número da página (começa em 1). Padrão: 1.
</ParamField>

<ParamField query="perPage" type="integer">
  Itens por página. Padrão: 10. Máximo: 100.
</ParamField>

## Respostas

<ResponseField name="data" type="array">
  Lista de envelopes.

  <Expandable title="Propriedades de data[]">
    <ResponseField name="uuid" type="string">
      UUID do envelope.
    </ResponseField>

    <ResponseField name="externalCode" type="string">
      Código externo do seu sistema (se fornecido).
    </ResponseField>

    <ResponseField name="title" type="string">
      Título do envelope.
    </ResponseField>

    <ResponseField name="state" type="string">
      Estado atual: `CREATED`, `AWAITING_SIGNATURE`, `SIGNING_IN_PROGRESS`, `FINISHED`, `CANCELLED`, `EXPIRED`, `REFUSED`.
    </ResponseField>

    <ResponseField name="dueDate" type="string">
      Data limite de assinatura (ISO 8601).
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Timestamp de criação (ISO 8601).
    </ResponseField>

    <ResponseField name="finishedAt" type="string">
      Timestamp de finalização (ISO 8601), presente apenas se `state` for `FINISHED`.
    </ResponseField>

    <ResponseField name="refusedAt" type="string">
      Timestamp de recusa (ISO 8601), presente apenas se `state` for `REFUSED`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Total de envelopes que correspondem ao filtro.
</ResponseField>

<ResponseField name="page" type="integer">
  Página atual.
</ResponseField>

<ResponseField name="perPage" type="integer">
  Itens por página.
</ResponseField>

## Erros

Veja [Autenticação e erros](/plataforma/assinatura-digital/api/erros-e-autenticacao) para detalhes.

* **400**: Parâmetros de query inválidos (ex: `state` com valor desconhecido).
* **401**: API key/Bearer token inválido.

<ResponseExample>
  ```json theme={"theme":"catppuccin-latte"}
  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "data": [
      {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "externalCode": "CONT-2025-001",
        "title": "Contrato de Serviços",
        "state": "FINISHED",
        "dueDate": "2025-12-31T23:59:59Z",
        "createdAt": "2025-07-27T10:30:00.000Z",
        "finishedAt": "2025-07-27T15:45:30.000Z"
      },
      {
        "uuid": "660e8400-e29b-41d4-a716-446655440001",
        "externalCode": "CONT-2025-002",
        "title": "Contrato de Parceria",
        "state": "AWAITING_SIGNATURE",
        "dueDate": "2025-08-15T23:59:59Z",
        "createdAt": "2025-07-27T11:00:00.000Z"
      }
    ],
    "total": 2,
    "page": 1,
    "perPage": 10
  }
  ```
</ResponseExample>

## Exemplo

```bash theme={"theme":"catppuccin-latte"}
# Listar envelopes finalizados da página 1
curl -X GET "https://signer.vcc-service.com/v1/envelopes?state=FINISHED&page=1&perPage=10" \
  -H "x-api-key: YOUR_API_KEY"

# Filtrar por CPF
curl -X GET "https://signer.vcc-service.com/v1/envelopes?signerCpf=12345678901" \
  -H "x-api-key: YOUR_API_KEY"

# Filtrar por código externo
curl -X GET "https://signer.vcc-service.com/v1/envelopes?externalCode=CONT-2025-001" \
  -H "x-api-key: YOUR_API_KEY"
```

## Relacionado

* [`GET /v1/envelopes/:uuid`](/plataforma/assinatura-digital/api/get-envelope-by-id) — detalhe completo de um envelope
* [`GET /v1/envelopes/:uuid/history`](/plataforma/assinatura-digital/api/get-envelope-history) — histórico de ações