Listar Validações KYC de uma Entidade

Visão Geral

Este endpoint recupera o histórico completo de validações KYC de uma entidade específica. Isso é útil para auditorias, acompanhamento de conformidade e compreensão da jornada de verificação de uma entidade. Recursos principais:

Retorna todas as validações (atuais e históricas) de uma entidade
Suporta paginação para grandes históricos de validações
Inclui detalhes completos de verificação para cada validação
Ordenado por data de criação (mais recente primeiro)
Mostra qual validação está atualmente ativa

Quando Usar Isso

Auditar histórico de verificação: Ver todas as tentativas de KYC e seus resultados
Relatórios de conformidade: Rastrear tentativas de verificação para conformidade regulatória
Suporte ao usuário: Investigar por que a verificação de um usuário falhou ou teve sucesso
Análises: Analisar taxas de sucesso de verificação e padrões de abandono
Depuração: Solucionar problemas de verificação revisando o histórico completo

Solicitação

Endpoint

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

Parâmetros de Rota

entityId

string

required

O UUID da entidade para recuperar validações

Parâmetros de Query

page

integer

default:"1"

Número da página para paginação (começa em 1)

limit

integer

default:"100"

Número de validações por página (máx 100)

status

string

Filtrar validações por status. Valores possíveis:

pending - Validação criada, usuário não começou
in_progress - Usuário está completando ativamente a 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 - Validação expirou (usuário não completou a tempo)
abandoned - Usuário começou mas não completou
cancelled - Validação foi cancelada pela organização

isCurrent

boolean

Filtrar para mostrar apenas a validação ativa atual (true) ou validações históricas (false)

Cabeçalhos

{
  "Authorization": "Bearer YOUR_API_KEY"
}

Resposta

Resposta de Sucesso (200 OK)

Retorna uma lista paginada de validações:

{
  "validations": [
    {
      "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",
          "full_name": "John Doe",
          "date_of_birth": "1990-01-15"
        }
      },
      "extractedData": {
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1990-01-15",
        "documentType": "Passport"
      },
      "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"
      }
    },
    {
      "id": "440e8400-e29b-41d4-a716-446655440001",
      "entityId": "123e4567-e89b-12d3-a456-426614174000",
      "organizationId": "org_abc123",
      "validationSessionId": "session_abc456",
      "status": "abandoned",
      "provider": "Gu1 KYC",
      "providerSessionUrl": "https://verify.example.com/session_abc456",
      "isCurrent": false,
      "decision": null,
      "extractedData": null,
      "verifiedAt": null,
      "createdAt": "2025-01-20T14:00:00Z",
      "updatedAt": "2025-01-21T10:00:00Z",
      "metadata": {
        "integrationCode": "global_gueno_validation_kyc",
        "integrationName": "Gu1 KYC"
      }
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 100
}

Campos de Resposta

validations

array

Array de objetos de validação

total

integer

Número total de validações que correspondem à consulta

page

integer

Número da página atual

limit

integer

Número de validações por página

Exemplos de Solicitações

Obter Todas as Validações de uma Entidade

const entityId = '123e4567-e89b-12d3-a456-426614174000';

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

const result = await response.json();
console.log(`Encontradas ${result.total} validações`);
console.log(`Página atual: ${result.page} de ${Math.ceil(result.total / result.limit)}`);

result.validations.forEach(validation => {
  console.log(`${validation.id}: ${validation.status} (${validation.isCurrent ? 'atual' : 'histórica'})`);
});

Filtrar por Status

Obter apenas validações aprovadas:

const entityId = '123e4567-e89b-12d3-a456-426614174000';

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

const result = await response.json();
console.log(`Encontradas ${result.total} validações aprovadas`);

Obter Apenas a Validação Atual

const entityId = '123e4567-e89b-12d3-a456-426614174000';

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

const result = await response.json();

