> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sincronizar Validación KYC

> Sincronizar manualmente los datos de validación KYC con el proveedor — en la API KYC de gu1 para flujos de verificación de identidad.

## 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

<Info>
  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.
</Info>

## 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

<ParamField path="id" type="string" required>
  El ID de la validación a sincronizar
</ParamField>

### Encabezados

```json theme={null}
{
  "Authorization": "Bearer TU_API_KEY",
  "Content-Type": "application/json"
}
```

### Parámetros del Cuerpo

<ParamField body="force" type="boolean">
  Forzar sincronización incluso si se sincronizó recientemente (opcional)

  **Tipo**: `boolean` (por defecto: `false`)

  **Ejemplo**: `true`
</ParamField>

## Respuesta

### Respuesta Exitosa (200 OK)

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

```json theme={null}
{
  "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

<CodeGroup>
  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  import requests

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

  response = requests.post(
      f'https://api.gu1.ai/api/kyc/validations/{validation_id}/sync',
      headers={
          'Authorization': 'Bearer TU_API_KEY',
          'Content-Type': 'application/json',
      },
      json={
          'force': False
      }
  )

  synced = response.json()
  print('Validación sincronizada:', synced['status'])
  print('Actualizada el:', synced['updatedAt'])
  ```

  ```curl cURL theme={null}
  curl -X POST https://api.gu1.ai/api/kyc/validations/550e8400-e29b-41d4-a716-446655440000/sync \
    -H "Authorization: Bearer TU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "force": false
    }'
  ```
</CodeGroup>

## Respuestas de Error

### Validación No Encontrada (404)

```json theme={null}
{
  "error": "NOT_FOUND",
  "message": "Validation not found"
}
```

### Sin ID de Sesión (400)

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

```json theme={null}
{
  "error": "NO_SESSION_ID",
  "message": "Validation has no session ID"
}
```

### Integración del Proveedor No Configurada (400)

```json theme={null}
{
  "error": "INTEGRATION_NOT_CONFIGURED",
  "message": "Integration not configured for organization: kyc_provider_code"
}
```

## Notas Importantes

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Casos de Uso

### 1. Refrescar Imágenes Expiradas

```javascript theme={null}
// 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

```javascript theme={null}
// 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

```javascript theme={null}
// 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

<CardGroup cols={2}>
  <Card title="Aprobar Validación" icon="check" href="/es/use-cases/kyc/approve-validation">
    Aprobar manualmente una validación
  </Card>

  <Card title="Rechazar Validación" icon="xmark" href="/es/use-cases/kyc/reject-validation">
    Rechazar manualmente una validación
  </Card>

  <Card title="Verificar Estado" icon="magnifying-glass" href="/es/use-cases/kyc/check-status">
    Consultar resultados de validación
  </Card>

  <Card title="Cancelar Validación" icon="ban" href="/es/use-cases/kyc/cancel-validation">
    Cancelar una validación pendiente
  </Card>
</CardGroup>