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

# Página de Onboarding Alojada

> La forma más rápida de crear páginas de verificación de identidad optimizadas, alojadas en Gu1 — en la API KYC de gu1 para flujos de verificación de identidad.

## Descripción General

Nuestra solución alojada es una página segura y totalmente personalizable de KYC y verificación de identidad que te permite verificar a tus clientes rápidamente sin código. La página de onboarding alojada es la forma más rápida de comenzar con la verificación KYC.

<Info>
  **Diseño Mobile-Responsive**: La página alojada es completamente responsive y optimizada para todos los dispositivos (escritorio, tablet y móvil). Tus usuarios tendrán una experiencia de verificación fluida sin importar el dispositivo que usen.
</Info>

## Cómo Funciona

```mermaid theme={null}
sequenceDiagram
    participant Client as Tu Cliente
    participant YourApp as Tu Backend
    participant Gu1API as Gu1 API
    participant HostedPage as Página Alojada

    YourApp->>Gu1API: 1. Crear entidad persona (POST /api/entities)
    Gu1API-->>YourApp: ID de entidad

    YourApp->>Gu1API: 2. Crear validación KYC (POST /api/kyc/validations)
    Gu1API-->>YourApp: providerSessionUrl

    YourApp->>Client: 3. Enviar providerSessionUrl<br/>(Email, SMS, etc.)

    Client->>HostedPage: 4. Abrir providerSessionUrl
    HostedPage->>Client: Página de verificación personalizada

    Client->>HostedPage: 5. Subir documento y selfie
    HostedPage->>Gu1API: Procesar verificación

    Gu1API->>YourApp: 6. Webhook (aprobado/rechazado)
    YourApp->>YourApp: Actualizar estado del usuario

    Client->>HostedPage: Ver estado de finalización
```

## Parámetros de Personalización

Puedes personalizar la página de onboarding usando estos parámetros:

### Personalización de Marca y Visual

<ParamField path="domain" type="string">
  La página web puede alojarse en tu propio dominio
</ParamField>

<ParamField path="lang" type="string" default="en">
  El idioma predeterminado de la página. Valores soportados: `en`, `es`, `pt`
</ParamField>

<ParamField path="icon" type="string">
  El ícono de la página (favicon)
</ParamField>

<ParamField path="logo" type="string">
  El logo principal mostrado en la página
</ParamField>

### Personalización de Colores

Todos los parámetros de color aceptan códigos hexadecimales (ej., `#6366f1`):

<ParamField path="headersColor" type="string">
  Código hex para el color de los encabezados
</ParamField>

<ParamField path="paragraphsColor" type="string">
  Código hex para el color de los párrafos
</ParamField>

<ParamField path="supportTextsColor" type="string">
  Código hex para el color de los textos de soporte
</ParamField>

<ParamField path="backgroundColor" type="string">
  Código hex para el color de fondo
</ParamField>

<ParamField path="pillsColor" type="string">
  Código hex para el color de las píldoras
</ParamField>

<ParamField path="progressBarColor" type="string">
  Código hex para el color de la barra de progreso
</ParamField>

<ParamField path="primaryButtonColor" type="string">
  Código hex para el color del botón primario
</ParamField>

<ParamField path="secondaryButtonColor" type="string">
  Código hex para el color del botón secundario
</ParamField>

<ParamField path="selectorColor" type="string">
  Código hex para el color del selector
</ParamField>

<ParamField path="primaryButtonTextColor" type="string">
  Código hex para el color del texto del botón primario
</ParamField>

<ParamField path="secondaryButtonTextColor" type="string">
  Código hex para el color del texto del botón secundario
</ParamField>

<ParamField path="borderRadius" type="number">
  Radio del borde web. Número entre 0 y 50
</ParamField>

## Configuración de Reglas de Validación

Puedes personalizar las reglas de validación usando estos parámetros:

### Verificación de Edad

<ParamField path="Exclude By Age" type="number">
  Rechaza automáticamente todas las sesiones realizadas por usuarios menores de cierta edad. Número entre 1 y 100
</ParamField>

### Captura de Documentos

<ParamField path="Capture Method" type="string">
  Selecciona los métodos permitidos para las imágenes:

  * `Camera` - Solo captura con cámara
  * `Upload` - Solo carga de archivos
  * `Both` - Permitir ambos métodos
</ParamField>

### Detección de Duplicados

<ParamField path="Duplicated users" type="string">
  Cuando un usuario tiene documentos previamente aprobados de la misma aplicación, puedes establecer una regla automática:

  * `Approve` - Aprobar automáticamente
  * `Review` - Enviar a revisión manual
  * `Decline` - Rechazar automáticamente
