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

# Assinar documento

> Realiza a assinatura do documento. Escolhe automaticamente entre PAdES avançado ou eletrônica simples conforme verificações.

Assina o documento no envelope. O sistema escolhe automaticamente entre **PAdES avançado** (Lacuna RestPKI, com certificado digital) ou **assinatura eletrônica simples**, conforme o resultado das verificações de autenticação (liveness, MFA).

**Autenticação**: use apenas o `sessionToken` na URL.

## Parâmetros

<ParamField path="sessionToken" type="string" required>
  Token da sessão do signatário.
</ParamField>

<ParamField body="fileUuid" type="string" required>
  UUID do arquivo a assinar (obtido em [`GET /v1/sign/:sessionToken`](/plataforma/assinatura-digital/api/get-sign-session)).
</ParamField>

<ParamField body="liveness" type="object">
  Dados de verificação de liveness (para PAdES avançado). Opcional, mas recomendado.

  <Expandable title="Propriedades de liveness">
    <ParamField body="sessionId" type="string">
      ID da sessão de liveness.
    </ParamField>

    <ParamField body="captureId" type="string">
      ID da captura (foto/vídeo).
    </ParamField>

    <ParamField body="verified" type="boolean">
      Se liveness foi verificado com sucesso.
    </ParamField>

    <ParamField body="status" type="string">
      Status: `APPROVED`, `REJECTED`, etc.
    </ParamField>

    <ParamField body="failureReason" type="string">
      Se rejeitado, o motivo.
    </ParamField>

    <ParamField body="imageBase64" type="string">
      Imagem de liveness em base64 (opcional).
    </ParamField>

    <ParamField body="payload" type="object">
      Payload adicional da verificação (opcional).
    </ParamField>
  </Expandable>
</ParamField>

## Respostas

<ResponseField name="url" type="string">
  URL assinada para download do PDF final assinado. Válida por 15 minutos.
</ResponseField>

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

## Erros

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

* **400**: `fileUuid` não corresponde ao envelope, arquivo não encontrado.
* **404**: Session token inválido.
* **410**: Session token expirado.
* **409**: Envelope já foi assinado ou está em estado terminal.

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

  {
    "url": "https://storage.googleapis.com/bucket/signed-550e8400.pdf?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=...",
    "expiresAt": "2025-07-27T16:00:30.000Z"
  }
  ```

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

  {
    "statusCode": 409,
    "message": "Envelope already signed"
  }
  ```
</ResponseExample>

## Exemplo

```bash theme={"theme":"catppuccin-latte"}
curl -X POST "https://signer.vcc-service.com/signature/envelope-sessions/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.../sign" \
  -H "Content-Type: application/json" \
  -d '{
    "fileUuid": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
    "liveness": {
      "sessionId": "liveness-sess-001",
      "captureId": "capture-001",
      "verified": true,
      "status": "APPROVED"
    }
  }'
```

## Fluxo de assinatura

1. **Pré-assinatura**: signatário preenche campos pendentes (se houver).
2. **Verificação**: sistema valida liveness e/ou MFA.
3. **Escolha de estratégia**: se verificação passou → PAdES (avançado); caso contrário → Eletrônica simples.
4. **Congelamento (templates)**: para envelopes baseados em template, o PDF é renderizado com campos finais antes da assinatura (one-time freeze).
5. **Assinatura**: documento é assinado e armazenado.
6. **Finalização**: se este for o último signatário, webhook `FINISHED` é disparado.

## Padrões de assinatura

| Estratégia             | Requisito                                   | Certificado          | Caso de uso                                 |
| :--------------------- | :------------------------------------------ | :------------------- | :------------------------------------------ |
| **PAdES Avançado**     | Liveness aprovado                           | Sim (Lacuna RestPKI) | Conformidade regulatória, documentos legais |
| **Eletrônica Simples** | MFA aprovado (ou nenhuma verificação em v1) | Não                  | Fluxos internos, documentos de baixo risco  |

## Relacionado

* [`GET /v1/sign/:sessionToken`](/plataforma/assinatura-digital/api/get-sign-session) — obter estado da sessão
* [`POST /v1/sign/:sessionToken/submit`](/plataforma/assinatura-digital/api/post-sign-submit) — fluxo alternativo para templates (preenche + assina em uma chamada)
* [`GET /v1/sign/:sessionToken/signed-document`](/plataforma/assinatura-digital/api/get-sign-session-signed-document) — obter documento assinado após a assinatura