Verificar Status de Validação

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

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

fetch('http://api.gu1.ai/api/kyc/validations/{id}', 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/validations/{id}",
  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/validations/{id}"

	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/validations/{id}")

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

validations

{id}

Verificar Status de Validação

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

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

fetch('http://api.gu1.ai/api/kyc/validations/{id}', 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/validations/{id}",
  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/validations/{id}"

	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/validations/{id}")

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

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

validation_id = '550e8400-e29b-41d4-a716-446655440000'

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

validation = response.json()

print('Status:', validation['status'])
print('Verificado:', validation['status'] == 'approved')

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

Usar Webhooks, Não Polling

Em vez de verificar repetidamente o status, use webhooks para receber notificações em tempo real.

Cachear Status de Verificação

Armazene o status de verificação no seu banco de dados e atualize-o via webhooks.

Lidar com Verificações Expiradas

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

Listar Validações KYC de uma Entidade Sincronizar Validação KYC

⌘I

Começando

SDK

Casos de Uso

Webhooks

Workflows

Monitoramento (entidades)

Pessoa

Mensagens

Empresa

Dispositivos

Eventos

Conheça Seu Cliente (KYC)

Transações

Métodos de Pagamento

Regras

Listas de dados

Matriz de Risco

Alertas

Investigações

Ingestão de Dados

Importações em lote

Enriquecimento

Serviços

Integrações

Tutoriais Interativos

Verificar Status de Validação

Resumo

Obter Validação por ID

Exemplo

Obter Validação Atual para Entidade

Obter Status KYC da Entidade

Resposta

Valores de Status

Objeto `decision`

Padrões de Integração Comuns

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

Melhores Práticas

Próximos Passos

Criar Validação KYC

Integração Webhook

​Resumo

​Obter Validação por ID

​Exemplo

​Obter Validação Atual para Entidade

​Obter Status KYC da Entidade

​Resposta

​Valores de Status

​Objeto decision

​Padrões de Integração Comuns

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

​Melhores Práticas

​Próximos Passos

Criar Validação KYC

Integração Webhook

Resumo

Obter Validação por ID

Exemplo

Obter Validação Atual para Entidade

Obter Status KYC da Entidade

Resposta

Valores de Status

Objeto `decision`

Padrões de Integração Comuns

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

Melhores Práticas

Próximos Passos