Obter Validação KYC Atual

curl --request GET \
  --url http://api.gu1.ai/api/kyc/entities/{entityId}/current \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/api/kyc/entities/{entityId}/current', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/api/kyc/entities/{entityId}/current",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/api/kyc/entities/{entityId}/current"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/api/kyc/entities/{entityId}/current")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/api/kyc/entities/{entityId}/current', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/api/kyc/entities/{entityId}/current",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/api/kyc/entities/{entityId}/current"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/api/kyc/entities/{entityId}/current")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

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

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 -X GET https://api.gu1.ai/api/kyc/entities/123e4567-e89b-12d3-a456-426614174000/current \
  -H "Authorization: Bearer SUA_API_KEY"

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

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.

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.

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

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.

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

​Visão Geral

​Quando Usar Isso

​Solicitação

​Endpoint

​Parâmetros de Rota

​Cabeçalhos

​Resposta

​Resposta Bem-Sucedida (200 OK)

​Exemplo de Solicitação

​Respostas de Erro

​Nenhuma Validação Atual Encontrada (404)

​Entidade Não Encontrada (404)

​Notas Importantes

​Próximos Passos