Skip to main content
GET
/
api
/
kyc
/
entities
/
{entityId}
/
current
Obter Validação KYC Atual
curl --request GET \
  --url http://api.gu1.ai/api/kyc/entities/{entityId}/current \
  --header 'Authorization: Bearer <token>'

​
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

​
entityId
string
required
O ID da entidade para obter a validação atual

​
Cabeçalhos

{
  "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: 
{
  "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

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);

​
Respostas de Erro

​
Nenhuma Validação Atual Encontrada (404)

{
  "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)

{
  "error": "ENTITY_NOT_FOUND",
  "message": "Entity not found"
}

​
Notas Importantes

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

​
Próximos Passos

Criar Validação KYC

Iniciar uma nova sessão de verificação

Listar Todas as Validações

Ver histórico de validações de uma entidade

Sincronizar Validação

Atualizar manualmente os dados de validação

Aprovar Validação

Aprovar manualmente uma validação