> ## 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 campos do envelope

> Lista os campos dinâmicos de um envelope baseado em template, com seus valores, origem e estado.

Retorna todos os campos dinâmicos de um envelope (quando criado a partir de um template), incluindo valores preenchidos, origem (API, operador, signatário) e estado (pendente, preenchido, bloqueado).

## Parâmetros

<ParamField path="uuid" type="string" required>
  UUID do envelope.
</ParamField>

## Respostas

<ResponseField name="fields" type="array">
  Lista de campos do template (cada um é um `EnvelopeFieldBlock`).

  <Expandable title="Propriedades de fields[]">
    <ResponseField name="key" type="string">
      Identificador único do campo (ex: `"nome_cliente"`). Imutável, define a integração.
    </ResponseField>

    <ResponseField name="fieldUuid" type="string">
      UUID interno do campo (para compatibilidade com endpoints que aceitam UUID).
    </ResponseField>

    <ResponseField name="type" type="string">
      Tipo do campo: `text`, `signature`, `checkbox`, `radio`, `date`, `select`.
    </ResponseField>

    <ResponseField name="label" type="string">
      Rótulo do campo (ex: `"Nome do Cliente"`).
    </ResponseField>

    <ResponseField name="required" type="boolean">
      Se é obrigatório.
    </ResponseField>

    <ResponseField name="pageIndex" type="integer">
      Página do PDF onde o campo aparece (0-indexado).
    </ResponseField>

    <ResponseField name="x" type="number">
      Coordenada X normalizada (0 a 1, origem no topo-esquerdo).
    </ResponseField>

    <ResponseField name="y" type="number">
      Coordenada Y normalizada (0 a 1).
    </ResponseField>

    <ResponseField name="width" type="number">
      Largura normalizada (0 a 1).
    </ResponseField>

    <ResponseField name="height" type="number">
      Altura normalizada (0 a 1).
    </ResponseField>

    <ResponseField name="value" type="string | string[] | boolean">
      Valor atual do campo. Para `checkbox`, array de strings selecionadas. Para `radio`/`select`, string única. Para booleanos, `true`/`false`.
    </ResponseField>

    <ResponseField name="origin" type="string">
      Origem do valor: `api` (vindo da API), `operator` (preenchido por operador), `signer` (preenchido por signatário), `default` (valor padrão do template), `null` (pendente).
    </ResponseField>

    <ResponseField name="status" type="string">
      Estado do campo: `pending` (sem valor), `filled` (preenchido), `locked` (preenchido e não editável), `invalid` (valor inválido).
    </ResponseField>

    <ResponseField name="displayState" type="string">
      Estado para exibição: `pending`, `filled_by_api`, `filled_by_operator`, `filled_by_signer`, `default`, `locked`, `invalid`.
    </ResponseField>

    <ResponseField name="assignedSignerId" type="string">
      UUID do signatário responsável por preencher este campo (se for um campo de dados atribuído a alguém).
    </ResponseField>

    <ResponseField name="editableBySigner" type="boolean">
      Se o signatário pode editar este campo (mesmo que já tenha valor pré-preenchido).
    </ResponseField>

    <ResponseField name="options" type="array">
      Para `radio`/`select`, lista de opções disponíveis (`{ label, value }`).
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros

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

* **400**: Envelope não baseado em template (sem campos).
* **401**: API key inválido.
* **404**: Envelope não encontrado.

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

  {
    "fields": [
      {
        "key": "nome_cliente",
        "fieldUuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "type": "text",
        "label": "Nome do Cliente",
        "required": true,
        "pageIndex": 0,
        "x": 0.1,
        "y": 0.2,
        "width": 0.8,
        "height": 0.05,
        "value": "Empresa XYZ Ltda.",
        "origin": "api",
        "status": "filled",
        "displayState": "filled_by_api",
        "assignedSignerId": null,
        "editableBySigner": false
      },
      {
        "key": "data_assinatura",
        "fieldUuid": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
        "type": "date",
        "label": "Data de Assinatura",
        "required": true,
        "pageIndex": 0,
        "x": 0.1,
        "y": 0.3,
        "width": 0.4,
        "height": 0.05,
        "value": null,
        "origin": null,
        "status": "pending",
        "displayState": "pending",
        "assignedSignerId": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
        "editableBySigner": true
      },
      {
        "key": "termos_aceitos",
        "fieldUuid": "6ba7b813-9dad-11d1-80b4-00c04fd430c8",
        "type": "checkbox",
        "label": "Aceito os termos e condições",
        "required": true,
        "pageIndex": 1,
        "x": 0.1,
        "y": 0.8,
        "width": 0.8,
        "height": 0.1,
        "value": ["opcao_a", "opcao_c"],
        "origin": "signer",
        "status": "filled",
        "displayState": "filled_by_signer",
        "assignedSignerId": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
        "editableBySigner": true,
        "options": [
          { "label": "Opção A", "value": "opcao_a" },
          { "label": "Opção B", "value": "opcao_b" },
          { "label": "Opção C", "value": "opcao_c" }
        ]
      }
    ]
  }
  ```
</ResponseExample>

## Exemplo

```bash theme={"theme":"catppuccin-latte"}
curl -X GET "https://signer.vcc-service.com/v1/envelopes/550e8400-e29b-41d4-a716-446655440000/fields" \
  -H "x-api-key: YOUR_API_KEY"
```

## Relacionado

* [`PATCH /v1/envelopes/:uuid/fields`](/plataforma/assinatura-digital/api/patch-envelope-fields) — operador preenche/edita campos
* [`PATCH /v1/sign/:sessionToken/fields`](/plataforma/assinatura-digital/api/patch-sign-session-fields) — signatário preenche campos