Skip to main content
POST
http://api.gu1.ai
/
api
/
kyc
/
validations
/
{id}
/
sync
Sincronizar Validação KYC
curl --request POST \
  --url http://api.gu1.ai/api/kyc/validations/{id}/sync \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "force": true
}'

​
Visão Geral

Este endpoint permite sincronizar manualmente uma validação KYC com o provedor de verificação para obter o status e os dados de decisão mais recentes. Quando você sincroniza:
  • Busca os dados mais recentes do provedor KYC em tempo real
  • Atualiza URLs de imagens expiradas (URLs do provedor expiram após ~4 horas)
  • Atualiza o status da validação se o provedor tomou uma decisão
  • Preserva decisões manuais - não sobrescreve validações aprovadas/rejeitadas/canceladas manualmente
  • Retorna dados de verificação atualizados incluindo documentos, biometria e avaliação de risco
A sincronização é útil quando você precisa de dados atualizados imediatamente sem esperar por webhooks, ou quando as URLs de imagens expiraram e você precisa visualizar os documentos de verificação.

​
Quando Usar Isso

  • Verificar status atual: Obter atualizações de status em tempo real do provedor
  • Atualizar imagens expiradas: URLs de imagens do provedor expiram após 4 horas
  • Forçar atualização: Acionar manualmente uma sincronização se a entrega do webhook falhou
  • Depurar verificação: Revisar os dados e decisões de verificação mais recentes
  • Antes de decisão manual: Sincronizar antes de aprovar/rejeitar para ver os dados mais recentes do provedor

​
Solicitação

​
Endpoint

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

​
Parâmetros de Rota

​
id
string
required
O ID da validação a ser sincronizada

​
Cabeçalhos

{
  "Authorization": "Bearer SUA_API_KEY",
  "Content-Type": "application/json"
}

​
Parâmetros do Corpo

​
force
boolean
Forçar sincronização mesmo se sincronizado recentemente (opcional)Tipo: boolean (padrão: false)Exemplo: true

​
Resposta

​
Resposta de Sucesso (200 OK)

Retorna o objeto de validação atualizado com os dados mais recentes do provedor: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entityId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "org_abc123",
  "validationSessionId": "session_xyz789",
  "status": "approved",
  "provider": "Provedor KYC",
  "providerSessionUrl": "https://verify.example.com/session_xyz789",
  "decision": {
    "status": "Approved",
    "features": ["id_verification", "liveness", "face_match"],
    "id_verification": {
      "status": "Approved",
      "document_type": "Identity Card",
      "first_name": "João",
      "last_name": "Silva",
      "date_of_birth": "1990-05-15",
      "nationality": "BR",
      "front_image": "https://provider.com/fresh-url-1.jpg",
      "portrait_image": "https://provider.com/fresh-url-2.jpg"
    },
    "liveness": {
      "status": "Approved",
      "score": 98,
      "method": "PASSIVE",
      "reference_image": "https://provider.com/fresh-url-3.jpg"
    },
    "face_match": {
      "status": "Approved",
      "score": 95
    }
  },
  "extractedData": {
    "firstName": "João",
    "lastName": "Silva",
    "dateOfBirth": "1990-05-15",
    "nationality": "BR",
    "documentNumber": "AB123456",
    "documentType": "Identity Card"
  },
  "documentsVerified": [
    {
      "type": "Identity Card",
      "verified": true,
      "verifiedAt": "2025-01-27T10:30:00Z"
    }
  ],
  "biometricResult": {
    "livenessScore": 0.98,
    "faceMatchScore": 0.95,
    "passed": true,
    "timestamp": "2025-01-27T10:30:00Z"
  },
  "riskAssessment": {
    "riskLevel": "low"
  },
  "verifiedFields": ["firstName", "lastName", "dateOfBirth", "nationality", "documentNumber"],
  "warnings": [],
  "isCurrent": true,
  "verifiedAt": "2025-01-27T10:30:00Z",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-27T10:30:00Z"
}

​
Exemplo de Solicitação

const validationId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://api.gu1.ai/api/kyc/validations/${validationId}/sync`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer SUA_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      force: false
    })
  }
);

const synced = await response.json();
console.log('Validação sincronizada:', synced.status);
console.log('Atualizada em:', synced.updatedAt);

​
Respostas de Erro

​
Validação Não Encontrada (404)

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

​
Sem ID de Sessão (400)

A validação não tem sessão do provedor para sincronizar: 
{
  "error": "NO_SESSION_ID",
  "message": "Validation has no session ID"
}

​
Integração do Provedor Não Configurada (400)

{
  "error": "INTEGRATION_NOT_CONFIGURED",
  "message": "Integration not configured for organization: kyc_provider_code"
}

​
Notas Importantes

As validações são sincronizadas automaticamente ao serem consultadas via GET se as imagens tiverem mais de 3.5 horas. A sincronização manual é útil quando você precisa de atualizações imediatas.
Se uma validação foi aprovada, rejeitada ou cancelada manualmente, a sincronização NÃO sobrescreverá essa decisão. Decisões manuais são preservadas para manter trilhas de auditoria.
URLs de imagens do provedor (fotos de documentos, selfies) expiram após ~4 horas. A sincronização busca URLs atualizadas para que você possa visualizar os documentos novamente.
Se o provedor tomou uma decisão desde a última sincronização, o status da validação será atualizado automaticamente (a menos que tenha um status manual).
A sincronização NÃO cobra créditos. Os créditos são cobrados apenas quando uma validação atinge um estado final (aprovada/rejeitada) pela primeira vez.

​
Casos de Uso

​
1. Atualizar Imagens Expiradas

// O usuário deseja revisar documentos mas as imagens expiraram
const validation = await fetch(
  `https://api.gu1.ai/api/kyc/validations/${validationId}/sync`,
  {
    method: 'POST',
    headers: { 'Authorization': 'Bearer SUA_API_KEY' }
  }
);

const data = await validation.json();
// URLs de imagens atualizadas disponíveis em data.decision.id_verification.front_image

​
2. Verificar Status Antes de Decisão Manual

// Sincronizar antes de tomar uma decisão de aprovação manual
const synced = await fetch(
  `https://api.gu1.ai/api/kyc/validations/${validationId}/sync`,
  { method: 'POST', headers: { 'Authorization': 'Bearer SUA_API_KEY' } }
);

const data = await synced.json();

// Revisar dados mais recentes do provedor
console.log('Status do provedor:', data.status);
console.log('Nível de risco:', data.riskAssessment?.riskLevel);
console.log('Avisos:', data.warnings);

// Então aprovar se satisfeito
if (data.status === 'in_progress' && data.warnings.length === 0) {
  await approveValidation(validationId, 'Todas as verificações passaram');
}

​
3. Forçar Atualização Após Falha de Webhook

// Se você suspeita que os webhooks não foram entregues
const validations = await getValidationsWithStatus('in_progress');

for (const validation of validations) {
  // Sincronizar cada uma para obter o status mais recente
  await fetch(
    `https://api.gu1.ai/api/kyc/validations/${validation.id}/sync`,
    {
      method: 'POST',
      headers: { 'Authorization': 'Bearer SUA_API_KEY' },
      body: JSON.stringify({ force: true })
    }
  );
}

​
Próximos Passos

Aprovar Validação

Aprovar manualmente uma validação

Rejeitar Validação

Rejeitar manualmente uma validação

Verificar Status de Verificação

Consultar resultados de validação

Cancelar Validação

Cancelar uma validação pendente