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

# Completar autorização QR Code VIDaaS

> Conclui o fluxo de QR Code trocando o código de autorização do VIDaaS por uma sessão autorizada.

Conclui o fluxo de autorização por QR Code no VIDaaS. Após o signatário ler o QR Code com o aplicativo VIDaaS, o provedor o redireciona de volta para a sua aplicação com um código de autorização — passe-o aqui para trocar por uma autorização confirmada.

Esta chamada verifica o dono do certificado (valida o CPF/CNPJ) e armazena a autorização para que [`POST /signer/v1/sign/:sessionToken/sign`](/plataforma/assinatura-digital/api/post-sign) possa usá-la.

**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="code" type="string" required>
  Código de autorização devolvido pelo VIDaaS na volta do QR Code. O VIDaaS devolve este código como parâmetro `code` na URL de redirecionamento (ex: `https://seu-app.com/callback?code=AUTH_CODE&state=...`).
</ParamField>

## Respostas

<ResponseField name="status" type="string" required>
  Sempre `authorized` quando a resposta é bem-sucedida.
</ResponseField>

<ResponseField name="certificateHolder" type="string" required>
  Nome do titular do certificado autorizado.
</ResponseField>

<ResponseField name="certificateIdentifier" type="string" required>
  CPF/CNPJ do titular do certificado autorizado.
</ResponseField>

<ResponseField name="expiresAt" type="string" required>
  Vencimento da autorização em ISO-8601.
</ResponseField>

## Erros

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

* **400**: `code` inválido, expirado ou validação falhou.
* **403**: O certificado autorizado pertence a outro CPF/CNPJ (o dono do certificado não corresponde ao signatário).
* **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

  {
    "status": "authorized",
    "certificateHolder": "João da Silva",
    "certificateIdentifier": "12345678909",
    "expiresAt": "2025-07-27T12:15:00Z"
  }
  ```

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

  {
    "statusCode": 403,
    "message": "Certificate owner CPF does not match signer CPF",
    "error": {
      "code": "INVALID_CERTIFICATE_OWNER",
      "details": "O certificado pertence a 98765432101, mas o signatário da sessão é 12345678909."
    }
  }
  ```

  ```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 POST "https://api.valid.com/signer/v1/sign/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.../vidaas/authorization/callback" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "AUTH_CODE_ABC123XYZ789"
  }'
```

## Importante

* **Sem autenticação por header**: o `sessionToken` é toda a autenticação necessária.
* **Validação do dono**: este endpoint verifica que o CPF/CNPJ do certificado autorizado corresponde ao do signatário da sessão. Se não corresponder, retorna **403**.
* **Código com prazo**: o `code` devolvido pelo VIDaaS tem um prazo (tipicamente alguns minutos) — complete esta chamada logo após o redirecionamento.
* **Autorização com prazo**: a autorização, quando concedida, expira em um prazo — use [`POST /signer/v1/sign/:sessionToken/sign`](/plataforma/assinatura-digital/api/post-sign) logo após antes de expirar.

## Próximas etapas

Quando a autorização é concluída com sucesso:

1. Chame [`POST /signer/v1/sign/:sessionToken/sign`](/plataforma/assinatura-digital/api/post-sign) para assinar usando o certificado VIDaaS autorizado.

Se o `code` for inválido ou expirado:

1. Comece um novo fluxo de autorização com [`POST /signer/v1/sign/:sessionToken/vidaas/authorization`](/plataforma/assinatura-digital/api/post-vidaas-authorization).

Se o certificado pertencer a outro CPF/CNPJ (erro 403):

1. Avise ao signatário que precisa usar um certificado no seu próprio nome.