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

# Obter sessão de assinatura

> Retorna dados da sessão do signatário: envelope, signer, arquivo e campos dinâmicos.

Retorna todos os dados necessários para o signatário assinar: detalhes do envelope, seus dados como signatário, arquivo a assinar e campos dinâmicos (se houver). Esta chamada também marca a sessão como acessada (transição para `SIGNING_IN_PROGRESS`).

**Autenticação**: use apenas o `sessionToken` na URL — nenhum header de autenticação é necessário.

## Parâmetros

<ParamField path="sessionToken" type="string" required>
  Token único da sessão do signatário (obtido em [`POST /v1/envelopes`](/plataforma/assinatura-digital/api/post-envelope) ou [`POST /v1/templates/:uuid/envelopes`](/plataforma/assinatura-digital/api/post-template-envelope)).
</ParamField>

## Respostas

<ResponseField name="envelope" type="object">
  Dados gerais do envelope.

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

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

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

    <ResponseField name="state" type="string">
      Estado atual do envelope.
    </ResponseField>

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

    <ResponseField name="templateId" type="string">
      ID do template (se baseado em template).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="signer" type="object">
  Dados do signatário.

  <Expandable title="Propriedades de signer">
    <ResponseField name="uuid" type="string">
      UUID do signatário.
    </ResponseField>

    <ResponseField name="name" type="string">
      Nome completo (não mascarado neste contexto).
    </ResponseField>

    <ResponseField name="email" type="string">
      E-mail (mascarado parcialmente, ex: `jo***@empresa.com`).
    </ResponseField>

    <ResponseField name="cpf" type="string">
      CPF (mascarado, ex: `123.456.789-**`).
    </ResponseField>

    <ResponseField name="phoneCountryCode" type="string">
      Código de país do telefone.
    </ResponseField>

    <ResponseField name="phoneNumber" type="string">
      Número de telefone.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="file" type="object">
  Arquivo a assinar.

  <Expandable title="Propriedades de file">
    <ResponseField name="uuid" type="string">
      UUID do arquivo.
    </ResponseField>

    <ResponseField name="filename" type="string">
      Nome do arquivo.
    </ResponseField>

    <ResponseField name="mime" type="string">
      MIME type (ex: `application/pdf`).
    </ResponseField>

    <ResponseField name="sizeBytes" type="integer">
      Tamanho em bytes.
    </ResponseField>

    <ResponseField name="downloadUrl" type="string">
      URL assinada para download do PDF (válida por 15 minutos). **Aponta para o PDF em branco/original, não o assinado.**
    </ResponseField>

    <ResponseField name="downloadUrlExpiresAt" type="string">
      Timestamp de expiração da URL.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="fields" type="array">
  Campos dinâmicos do template (vazio se não houver template).

  <Expandable title="Propriedades de fields[]">
    <ResponseField name="key" type="string">
      Identificador do campo.
    </ResponseField>

    <ResponseField name="fieldUuid" type="string">
      UUID interno.
    </ResponseField>

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

    <ResponseField name="label" type="string">
      Rótulo do campo.
    </ResponseField>

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

    <ResponseField name="value" type="string | string[] | boolean">
      Valor atual (pode estar vazio se pendente).
    </ResponseField>

    <ResponseField name="status" type="string">
      Estado: `pending`, `filled`, `locked`, `invalid`.
    </ResponseField>

    <ResponseField name="assignedToMe" type="boolean">
      Se este campo está atribuído ao signatário atual (responsável por preencher).
    </ResponseField>

    <ResponseField name="canFill" type="boolean">
      Se o signatário pode preencher este campo (combinação de `editableBySigner` e estado).
    </ResponseField>

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

## Erros

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

* **404**: Session token não encontrado ou envelope/signatário inválido.
* **410**: Session token expirado (envelope expirou ou foi deletado).

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

  {
    "envelope": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Contrato de Serviços",
      "externalCode": "CONT-2025-001",
      "state": "SIGNING_IN_PROGRESS",
      "dueDate": "2025-12-31T23:59:59Z",
      "templateId": null
    },
    "signer": {
      "uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "name": "João Silva",
      "email": "jo***@empresa.com",
      "cpf": "123.456.789-**",
      "phoneCountryCode": "55",
      "phoneNumber": "11987654321"
    },
    "file": {
      "uuid": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
      "filename": "contrato.pdf",
      "mime": "application/pdf",
      "sizeBytes": 250000,
      "downloadUrl": "https://storage.googleapis.com/bucket/file.pdf?X-Goog-Algorithm=...",
      "downloadUrlExpiresAt": "2025-07-27T11:00:00.000Z"
    },
    "fields": []
  }
  ```

  ```json theme={"theme":"catppuccin-latte"}
  HTTP/1.1 410 Gone
  Content-Type: application/json

  {
    "statusCode": 410,
    "message": "Session expired"
  }
  ```
</ResponseExample>

## Exemplo

```bash theme={"theme":"catppuccin-latte"}
curl -X GET "https://signer.vcc-service.com/v1/sign/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"
```

## Importante

* **Sem autenticação por header**: o `sessionToken` é toda a autenticação necessária.
* **URL de preview**: para visualizar o PDF com campos **preenchidos**, use [`GET /v1/sign/:sessionToken/preview`](/plataforma/assinatura-digital/api/get-sign-session-preview) em vez de `downloadUrl`.
* **Primeiro acesso**: esta chamada marca a sessão como acessada, transicionando o envelope para `SIGNING_IN_PROGRESS`.

## Próximas etapas

1. Se houver campos pendentes: preencha com [`PATCH /v1/sign/:sessionToken/fields`](/plataforma/assinatura-digital/api/patch-sign-session-fields).
2. Visualize o PDF: use [`GET /v1/sign/:sessionToken/preview`](/plataforma/assinatura-digital/api/get-sign-session-preview).
3. Assine: chame [`POST /v1/sign/:sessionToken/sign`](/plataforma/assinatura-digital/api/post-sign) (ou [`POST /signature/envelope-sessions/:sessionToken/submit`](/plataforma/assinatura-digital/api/post-sign-submit) para templates).
4. Se recusar: [`POST /v1/sign/:sessionToken/refuse`](/plataforma/assinatura-digital/api/post-sign-session-refuse).