Skip to main content
GET
/
api
/
kyc
/
validations
/
{id}
Verificar Status de Validação
curl --request GET \
  --url http://api.gu1.ai/api/kyc/validations/{id} \
  --header 'Authorization: Bearer <token>'

​
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.
Embora você possa consultar esta API, recomendamos fortemente usar webhooks para receber notificações em tempo real quando a verificação for concluída.

​
Obter Validação por ID

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

​
Exemplo

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

​
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

{
  "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. Registros antigos podem ainda ter URLs HTTPS de curta duração até sincronizar. Exemplos completos (aprovado e rejeitado) em Eventos webhook KYC — objeto decision.

​
Padrões de Integração Comuns

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

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

Em vez de verificar repetidamente o status, use webhooks para receber notificações em tempo real.
Armazene o status de verificação no seu banco de dados e atualize-o via webhooks.
As verificações podem expirar. Verifique needsReverification e solicite aos clientes reverificar quando necessário.

​
Próximos Passos

Criar Validação KYC

Iniciar nova sessão de verificação

Integração Webhook

Obter notificações em tempo real