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

# Obter Validação KYC Atual

> Recupera a validação KYC ativa atual de uma entidade — na API KYC da gu1 para fluxos de verificação de identidade, com exemplos para current validation.

## Visão Geral

Este endpoint recupera a validação KYC ativa atual para uma entidade específica. A validação "atual" é a validação mais recente marcada com `isCurrent: true`.

**Recursos principais:**

* Retorna a validação ativa de uma entidade
* Sincroniza automaticamente com o provedor KYC se as imagens expiraram (> 3.5 horas)
* Inclui todos os dados de verificação (documentos, biometria, avaliação de risco)
* Retorna 404 se não existir uma validação atual

## Quando Usar Isso

* **Verificar status de validação**: Ver se uma entidade tem uma validação KYC ativa
* **Exibir dados de verificação**: Mostrar resultados de verificação de documentos e biometria na sua UI
* **Validar identidade do usuário**: Verificar se um usuário completou o KYC antes de permitir certas ações
* **Controles de conformidade**: Verificar que uma entidade tem documentação KYC válida

## Solicitação

### Endpoint

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

### Parâmetros de Rota

<ParamField path="entityId" type="string" required>
  O ID da entidade para obter a validação atual
</ParamField>

### Cabeçalhos

```json theme={null}
{
  "Authorization": "Bearer SUA_API_KEY"
}
```

## Resposta

### Resposta Bem-Sucedida (200 OK)

Retorna o objeto de validação atual com todos os dados de verificação:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entityId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "org_abc123",
  "validationSessionId": "session_xyz789",
  "status": "approved",
  "provider": "Gu1 KYC",
  "providerSessionUrl": "https://verify.example.com/session_xyz789",
  "isCurrent": true,
  "decision": {
    "status": "Approved",
    "features": ["id_verification", "liveness", "face_match"],
    "id_verification": {
      "status": "Approved",
      "document_type": "Passport",
      "document_number": "AB123456",
      "full_name": "João Silva",
      "date_of_birth": "1990-01-15",
      "nationality": "BR"
    },
    "liveness": {
      "status": "Approved",
      "score": 95
    },
    "face_match": {
      "status": "Approved",
      "score": 98
    }
  },
  "extractedData": {
    "firstName": "João",
    "lastName": "Silva",
    "dateOfBirth": "1990-01-15",
    "documentNumber": "AB123456",
    "documentType": "Passport",
    "nationality": "BR"
  },
  "documentsVerified": [
    {
      "type": "Passport",
      "verified": true,
      "verifiedAt": "2025-01-27T10:30:00Z"
    }
  ],
  "biometricResult": {
    "livenessScore": 0.95,
    "faceMatchScore": 0.98,
    "passed": true,
    "timestamp": "2025-01-27T10:30:00Z"
  },
  "riskAssessment": {
    "riskLevel": "low"
  },
  "verifiedFields": [
    "firstName",
    "lastName",
    "dateOfBirth",
    "nationality",
    "documentNumber",
    "documentType"
  ],
  "warnings": [],
  "verifiedAt": "2025-01-27T10:30:00Z",
  "createdAt": "2025-01-27T09:00:00Z",
  "updatedAt": "2025-01-27T10:30:00Z",
  "metadata": {
    "integrationCode": "global_gueno_validation_kyc",
    "integrationName": "Gu1 KYC"
  }
}
```

## Exemplo de Solicitação

<CodeGroup>
  ```javascript Node.js theme={null}
  const entityId = '123e4567-e89b-12d3-a456-426614174000';

  const response = await fetch(
    `https://api.gu1.ai/api/kyc/entities/${entityId}/current`,
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer SUA_API_KEY',
      },
    }
  );

  const validation = await response.json();
  console.log('Status da validação atual:', validation.status);
  console.log('Verificado em:', validation.verifiedAt);
  ```

  ```python Python theme={null}
  import requests

  entity_id = '123e4567-e89b-12d3-a456-426614174000'

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

  validation = response.json()
  print('Status da validação atual:', validation['status'])
  print('Verificado em:', validation.get('verifiedAt'))
  ```

  ```curl cURL theme={null}
  curl -X GET https://api.gu1.ai/api/kyc/entities/123e4567-e89b-12d3-a456-426614174000/current \
    -H "Authorization: Bearer SUA_API_KEY"
  ```
</CodeGroup>

## Respostas de Erro

### Nenhuma Validação Atual Encontrada (404)

```json theme={null}
{
  "error": "NOT_FOUND",
  "message": "No current KYC validation found for this entity"
}
```

Isso significa que a entidade:

* Nunca teve uma validação KYC criada
* Tem validações, mas nenhuma está marcada como atual (`isCurrent: false`)
* Todas as validações estão em estados terminais (cancelada, expirada, etc.)

### Entidade Não Encontrada (404)

```json theme={null}
{
  "error": "ENTITY_NOT_FOUND",
  "message": "Entity not found"
}
```

## Notas Importantes

<AccordionGroup>
  <Accordion title="Sincronização Automática com Provedor">
    Se as imagens da validação têm mais de 3.5 horas, este endpoint sincroniza automaticamente com o provedor KYC para atualizar os dados. Isso garante que você sempre obtenha imagens e dados de verificação atualizados.
  </Accordion>

  <Accordion title="Validações Atuais vs Históricas">
    Apenas uma validação por entidade pode ter `isCurrent: true` de cada vez. Quando uma nova validação é criada, a validação atual anterior é automaticamente marcada como não atual. Use o endpoint `/api/kyc/entities/:entityId/validations` para recuperar validações históricas.
  </Accordion>

  <Accordion title="Valores de Status">
    Possíveis valores do campo `status`:

    * `pending` - Validação criada, o usuário ainda não começou
    * `in_progress` - O usuário está completando a verificação (preenchendo formulário)
    * `in_review` - Verificação completa, requer revisão manual da equipe de compliance
    * `approved` - Verificação aprovada (pelo provedor ou manualmente)
    * `rejected` - Verificação rejeitada (pelo provedor ou manualmente)
    * `expired` - Validação expirou (o usuário não completou a tempo)
    * `abandoned` - O usuário começou mas abandonou o processo
    * `cancelled` - Validação cancelada manualmente
  </Accordion>

  <Accordion title="Proteção de Status Manuais">
    Se uma validação foi aprovada, rejeitada ou cancelada manualmente, ela NÃO será atualizada por webhooks do provedor ou operações de sincronização. Decisões manuais são protegidas para manter a integridade do registro de auditoria.
  </Accordion>
</AccordionGroup>

## Próximos Passos

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

  <Card title="Listar Todas as Validações" icon="list" href="/pt/use-cases/kyc/check-status">
    Ver histórico de validações de uma entidade
  </Card>

  <Card title="Sincronizar Validação" icon="arrows-rotate" href="/pt/use-cases/kyc/sync-validation">
    Atualizar manualmente os dados de validação
  </Card>

  <Card title="Aprovar Validação" icon="check" href="/pt/use-cases/kyc/approve-validation">
    Aprovar manualmente uma validação
  </Card>
</CardGroup>