> ## 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 histórico do envelope

> Lista o histórico completo de ações do envelope com auditoria (eventos, IPs, geolocalização, verificações biométricas).

Retorna um log completo de todas as ações realizadas no envelope (criação, acesso de signatário, preenchimento de campos, assinatura, recusa, etc.) com detalhes de auditoria como IP, coordenadas de geolocalização e resultado de verificações de liveness.

## Parâmetros

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

## Respostas

<ResponseField name="data" type="array">
  Lista de eventos do histórico.

  <Expandable title="Propriedades de data[]">
    <ResponseField name="description" type="string">
      Descrição legível da ação (ex: `"João Silva (CPF: 123.456.789-**) iniciou a assinatura."`).
    </ResponseField>

    <ResponseField name="signerUuid" type="string">
      UUID do signatário associado a este evento (se aplicável).
    </ResponseField>

    <ResponseField name="systemUuid" type="string">
      UUID do sistema ou usuário que realizou a ação (para ações de admin/operador).
    </ResponseField>

    <ResponseField name="ip" type="string">
      Endereço IP de origem da ação.
    </ResponseField>

    <ResponseField name="latitude" type="number">
      Latitude da geolocalização aproximada (opcional, pode ser null).
    </ResponseField>

    <ResponseField name="longitude" type="number">
      Longitude da geolocalização aproximada (opcional, pode ser null).
    </ResponseField>

    <ResponseField name="accuracy" type="number">
      Precisão da geolocalização em metros (opcional).
    </ResponseField>

    <ResponseField name="livenessVerified" type="boolean">
      Se liveness foi verificado e aprovado neste evento (apenas para assinaturas PAdES).
    </ResponseField>

    <ResponseField name="livenessStatus" type="string">
      Status do liveness: `APPROVED`, `REJECTED`, `NOT_PERFORMED`, etc.
    </ResponseField>

    <ResponseField name="livenessSessionId" type="string">
      ID da sessão de liveness associada.
    </ResponseField>

    <ResponseField name="livenessCaptureId" type="string">
      ID da captura de foto/vídeo de liveness.
    </ResponseField>

    <ResponseField name="livenessFailureReason" type="string">
      Se liveness foi rejeitado, o motivo (ex: `"Face not detected"`, `"Liveness check failed"`).
    </ResponseField>

    <ResponseField name="livenessImageUrl" type="string">
      URL assinada da imagem capturada de liveness (válida por 15 minutos).
    </ResponseField>

    <ResponseField name="fileUuids" type="array">
      UUIDs de arquivo(s) mencionados neste evento (ex: o PDF assinado).
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Timestamp do evento (ISO 8601).
    </ResponseField>
  </Expandable>
</ResponseField>

## Erros

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

* **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

  {
    "data": [
      {
        "description": "Envelope criado",
        "signerUuid": null,
        "systemUuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "ip": "192.168.1.100",
        "latitude": null,
        "longitude": null,
        "livenessVerified": false,
        "createdAt": "2025-07-27T10:30:00.000Z"
      },
      {
        "description": "João Silva (CPF: 123.456.789-**) iniciou a assinatura",
        "signerUuid": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
        "systemUuid": null,
        "ip": "203.0.113.50",
        "latitude": -23.5505,
        "longitude": -46.6333,
        "accuracy": 100,
        "livenessVerified": true,
        "livenessStatus": "APPROVED",
        "livenessSessionId": "liveness-sess-001",
        "livenessCaptureId": "capture-001",
        "livenessImageUrl": "https://storage.googleapis.com/bucket/liveness-001.jpg?X-Goog-Algorithm=...",
        "createdAt": "2025-07-27T15:20:00.000Z"
      },
      {
        "description": "Assinatura de João Silva registrada (PAdES - Lacuna RestPKI)",
        "signerUuid": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
        "ip": "203.0.113.50",
        "latitude": -23.5505,
        "longitude": -46.6333,
        "fileUuids": ["6ba7b812-9dad-11d1-80b4-00c04fd430c8"],
        "createdAt": "2025-07-27T15:20:30.000Z"
      },
      {
        "description": "Maria Santos (CPF: 987.654.321-**) assinou com sucesso",
        "signerUuid": "6ba7b812-9dad-11d1-80b4-00c04fd430c9",
        "ip": "203.0.113.51",
        "latitude": -23.5510,
        "longitude": -46.6340,
        "livenessVerified": true,
        "livenessStatus": "APPROVED",
        "fileUuids": ["6ba7b812-9dad-11d1-80b4-00c04fd430c8"],
        "createdAt": "2025-07-27T15:45:30.000Z"
      },
      {
        "description": "Envelope finalizado - último signatário assinou",
        "signerUuid": null,
        "systemUuid": null,
        "createdAt": "2025-07-27T15:45:31.000Z"
      }
    ]
  }
  ```
</ResponseExample>

## Exemplo

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

## Relacionado

* [`GET /v1/envelopes/:uuid`](/plataforma/assinatura-digital/api/get-envelope-by-id) — detalhe geral do envelope