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

# Abrir autorização VIDaaS

> Abre a autorização do signatário no VIDaaS por QR Code ou notificação push.

Inicia o fluxo de autorização do signatário no VIDaaS. Você pode escolher entre dois modos:

* **`qrcode`**: devolve um endereço que o signatário lê com o aplicativo VIDaaS.
* **`push`**: envia uma notificação para o aplicativo do signatário; você depois consulta o status com polling.

Nenhuma assinatura é feita aqui — apenas a autorização que a precede. Após autorização bem-sucedida, chame [`POST /signer/v1/sign/:sessionToken/sign`](/plataforma/assinatura-digital/api/post-sign) para assinar usando o VIDaaS.

**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 /signer/v1/envelopes`](/plataforma/assinatura-digital/api/post-envelope) ou [`POST /signer/v1/templates/:uuid/envelopes`](/plataforma/assinatura-digital/api/post-template-envelope)).
</ParamField>

<ParamField body="mode" type="enum" required>
  Modo de autorização: `qrcode` ou `push`.

  * `qrcode`: devolve `qrCodeUrl` — o signatário lê com o aplicativo VIDaaS.
  * `push`: devolve `pushCode` — você faz polling para saber quando foi aprovado.
</ParamField>

<ParamField body="identifier" type="string" optional>
  CPF/CNPJ do titular do certificado (quando diferente do signatário). Só é considerado se o signatário não estiver restrito ao próprio documento; caso contrário é ignorado. Formato: números e separadores `.`, `-`, `/`.
</ParamField>

<ParamField body="callbackUrl" type="string" optional>
  URL de retorno do front (para o modo QR Code), quando a origem da requisição não for utilizável. Deve ser da mesma origem que a requisição e já estar cadastrada no cliente VIDaaS. Sem ela, usa-se a origem da requisição + caminho padrão de callback.
</ParamField>

## Respostas

<ResponseField name="mode" type="string" required>
  Eco do modo solicitado: `qrcode` ou `push`.
</ResponseField>

<ResponseField name="qrCodeUrl" type="string" optional>
  Endereço do QR Code para o signatário ler com o aplicativo VIDaaS. Presente apenas se `mode` = `qrcode`.
</ResponseField>

<ResponseField name="pushCode" type="string" optional>
  Handle para acompanhar a aprovação da notificação push. Presente apenas se `mode` = `push`. Passe este valor em [`POST /signer/v1/sign/:sessionToken/vidaas/authorization/poll`](/plataforma/assinatura-digital/api/post-vidaas-authorization-poll).
</ResponseField>

## Erros

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

* **400**: `mode` inválido ou validação falhou.
* **410**: Session token expirado (envelope expirou ou foi deletado).
* **502**: O VIDaaS não respondeu ou respondeu com erro.
* **503**: Integração VIDaaS não configurada no ambiente.

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

  {
    "mode": "qrcode",
    "qrCodeUrl": "https://vidaas.valid.com/auth?code=abc123&state=xyz789",
    "pushCode": null
  }
  ```

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

  {
    "mode": "push",
    "qrCodeUrl": null,
    "pushCode": "push_handle_abc123xyz789"
  }
  ```

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

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

## Exemplos

**QR Code:**

```bash theme={"theme":"catppuccin-latte"}
curl -X POST "https://api.valid.com/signer/v1/sign/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.../vidaas/authorization" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "qrcode"
  }'
```

**Push notification:**

```bash theme={"theme":"catppuccin-latte"}
curl -X POST "https://api.valid.com/signer/v1/sign/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.../vidaas/authorization" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "push"
  }'
```

## Importante

* **Sem autenticação por header**: o `sessionToken` é toda a autenticação necessária.
* **QR Code vs push**: escolha o modo baseado na experiência do usuário desejada. QR Code força redirecionamento; push permite que o signatário autorize no aplicativo dele.
* **Callback URL**: quando está em desenvolvimento ou atrás de proxy, informe `callbackUrl` explicitamente para evitar redirecionamentos quebrados.
* **Autorização com prazo**: a autorização obtida (se bem-sucedida) tem prazo de validade — use [`POST /signer/v1/sign/:sessionToken/sign`](/plataforma/assinatura-digital/api/post-sign) logo após antes de expirar.

## Próximas etapas

**Se `mode` = `qrcode`:**

1. Abra `qrCodeUrl` no navegador (ou exiba como QR Code na tela).
2. O signatário lê o código com o aplicativo VIDaaS.
3. O VIDaaS redireciona o navegador de volta para o `callbackUrl` (ou origem da requisição).
4. Chame [`GET /signer/v1/sign/:sessionToken/vidaas/authorization`](/plataforma/assinatura-digital/api/get-vidaas-authorization-status) para confirmar que a autorização está pronta.
5. Assine com [`POST /signer/v1/sign/:sessionToken/sign`](/plataforma/assinatura-digital/api/post-sign).

**Se `mode` = `push`:**

1. Faça polling com [`POST /signer/v1/sign/:sessionToken/vidaas/authorization/poll`](/plataforma/assinatura-digital/api/post-vidaas-authorization-poll), passando o `pushCode`.
2. Quando a resposta for `status: authorized`, a autorização está pronta.
3. Assine com [`POST /signer/v1/sign/:sessionToken/sign`](/plataforma/assinatura-digital/api/post-sign).