if (result.validations.length > 0) {
  const currentValidation = result.validations[0];
  console.log('Status da validação atual:', currentValidation.status);
} else {
  console.log('Nenhuma validação atual encontrada');
}

Exemplo de Paginação

const entityId = '123e4567-e89b-12d3-a456-426614174000';

async function getAllValidations(entityId) {
  let page = 1;
  const limit = 50;
  let allValidations = [];

  while (true) {
    const response = await fetch(
      `https://api.gu1.ai/api/kyc/entities/${entityId}/validations?page=${page}&limit=${limit}`,
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
        },
      }
    );

    const result = await response.json();
    allValidations = allValidations.concat(result.validations);

    console.log(`Página ${page} obtida: ${result.validations.length} validações`);

    // Verificar se obtivemos todas as validações
    if (allValidations.length >= result.total) {
      break;
    }

    page++;
  }

  return allValidations;
}

const validations = await getAllValidations(entityId);
console.log(`Total de validações obtidas: ${validations.length}`);

Respostas de Erro

Entidade Não Encontrada (404)

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

Parâmetros de Query Inválidos (400)

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid status value. Must be one of: pending, in_progress, approved, rejected, expired, abandoned, cancelled"
}

Não Autorizado (401)

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

Casos de Uso

1. Trilha de Auditoria para Conformidade

Rastrear todas as tentativas de verificação para conformidade regulatória:

async function getVerificationAuditTrail(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/api/kyc/entities/${entityId}/validations`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );

  const result = await response.json();

  // Gerar relatório de auditoria
  const auditReport = result.validations.map(v => ({
    validationId: v.id,
    status: v.status,
    provider: v.provider,
    createdAt: v.createdAt,
    completedAt: v.verifiedAt || v.updatedAt,
    isCurrent: v.isCurrent,
    manualAction: v.metadata?.manuallyApprovedBy || v.metadata?.manuallyRejectedBy,
  }));

  return auditReport;
}

2. Calcular Taxa de Sucesso

Analisar taxas de sucesso de verificação:

async function calculateSuccessRate(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/api/kyc/entities/${entityId}/validations`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );

  const result = await response.json();
  const validations = result.validations;

  const completed = validations.filter(v =>
    ['approved', 'rejected'].includes(v.status)
  );

  const approved = validations.filter(v => v.status === 'approved');
  const rejected = validations.filter(v => v.status === 'rejected');
  const abandoned = validations.filter(v => v.status === 'abandoned');

  return {
    total: validations.length,
    completed: completed.length,
    approved: approved.length,
    rejected: rejected.length,
    abandoned: abandoned.length,
    successRate: completed.length > 0
      ? (approved.length / completed.length * 100).toFixed(2) + '%'
      : 'N/A',
    abandonmentRate: validations.length > 0
      ? (abandoned.length / validations.length * 100).toFixed(2) + '%'
      : 'N/A',
  };
}

3. Encontrar Validações Falhadas para Suporte

Ajudar usuários que tiveram problemas de verificação:

