> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Verificar Status de Validação

> Consulte o resultado de uma validação KYC e os detalhes de verificação por ID na API KYC da gu1 para fluxos de verificação de identidade.

## Resumo

Após um cliente completar sua verificação KYC, você pode consultar os resultados para verificar o status, dados extraídos e detalhes de decisão.

<Note>
  Embora você possa consultar esta API, recomendamos fortemente usar [webhooks](/pt/use-cases/kyc/webhook-integration) para receber notificações em tempo real quando a verificação for concluída.
</Note>

## Obter Validação por ID

```
GET https://api.gu1.ai/api/kyc/validations/{id}
```

### Exemplo

<CodeGroup>
  ```javascript Node.js theme={null}
  const validationId = '550e8400-e29b-41d4-a716-446655440000';

  const response = await fetch(
    `https://api.gu1.ai/api/kyc/validations/${validationId}`,
    {
      headers: {
        'Authorization': 'Bearer SUA_API_KEY'
      }
    }
  );

  const validation = await response.json();

  console.log('Status:', validation.status);
  console.log('Verificado:', validation.status === 'approved');

  if (validation.status === 'approved') {
    console.log('Dados verificados:', validation.extractedData);
  }
  ```

  ```python Python theme={null}
  validation_id = '550e8400-e29b-41d4-a716-446655440000'

  response = requests.get(
      f'https://api.gu1.ai/api/kyc/validations/{validation_id}',
      headers={'Authorization': 'Bearer SUA_API_KEY'}
  )

  validation = response.json()

  print('Status:', validation['status'])
  print('Verificado:', validation['status'] == 'approved')
  ```
</CodeGroup>

## Obter Validação Atual para Entidade

```
GET https://api.gu1.ai/api/kyc/entities/{entityId}/current
```

## Obter Status KYC da Entidade

```
GET https://api.gu1.ai/api/kyc/entities/{entityId}/status
```

### Resposta

```json theme={null}
{
  "entityId": "123e4567-e89b-12d3-a456-426614174000",
  "hasKyc": true,
  "isVerified": true,
  "currentValidation": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "approved",
    "verifiedAt": "2025-01-15T11:00:00Z"
  },
  "lastVerifiedAt": "2025-01-15T11:00:00Z",
  "needsReverification": false
}
```

## Valores de Status

* **`pending`** - Aguardando cliente iniciar
* **`in_progress`** - Cliente completando verificação (preenchendo formulário)
* **`in_review`** - Verificação completa, requer revisão manual da equipe de compliance
* **`approved`** - Verificação bem-sucedida
* **`rejected`** - Verificação falhou
* **`expired`** - Sessão expirou
* **`abandoned`** - Cliente não completou
* **`cancelled`** - Validação cancelada manualmente

## Objeto `decision`

Quando o status é `approved` ou `rejected`, o campo `decision` contém o resultado completo do fluxo KYC. O Gu1 **sempre persiste e devolve ambas as formas** por feature: objeto singular (legacy) **e** array de um elemento (atual). Você pode ler `id_verification` ou `id_verifications[0]`; eles ficam sincronizados. O mesmo vale para `liveness` / `liveness_checks`, `face_match` / `face_matches`, `aml_screening` / `aml_screenings` e `ip_analysis` / `ip_analyses`.

Campos de mídia (`front_image`, `reference_image`, `images.*`, etc.) são **chaves de armazenamento Gu1** (`kyc/...`) após o ingest. Obtenha-as via a [API de mídia de validação](/pt/use-cases/kyc/validation-media). Registros antigos podem ainda ter URLs HTTPS de curta duração até sincronizar.

Exemplos completos (aprovado e rejeitado) em [Eventos webhook KYC — objeto decision](/pt/webhooks/events/kyc-events#objeto-decision-payloaddecision).

## Padrões de Integração Comuns

### Padrão 1: Verificar Antes de Permitir Ação

```javascript theme={null}
async function requererVerificacao(entityId) {
  const status = await fetch(
    `https://api.gu1.ai/api/kyc/entities/${entityId}/status`,
    { headers: { 'Authorization': 'Bearer SUA_API_KEY' } }
  ).then(r => r.json());

  if (!status.isVerified) {
    throw new Error('Cliente deve completar verificação de identidade');
  }

  return true;
}
```

## Melhores Práticas

<AccordionGroup>
  <Accordion title="Usar Webhooks, Não Polling">
    Em vez de verificar repetidamente o status, use [webhooks](/pt/use-cases/kyc/webhook-integration) para receber notificações em tempo real.
  </Accordion>

  <Accordion title="Cachear Status de Verificação">
    Armazene o status de verificação no seu banco de dados e atualize-o via webhooks.
  </Accordion>

  <Accordion title="Lidar com Verificações Expiradas">
    As verificações podem expirar. Verifique `needsReverification` e solicite aos clientes reverificar quando necessário.
  </Accordion>
</AccordionGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Criar Validação KYC" icon="play" href="/pt/use-cases/kyc/create-validation">
    Iniciar nova sessão de verificação
  </Card>

  <Card title="Integração Webhook" icon="webhook" href="/pt/use-cases/kyc/webhook-integration">
    Obter notificações em tempo real
  </Card>
</CardGroup>