Skip to main content
POST
http://api.gu1.ai
/
api
/
kyc
/
validations
/
{id}
/
sync
Sincronizar Validación 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
}'

​
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

​
id
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

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