</ParamField>

### Reglas de Validación de Documentos

<ParamField path="QR / barcode" type="string">
  Si se esperaba un código de barras o QR en el documento pero no se pudo leer, puedes establecer una regla automática:

  * `Approve` - Aprobar automáticamente
  * `Review` - Enviar a revisión manual
  * `Decline` - Rechazar automáticamente
</ParamField>

<ParamField path="MRZ not valid" type="string">
  Cuando se espera una Zona de Lectura Mecánica (MRZ) en el documento pero no se puede leer:

  * `Approve` - Aprobar automáticamente
  * `Review` - Enviar a revisión manual
  * `Decline` - Rechazar automáticamente
</ParamField>

<ParamField path="Expiration date" type="string">
  Cuando se espera la fecha de vencimiento del documento pero no se puede leer o está en un formato inválido:

  * `Approve` - Aprobar automáticamente
  * `Review` - Enviar a revisión manual
  * `Decline` - Rechazar automáticamente
</ParamField>

<ParamField path="Invalid validation" type="string">
  Este problema surge cuando no podemos validar una fecha, detectar un número de documento o reconocer con precisión el documento:

  * `Review` - Enviar a revisión manual
  * `Decline` - Rechazar automáticamente
</ParamField>

<ParamField path="Invalid document liveness" type="string">
  Este problema surge cuando no podemos validar la vivacidad del documento:

  * `Approve` - Aprobar automáticamente
  * `Review` - Enviar a revisión manual
  * `Decline` - Rechazar automáticamente
</ParamField>

<ParamField path="Address not processed" type="string">
  Este problema surge cuando la dirección en el documento no se pudo encontrar o geolocalizar, probablemente debido a una dirección inválida o faltante:

  * `Approve` - Aprobar automáticamente
  * `Review` - Enviar a revisión manual
  * `Decline` - Rechazar automáticamente
</ParamField>

<Note>
  Estos parámetros de validación deben ser comunicados al equipo de Gu1 a través de tu canal de soporte dedicado. Si necesitas hacer cambios o modificaciones a estos parámetros, por favor envía una solicitud a través de tu canal de soporte dedicado del cliente. En el futuro, estos parámetros serán editables en el panel de Gu1.
</Note>

## ¿Cómo Obtener la URL de la Página de Onboarding?

<Steps>
  <Step title="Crear una entidad persona">
    Crea una entidad de tipo persona en Gu1 con la API de Entidades (nombre, taxId, countryCode).

    [Aprende cómo crear una entidad →](/es/api-reference/entities/create)
  </Step>

  <Step title="Crear una validación KYC">
    Crea una sesión de validación KYC para esa entidad con `POST /api/kyc/validations` usando el ID de la entidad y `integrationCode` (ej. `global_gueno_validation_kyc`).

    [Aprende cómo crear una validación →](/es/use-cases/kyc/create-validation)
  </Step>

  <Step title="Obtener el providerSessionUrl">
    Recupera el `providerSessionUrl` de la respuesta de la validación. Es la URL de la página alojada que compartes con tu cliente.
  </Step>

  <Step title="Compartir con tu cliente">
    Comparte el `providerSessionUrl` con tu cliente por correo, SMS o incrustado en tu aplicación.
  </Step>
</Steps>

## Ejemplo de Implementación

