Sincronizar Validación KYC

Descripción General

Este endpoint te permite sincronizar manualmente una validación KYC con el proveedor de verificación para obtener el estado y los datos de decisión más recientes. Cuando sincronizas:

Obtiene los datos más recientes del proveedor KYC en tiempo real
Refresca las URLs de imágenes expiradas (las URLs del proveedor expiran después de ~4 horas)
Actualiza el estado de la validación si el proveedor ha tomado una decisión
Preserva las decisiones manuales - no sobrescribe validaciones aprobadas/rechazadas/canceladas manualmente
Retorna datos de verificación actualizados incluyendo documentos, biometría y evaluación de riesgo

La sincronización es útil cuando necesitas datos frescos inmediatamente sin esperar webhooks, o cuando las URLs de imágenes han expirado y necesitas ver los documentos de verificación.

Cuándo Usar Esto

Verificar estado actual: Obtener actualizaciones de estado en tiempo real del proveedor
Refrescar imágenes expiradas: Las URLs de imágenes del proveedor expiran después de 4 horas
Forzar actualización: Activar manualmente una sincronización si falló la entrega del webhook
Depurar verificación: Revisar los datos y decisiones de verificación más recientes
Antes de decisión manual: Sincronizar antes de aprobar/rechazar para ver los datos más recientes del proveedor

Solicitud

Endpoint

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

Parámetros de Ruta

string

required

El ID de la validación a sincronizar

Encabezados

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

Parámetros del Cuerpo

force

boolean

Forzar sincronización incluso si se sincronizó recientemente (opcional)Tipo: boolean (por defecto: false)Ejemplo: true

Respuesta

Respuesta Exitosa (200 OK)

Retorna el objeto de validación actualizado con los últimos datos del proveedor:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entityId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "org_abc123",
  "validationSessionId": "session_xyz789",
  "status": "approved",
  "provider": "Proveedor 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": "Juan",
      "last_name": "Pérez",
      "date_of_birth": "1990-05-15",
      "nationality": "ES",
      "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": "Juan",
    "lastName": "Pérez",
    "dateOfBirth": "1990-05-15",
    "nationality": "ES",
    "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"
}

Ejemplo de Solicitud

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 TU_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      force: false
    })
  }
);

const synced = await response.json();
console.log('Validación sincronizada:', synced.status);
console.log('Actualizada el:', synced.updatedAt);

Respuestas de Error

Validación No Encontrada (404)

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

Sin ID de Sesión (400)

La validación no tiene sesión del proveedor para sincronizar:

{
  "error": "NO_SESSION_ID",
  "message": "Validation has no session ID"
}

Integración del Proveedor No Configurada (400)

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

Notas Importantes

Sincronización Automática

Las validaciones se sincronizan automáticamente al consultarlas vía GET si las imágenes tienen más de 3.5 horas. La sincronización manual es útil cuando necesitas actualizaciones inmediatas.

Las Decisiones Manuales Están Protegidas

Si una validación fue aprobada, rechazada o cancelada manualmente, la sincronización NO sobrescribirá esa decisión. Las decisiones manuales se preservan para mantener trazabilidad de auditoría.

Refresco de URLs de Imágenes

Las URLs de imágenes del proveedor (fotos de documentos, selfies) expiran después de ~4 horas. La sincronización obtiene URLs frescas para que puedas ver los documentos nuevamente.

Actualización de Estado

Si el proveedor ha tomado una decisión desde la última sincronización, el estado de la validación se actualizará automáticamente (a menos que tenga un estado manual).

Cargo de Créditos

La sincronización NO cobra créditos. Los créditos solo se cobran cuando una validación alcanza un estado final (aprobada/rechazada) por primera vez.

Casos de Uso

1. Refrescar Imágenes Expiradas

// El usuario quiere revisar documentos pero las imágenes expiraron
const validation = await fetch(
  `https://api.gu1.ai/api/kyc/validations/${validationId}/sync`,
  {
    method: 'POST',
    headers: { 'Authorization': 'Bearer TU_API_KEY' }
  }
);

const data = await validation.json();
// URLs de imágenes frescas disponibles en data.decision.id_verification.front_image

2. Verificar Estado Antes de Decisión Manual

// Sincronizar antes de tomar una decisión de aprobación manual
const synced = await fetch(
  `https://api.gu1.ai/api/kyc/validations/${validationId}/sync`,
  { method: 'POST', headers: { 'Authorization': 'Bearer TU_API_KEY' } }
);

const data = await synced.json();

// Revisar datos más recientes del proveedor
console.log('Estado del proveedor:', data.status);
console.log('Nivel de riesgo:', data.riskAssessment?.riskLevel);
console.log('Advertencias:', data.warnings);

// Luego aprobar si está satisfecho
if (data.status === 'in_progress' && data.warnings.length === 0) {
  await approveValidation(validationId, 'Todas las verificaciones pasaron');
}

3. Forzar Actualización Después de Falla de Webhook

// Si sospechas que los webhooks no se entregaron
const validations = await getValidationsWithStatus('in_progress');

for (const validation of validations) {
  // Sincronizar cada una para obtener el estado más reciente
  await fetch(
    `https://api.gu1.ai/api/kyc/validations/${validation.id}/sync`,
    {
      method: 'POST',
      headers: { 'Authorization': 'Bearer TU_API_KEY' },
      body: JSON.stringify({ force: true })
    }
  );
}

Próximos Pasos

Aprobar Validación

Aprobar manualmente una validación

Rechazar Validación

Rechazar manualmente una validación

Verificar Estado

Consultar resultados de validación

Cancelar Validación

Cancelar una validación pendiente

​Descripción General

​Cuándo Usar Esto

​Solicitud

​Endpoint

​Parámetros de Ruta

​Encabezados

​Parámetros del Cuerpo

​Respuesta

​Respuesta Exitosa (200 OK)

​Ejemplo de Solicitud

​Respuestas de Error

​Validación No Encontrada (404)

​Sin ID de Sesión (400)

​Integración del Proveedor No Configurada (400)

​Notas Importantes

​Casos de Uso

​1. Refrescar Imágenes Expiradas

​2. Verificar Estado Antes de Decisión Manual

​3. Forzar Actualización Después de Falla de Webhook

​Próximos Pasos

Aprobar Validación

Rechazar Validación

Verificar Estado

Cancelar Validación

Descripción General

Cuándo Usar Esto

Solicitud

Endpoint

Parámetros de Ruta

Encabezados

Parámetros del Cuerpo

Respuesta

Respuesta Exitosa (200 OK)

Ejemplo de Solicitud

Respuestas de Error

Validación No Encontrada (404)

Sin ID de Sesión (400)

Integración del Proveedor No Configurada (400)

Notas Importantes

Casos de Uso

1. Refrescar Imágenes Expiradas

2. Verificar Estado Antes de Decisión Manual

3. Forzar Actualización Después de Falla de Webhook

Próximos Pasos