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

# Cancelar Validación KYC

> Cancelar una validación KYC pendiente, en progreso o en revisión — en la API KYC de gu1 para flujos de verificación de identidad, con ejemplos para cancel.

## Resumen

Este endpoint te permite cancelar una validación KYC que está en estado `pending`, `in_progress` o `in_review`. Cuando se cancela:

* El estado de la validación cambia a `cancelled`
* La sesión del proveedor se termina (el usuario ya no puede acceder a la URL de verificación)
* La validación se marca como no actual (`isCurrent: false`)
* Puedes crear una nueva validación para la misma entidad después

<Warning>
  Esta acción no se puede deshacer. El usuario necesitará iniciar un nuevo proceso de validación si aún necesita verificar su identidad.
</Warning>

## Cuándo Usar Esto

* **Cancelación solicitada por el usuario**: El cliente ya no quiere completar la verificación
* **Datos incorrectos**: La información de la entidad fue ingresada incorrectamente
* **Validación duplicada**: La validación fue creada por error
* **Necesidad de reiniciar el proceso**: Se necesita empezar de cero con una nueva sesión de verificación

## Solicitud

### Endpoint

```
DELETE https://api.gu1.ai/api/kyc/validations/{id}/cancel
```

### Parámetros de Ruta

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

### Headers

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

### Parámetros del Body

<ParamField body="reason" type="string" required>
  Razón para cancelar la validación (mínimo 5 caracteres)

  **Tipo**: `string` (longitud mínima: 5)

  **Ejemplo**: `"Usuario solicitó cancelar el proceso de verificación"`
</ParamField>

## Respuesta

### Respuesta Exitosa (200 OK)

Retorna el objeto de validación actualizado con estado `cancelled`:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entityId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "org_abc123",
  "validationSessionId": "session_xyz789",
  "status": "cancelled",
  "provider": "kyc_provider",
  "providerSessionUrl": "https://verify.example.com/session_xyz789",
  "isCurrent": false,
  "metadata": {
    "cancelledBy": "user_123",
    "cancelledAt": "2025-01-27T10:30:00Z",
    "cancellationReason": "Usuario solicitó cancelar el proceso de verificación"
  },
  "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}/cancel`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        reason: 'Usuario solicitó cancelar el proceso de verificación'
      })
    }
  );

  const cancelled = await response.json();
  console.log('Validación cancelada:', cancelled.status);
  ```

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

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

  response = requests.delete(
      f'https://api.gu1.ai/api/kyc/validations/{validation_id}/cancel',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json',
      },
      json={
          'reason': 'Usuario solicitó cancelar el proceso de verificación'
      }
  )

  cancelled = response.json()
  print('Validación cancelada:', cancelled['status'])
  ```

  ```curl cURL theme={null}
  curl -X DELETE https://api.gu1.ai/api/kyc/validations/550e8400-e29b-41d4-a716-446655440000/cancel \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "reason": "Usuario solicitó cancelar el proceso de verificación"
    }'
  ```
</CodeGroup>

## Respuestas de Error

### Validación No Encontrada (404)

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

### Estado Inválido (400)

La validación solo puede cancelarse si el estado es `pending`, `in_progress` o `in_review`:

```json theme={null}
{
  "error": "INVALID_STATUS",
  "message": "Cannot cancel validation with status 'approved'. Only 'pending', 'in_progress', or 'in_review' validations can be cancelled."
}
```

### Razón Inválida (400)

La razón debe tener al menos 5 caracteres:

```json theme={null}
{
  "error": "VALIDATION_ERROR",
  "message": "Reason must be at least 5 characters"
}
```

## Notas Importantes

<AccordionGroup>
  <Accordion title="La Sesión se Elimina del Proveedor">
    Cuando cancelas una validación, intentamos eliminar la sesión del proveedor de KYC. La URL de verificación ya no funcionará para el usuario.
  </Accordion>

  <Accordion title="Registro de Auditoría">
    La razón de cancelación se guarda en los metadatos de la validación y en los registros de auditoría. Esto ayuda a mantener el cumplimiento y rastrear por qué se cancelaron las validaciones.
  </Accordion>

  <Accordion title="No Se Pueden Cancelar Validaciones Completadas">
    No puedes cancelar validaciones que ya están `approved`, `rejected`, `expired`, `abandoned` o `cancelled`. Solo las validaciones `pending`, `in_progress` o `in_review` pueden cancelarse.
  </Accordion>

  <Accordion title="Crear Nueva Validación Después de la Cancelación">
    Después de cancelar, puedes crear una nueva validación KYC para la misma entidad. La validación anterior permanecerá en el historial con estado `cancelled`.
  </Accordion>
</AccordionGroup>

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Crear Validación KYC" icon="play" href="/es/use-cases/kyc/create-validation">
    Iniciar una nueva sesión de verificación
  </Card>

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