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

# Consultar status da autorização push VIDaaS

> Faz polling do status de uma notificação push em andamento no VIDaaS.

Consulta o status de uma autorização por push iniciada em [`POST /signer/v1/sign/:sessionToken/vidaas/authorization`](/plataforma/assinatura-digital/api/post-vidaas-authorization) com `mode: push`. Use esta chamada repetidamente até que a autorização seja aprovada ou expire.

**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="pushCode" type="string" required>
  Handle devolvido ao abrir a autorização por push (campo `pushCode`). Identifica qual autorização você está consultando.
</ParamField>

## Respostas

<ResponseField name="status" type="string" required>
  Estado da autorização:

  * `pending`: a notificação foi enviada mas o signatário ainda não aprovou no aplicativo — situação normal, não é erro. Faça polling novamente após alguns segundos.
  * `authorized`: a autorização foi concluída com sucesso. Agora você pode chamar [`POST /signer/v1/sign/:sessionToken/sign`](/plataforma/assinatura-digital/api/post-sign).
</ResponseField>

<ResponseField name="certificateHolder" type="string" optional>
  Nome do titular do certificado autorizado. Presente apenas quando `status` = `authorized`.
</ResponseField>

<ResponseField name="certificateIdentifier" type="string" optional>
  CPF/CNPJ do titular do certificado autorizado. Presente apenas quando `status` = `authorized`.
</ResponseField>

<ResponseField name="expiresAt" type="string" optional>
  Vencimento da autorização em ISO-8601. Presente apenas quando `status` = `authorized`.
</ResponseField>

## Erros

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

* **400**: `pushCode` 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

  {
    "status": "pending",
    "certificateHolder": null,
    "certificateIdentifier": null,
    "expiresAt": null
  }
  ```

  ```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 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/poll" \
  -H "Content-Type: application/json" \
  -d '{
    "pushCode": "push_handle_abc123xyz789"
  }'
```

## Importante

* **Sem autenticação por header**: o `sessionToken` é toda a autenticação necessária.
* **Polling**: `status: pending` não é erro — significa que o signatário ainda não aprovou. Implemente polling com intervalo apropriado (ex: a cada 2-5 segundos) e timeout (ex: 5 minutos).
* **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 `status` = `authorized`:

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

Se a autorização expirar ou o signatário rejeitar:

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