Sincronizar Validação KYC

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

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

Sincronização Automática

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.

Decisões Manuais São Protegidas

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.

Atualização de URLs de Imagens

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.

Atualizações de Status

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

Cobrança de Créditos

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

​Visão Geral

​Quando Usar Isso

​Solicitação

​Endpoint

​Parâmetros de Rota

​Cabeçalhos

​Parâmetros do Corpo

​Resposta

​Resposta de Sucesso (200 OK)

​Exemplo de Solicitação

​Respostas de Erro

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

​Sem ID de Sessão (400)

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

​Notas Importantes

​Casos de Uso

​1. Atualizar Imagens Expiradas

​2. Verificar Status Antes de Decisão Manual

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

​Próximos Passos

Aprovar Validação

Rejeitar Validação

Verificar Status de Verificação

Cancelar Validação

Visão Geral

Quando Usar Isso

Solicitação

Endpoint

Parâmetros de Rota

Cabeçalhos

Parâmetros do Corpo

Resposta

Resposta de Sucesso (200 OK)

Exemplo de Solicitação

Respostas de Erro

Validação Não Encontrada (404)

Sem ID de Sessão (400)

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

Notas Importantes

Casos de Uso

1. Atualizar Imagens Expiradas

2. Verificar Status Antes de Decisão Manual

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

Próximos Passos