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

# Apresentação

> Assinatura digital de documentos PDF em envelopes multi-signatário, com PAdES avançado ou eletrônica simples.

Assine documentos PDF de forma segura e escalável, com suporte a múltiplos signatários, campos de dados dinâmicos e dois modos de assinatura (PAdES avançado ou eletrônica simples).

## O produto

A **Assinatura de Envelopes** é um serviço de assinatura digital de PDFs que encapsula workflows complexos de coleta e autenticação de assinaturas. Um "envelope" é um pacote que reúne documento(s), signatário(s) e seu ciclo de vida — desde a criação até a finalização.

O serviço oferece:

* **Envelopes multi-signatário**: organize quantos signatários precisar (sequencial ou paralelo) em um único pacote.
* **Assinatura PAdES avançada**: utiliza certificado digital e a plataforma **Lacuna RestPKI** para gerar assinaturas de conformidade regulatória (LGPD, e-documentos, etc.).
* **Assinatura eletrônica simples**: quando MFA (autenticação multi-fator) é aprovada, registra a assinatura sem certificado.
* **Templates de PDF dinâmicos**: crie templates com campos posicionados (texto, assinatura, checkbox, data, select) que se preenchem via API antes da assinatura.
* **Histórico e auditoria completos**: rastreie cada ação (acesso, preenchimento, recusa, assinatura) com timestamps, IPs e dados de verificação biométrica (liveness, se ativado).
* **Webhooks de status**: notifique seu sistema quando envelopes terminam, expiram ou são cancelados.

## Como funciona

<Steps>
  <Step title="Criar envelope ou template" icon="file-plus" iconType="regular">
    Envie um PDF (direto ou via URL) junto com os dados dos signatários. Se usar um template, especifique os valores para campos dinâmicos. Você recebe um `envelopeUuid` e um `sessionToken` único para cada signatário.
  </Step>

  <Step title="Compartilhar com signatários" icon="share-nodes" iconType="regular">
    Envie para cada signatário um link ou embed contendo o seu `sessionToken` (ex: `https://seu-app.com/assinar/{sessionToken}`). O token encapsula a identidade do signatário e o escopo de acesso.
  </Step>

  <Step title="Signatário preenche e assina" icon="pen" iconType="regular">
    Cada signatário acessa a sessão, visualiza o documento, preenche campos pendentes (se houver) e assina. O sistema renderiza o PDF com os campos preenchidos uma única vez (congelamento PAdES) antes da primeira assinatura.
  </Step>

  <Step title="Autenticação e assinatura" icon="lock" iconType="regular">
    O sistema verifica a legitimidade (liveness, MFA) e escolhe a estratégia: se validado, usa PAdES avançado (Lacuna RestPKI); caso contrário, registra como eletrônica simples. Ambas geram assinaturas legalmente válidas.
  </Step>

  <Step title="Finalização e notificação" icon="check-circle" iconType="regular">
    Quando o último signatário assina, o envelope passa ao estado `FINISHED`. Um webhook (se configurado) notifica seu backend, e um e-mail com link de download é disparado.
  </Step>
</Steps>

### Modos de assinatura

| Modo                   | Via                | Requisito           | Caso de uso                                                   |
| :--------------------- | :----------------- | :------------------ | :------------------------------------------------------------ |
| **PAdES Avançado**     | Lacuna RestPKI     | Certificado digital | Conformidade regulatória, documentos legais, LOAs altos       |
| **Eletrônica Simples** | Plataforma interna | MFA aprovada        | Fluxos internos, documentos de baixo risco, assinatura rápida |

A estratégia é escolhida automaticamente no momento da assinatura, conforme os dados de verificação fornecidos (sessão de liveness, transação MFA aprovada, etc.).

### Estados de um envelope

* **Criado**: acabou de ser criado, signatários podem acessar as sessões.
* **Assinatura iniciada**: o primeiro signatário começou a assinar.
* **Concluído**: o último signatário assinou — envelope finalizado.
* **Cancelado**: cancelado explicitamente via API.
* **Expirado**: nenhum signatário acessou dentro do prazo (calculado a partir da `dueDate`).
* **Recusado**: algum signatário recusou a assinatura (com motivo registrado).

## FAQ