<CodeGroup>
  ```javascript Node.js theme={null}
  // 1. Crear una entidad persona (API de Entidades)
  const entityRes = await fetch('https://api.gu1.ai/api/entities', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer TU_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'person',
      name: 'Juan Pérez',
      taxId: '12345678900',
      countryCode: 'AR',
      entityData: { person: { email: 'juan@ejemplo.com' } }
    })
  });
  const entityData = await entityRes.json();
  const entityId = entityData.entity?.id ?? entityData.id;

  // 2. Crear una sesión de validación KYC
  const validationRes = await fetch('https://api.gu1.ai/api/kyc/validations', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer TU_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityId,
      integrationCode: 'global_gueno_validation_kyc'
    })
  });
  const validationData = await validationRes.json();

  // 3. Obtener la URL de la página alojada (providerSessionUrl)
  const hostedPageUrl = validationData.providerSessionUrl;
  console.log('Comparte esta URL con tu cliente:', hostedPageUrl);

  // 4. Compartir con el cliente (por correo, SMS, etc.)
  await sendEmail({
    to: 'juan@ejemplo.com',
    subject: 'Completa tu Verificación de Identidad',
    body: `Por favor completa tu verificación aquí: ${hostedPageUrl}`
  });
  ```

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

  # 1. Crear una entidad persona (API de Entidades)
  entity_response = requests.post(
      'https://api.gu1.ai/api/entities',
      headers={
          'Authorization': 'Bearer TU_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'type': 'person',
          'name': 'Juan Pérez',
          'taxId': '12345678900',
          'countryCode': 'AR',
          'entityData': { 'person': { 'email': 'juan@ejemplo.com' } }
      }
  )
  entity_data = entity_response.json()
  entity_id = entity_data.get('entity', {}).get('id') or entity_data.get('id')

  # 2. Crear una sesión de validación KYC
  validation_response = requests.post(
      'https://api.gu1.ai/api/kyc/validations',
      headers={
          'Authorization': 'Bearer TU_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'entityId': entity_id,
          'integrationCode': 'global_gueno_validation_kyc'
      }
  )
  validation_data = validation_response.json()

  # 3. Obtener la URL de la página alojada (providerSessionUrl)
  hosted_page_url = validation_data['providerSessionUrl']
  print('Comparte esta URL con tu cliente:', hosted_page_url)

  # 4. Compartir con el cliente (por correo, SMS, etc.)
  send_email(
      to='juan@ejemplo.com',
      subject='Completa tu Verificación de Identidad',
      body=f'Por favor completa tu verificación aquí: {hosted_page_url}'
  )
  ```

  ```curl cURL theme={null}
  # 1. Crear una entidad persona (API de Entidades)
  curl -X POST https://api.gu1.ai/api/entities \
    -H "Authorization: Bearer TU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "person",
      "name": "Juan Pérez",
      "taxId": "12345678900",
      "countryCode": "AR"
    }'

  # Respuesta: {"entity": {"id": "entity-uuid", ...}, ...} o {"id": "entity-uuid", ...}

  # 2. Crear una sesión de validación KYC
  curl -X POST https://api.gu1.ai/api/kyc/validations \
    -H "Authorization: Bearer TU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityId": "entity-uuid",
      "integrationCode": "global_gueno_validation_kyc"
    }'

  # Respuesta: {"id": "...", "providerSessionUrl": "https://...", "status": "pending", ...}

  # 3. Compartir el providerSessionUrl con tu cliente
  ```
</CodeGroup>

## Mejores Prácticas

<AccordionGroup>
  <Accordion title="Personaliza para tu Marca">
    Configura el esquema de colores, logo e idioma para que coincida con la identidad de tu marca. Esto crea una experiencia fluida para tus usuarios.
  </Accordion>

  <Accordion title="Establece Reglas de Validación Apropiadas">
    Configura las reglas de validación basándote en tus requisitos de cumplimiento y tolerancia al riesgo. Reglas más estrictas proporcionan mejor seguridad pero pueden resultar en más revisiones manuales.
  </Accordion>

  <Accordion title="Monitorea el Estado de la Sesión">
    Usa webhooks para recibir notificaciones en tiempo real cuando se complete la verificación. Esto te permite actualizar inmediatamente el acceso del usuario en tu sistema.
  </Accordion>

  <Accordion title="Maneja la Expiración y Seguridad">
    **Expiración de Sesiones**: Las sesiones típicamente expiran después de 7 días. Si la sesión de un usuario expira, crea una nueva validación para generar una URL nueva.

    **Mejores Prácticas de Seguridad**:

    * Nunca expongas el providerSessionUrl públicamente (no lo compartas en foros públicos, URLs públicas, etc.)
    * Siempre genera URLs del lado del servidor - nunca expongas las API keys en código del lado del cliente
    * Usa HTTPS cuando compartas URLs a través de tus propios sistemas
    * Implementa autenticación adecuada antes de generar sesiones para usuarios
    * Considera implementar rate limiting en la creación de sesiones para prevenir abuso
    * Almacena los IDs de validación en tu base de datos vinculados a registros de usuarios para trazabilidad de auditoría
  </Accordion>
</AccordionGroup>

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Crear Entidad" icon="user" href="/es/api-reference/entities/create">
    Aprende cómo crear una entidad de persona
  </Card>

  <Card title="Crear Validación" icon="shield-check" href="/es/use-cases/kyc/create-validation">
    Crea una sesión de validación KYC
  </Card>

  <Card title="Integración de Webhooks" icon="webhook" href="/es/use-cases/kyc/webhook-integration">
    Recibe actualizaciones de estado en tiempo real
  </Card>

  <Card title="Integración de Cliente" icon="code" href="/es/use-cases/kyc/client-integration">
    Incrusta en tu aplicación móvil o web
  </Card>
</CardGroup>