async function findFailedValidations(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/api/kyc/entities/${entityId}/validations?status=rejected`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );

  const result = await response.json();

  // Extrair razões de falha
  const failures = result.validations.map(v => ({
    validationId: v.id,
    rejectedAt: v.updatedAt,
    reason: v.metadata?.rejectionReason || 'Não especificado',
    warnings: v.warnings || [],
    decision: v.decision,
  }));

  return failures;
}

4. Exportar Histórico de Validação

Exportar histórico completo de validação para relatórios:

async function exportValidationHistory(entityId) {
  const validations = await getAllValidations(entityId); // Do exemplo de paginação

  // Converter para formato CSV
  const csv = [
    'ID Validação,Status,Provedor,Criado,Verificado,É Atual',
    ...validations.map(v =>
      `${v.id},${v.status},${v.provider},${v.createdAt},${v.verifiedAt || ''},${v.isCurrent}`
    )
  ].join('\n');

  return csv;
}

Notas Importantes

Paginação Padrão

Por padrão, este endpoint retorna até 100 validações por página. Se uma entidade tiver mais de 100 validações, você precisará usar paginação para recuperar todos os registros.

Ordenação

As validações são retornadas em ordem decrescente por data de criação (mais recente primeiro). A validação atual normalmente aparecerá primeiro na lista.

Flag isCurrent

Apenas uma validação por entidade pode ter isCurrent: true por vez. Quando uma nova validação é criada, a validação atual anterior é automaticamente marcada como isCurrent: false.

Retenção de Dados Históricos

Todas as validações são retidas indefinidamente para fins de auditoria e conformidade. As validações históricas nunca são excluídas, mesmo que estejam abandonadas ou expiradas.

Considerações de Desempenho

Para entidades com muitas validações (>100), considere usar paginação e filtros de status para reduzir o tamanho da resposta e melhorar o desempenho.

Diferenças com Endpoints Similares

Endpoint	Propósito	Caso de Uso
`GET /api/kyc/entities/:entityId/validations`	Obter todas as validações de uma entidade	Trilha de auditoria, histórico, análises
`GET /api/kyc/entities/:entityId/current`	Obter apenas a validação atual	Verificar se o usuário está verificado agora
`GET /api/kyc/validations/:id`	Obter validação específica por ID	Recuperar detalhes de uma validação conhecida
`GET /api/kyc/validations`	Listar todas as validações de todas as entidades	Análises em nível de organização

Próximos Passos

Obter Validação Atual

Obter apenas a validação ativa de uma entidade

Criar Validação KYC

Iniciar uma nova sessão de verificação

Verificar Status da Entidade

Obter resumo do status de verificação

Sincronizar Validação

Atualizar dados de validação manualmente

Começando

Casos de Uso

Webhooks

Pessoa

Empresa

Dispositivos

Eventos

Conheça Seu Cliente (KYC)

Transações

Métodos de Pagamento

Regras

Matriz de Risco

Alertas

Investigações

Ingestão de Dados

Enriquecimento

Integrações

Tutoriais Interativos

​Visão Geral

​Quando Usar Isso

​Solicitação

​Endpoint

​Parâmetros de Rota

​Parâmetros de Query

​Cabeçalhos

​Resposta

​Resposta de Sucesso (200 OK)

​Campos de Resposta

​Exemplos de Solicitações

​Obter Todas as Validações de uma Entidade

​Filtrar por Status

​Obter Apenas a Validação Atual

​Exemplo de Paginação

​Respostas de Erro

​Entidade Não Encontrada (404)

​Parâmetros de Query Inválidos (400)

​Não Autorizado (401)

​Casos de Uso

​1. Trilha de Auditoria para Conformidade

​2. Calcular Taxa de Sucesso

​3. Encontrar Validações Falhadas para Suporte

​4. Exportar Histórico de Validação

​Notas Importantes

​Diferenças com Endpoints Similares

​Próximos Passos

Obter Validação Atual

Criar Validação KYC

Verificar Status da Entidade

Sincronizar Validação

Visão Geral

Quando Usar Isso

Solicitação

Endpoint

Parâmetros de Rota

Parâmetros de Query

Cabeçalhos

Resposta

Resposta de Sucesso (200 OK)

Campos de Resposta

Exemplos de Solicitações

Obter Todas as Validações de uma Entidade

Filtrar por Status

Obter Apenas a Validação Atual

Exemplo de Paginação

Respostas de Erro

Entidade Não Encontrada (404)

Parâmetros de Query Inválidos (400)

Não Autorizado (401)

Casos de Uso

1. Trilha de Auditoria para Conformidade

2. Calcular Taxa de Sucesso

3. Encontrar Validações Falhadas para Suporte

4. Exportar Histórico de Validação

Notas Importantes

Diferenças com Endpoints Similares

Próximos Passos