Dúvidas mais comuns sobre Assinatura de Envelopes:

<AccordionGroup>
  <Accordion title="Qual a diferença entre PAdES avançado e eletrônica simples?">
    **PAdES avançado** usa um certificado digital (ICP-Brasil ou equivalente) fornecido pela plataforma **Lacuna RestPKI**, gerando assinaturas de conformidade regulatória com garantia criptográfica forte. **Eletrônica simples** registra a assinatura sem certificado, válida legalmente quando acompanhada de prova de autenticação (MFA, liveness). A escolha é automática: se o signatário passar nas verificações configuradas (ex: liveness aprovado), PAdES é usado; caso contrário, a assinatura fica como eletrônica simples.
  </Accordion>

  <Accordion title="O sessionToken expira? O que acontece se o signatário acessar depois?">
    Sim, o `sessionToken` está vinculado à `dueDate` do envelope. Se o signatário não acessar até essa data, a sessão retorna **410 Gone**. Você pode renovar enviando um novo `sessionToken` via `PATCH` no signatário ou criando um novo envelope. Se a sessão expirou mas o signatário ainda tenta acessar, o envelope é marcado como `Expirado` e um webhook `EXPIRED` é disparado (se configurado).
  </Accordion>

  <Accordion title="Posso editar os campos de um template depois da primeira assinatura?">
    Não. Quando o primeiro signatário assina um envelope baseado em template, o PDF é renderizado com todos os campos congelados (PAdES não permite adicionar conteúdo após assinatura sem invalidar a assinatura anterior). Todos os dados precisam estar preenchidos/confirmados **antes** da primeira assinatura. Planeje seus templates para coletar tudo que é necessário nos passos anteriores.
  </Accordion>

  <Accordion title="Como sei quando um envelope foi finalizado se não confio só em webhooks?">
    Use polling: faça `GET /v1/envelopes/:uuid` periodicamente e verifique o campo `state`. Webhooks são best-effort (disparados uma única vez, sem retry em caso de falha) — sempre tenha polling como fallback para fluxos críticos. Você pode combinar: aguarde o webhook, mas confirme chamando a API.
  </Accordion>

  <Accordion title="Por quanto tempo as URLs de download do documento ficam válidas?">
    Todas as URLs assinadas (PDF em branco, documento assinado, pré-visualização) expiram em **15 minutos** por padrão. Se precisar de uma URL nova, chame o endpoint correspondente novamente (ex: `GET /v1/envelopes/:uuid/signed-document`). Use `expiresAt` na resposta para saber exatamente quando a URL caduca.
  </Accordion>

  <Accordion title="Posso usar a API sem autenticação?">
    Endpoints do **signatário** (`v1/sign/*`, `signature/*`) não exigem header de autenticação — o `sessionToken` na URL já funciona como credencial. Endpoints de **administrador/plataforma** (`v1/envelopes/*`, `v1/templates/*`) exigem `x-api-key` ou `Authorization: Bearer` com headers de projeto/organização. Veja [Autenticação e Erros](/plataforma/assinatura-digital/api/erros-e-autenticacao) para detalhes.
  </Accordion>
</AccordionGroup>

## Próximos passos

Comece agora com a API ou conheça outras soluções:

<Columns cols={2}>
  <Column>
    <Card title="Criar um envelope" icon="rocket" href="/plataforma/assinatura-digital/api/post-envelope">
      Entenda como criar seu primeiro envelope com a API
    </Card>
  </Column>

  <Column>
    <Card title="Usar templates dinâmicos" icon="file-invoice" href="/plataforma/assinatura-digital/api/post-template">
      Crie templates de PDF com campos posicionados
    </Card>
  </Column>
</Columns>

Ou explore as operações relacionadas:

<Columns cols={2}>
  <Column>
    <Card title="Fluxo de assinatura do signatário" icon="pen-nib" href="/plataforma/assinatura-digital/api/get-sign-session">
      Como um signatário acessa e assina via sessionToken
    </Card>
  </Column>

  <Column>
    <Card title="Webhooks de notificação de status" icon="bell" href="/plataforma/assinatura-digital/api/notificacoes-webhook">
      Receba notificações de status de envelopes
    </Card>
  </Column>
</Columns>