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

# Resumen de la API de KYC de gu1

> Resumen de la API de KYC de gu1: verifica la identidad de personas vía API, crea validaciones KYC, genera enlaces y consulta resultados desde el panel.

## ¿Qué es KYC (Conozca a Su Cliente)?

Know Your Customer (KYC) es el proceso de verificación de identidad de clientes individuales antes de establecer una relación comercial. La solución KYC de gu1 te permite integrar la verificación de identidad en tu aplicación, permitiendo que tus usuarios finales completen el proceso de verificación de manera fluida.

## Enfoque API-First

Nuestra API de KYC te permite:

* **Crear validaciones KYC programáticamente** para tus clientes
* **Generar URLs de verificación** para compartir con tus usuarios
* **Recibir notificaciones webhook en tiempo real** cuando la verificación se complete
* **Consultar el estado de validación** en cualquier momento

## Flujo de Integración Típico

<Steps>
  <Step title="Crear Entidad Persona">
    Crea una entidad persona en gu1 con la información básica de tu cliente
  </Step>

  <Step title="Iniciar Validación KYC">
    Llama a la API para crear una validación KYC y recibe una URL de verificación
  </Step>

  <Step title="Compartir URL con el Cliente">
    Envía la URL de verificación a tu cliente por email, SMS o intégrala en tu app
  </Step>

  <Step title="Cliente Completa la Verificación">
    Tu cliente sigue la URL y completa el proceso de verificación de identidad
  </Step>

  <Step title="Recibir Notificación Webhook">
    gu1 envía un webhook a tu sistema cuando la verificación está completa
  </Step>

  <Step title="Verificar Estado">
    Consulta la API para obtener los resultados finales de verificación y la decisión
  </Step>
</Steps>

<Info>
  **Webhooks vs Polling Manual**: Aunque los webhooks proporcionan notificaciones en tiempo real, también puedes verificar manualmente el estado de validación en cualquier momento usando `GET /api/kyc/validations/:id`. Esto es útil para:

  * Depuración o pruebas sin infraestructura de webhooks
  * Mostrar actualizaciones de estado a usuarios en tiempo real
  * Recuperarse de fallos en la entrega de webhooks
  * Construir dashboards de administración para monitorear el estado de validación
</Info>

## Características Principales

### KYC Completo vs Verificaciones Individuales

<Note>
  **¿Cuál deberías usar?**

  * **KYC Completo** (`global_gueno_validation_kyc`): Verificación completa de identidad incluyendo carga de documento, selfie, face matching y detección de vida. **Recomendado para servicios financieros, banca e industrias reguladas.**

  * **Verificaciones Individuales**: Llamadas API separadas para verificaciones específicas como screening PEP, verificación de sanciones o búsquedas de medios adversos. **Usa cuando solo necesitas puntos de datos específicos o ya tienes documentos de identidad verificados.**
</Note>

| Característica             | KYC Completo                   | Verificaciones Individuales   |
| -------------------------- | ------------------------------ | ----------------------------- |
| **Carga de Documento**     | ✅ Incluido                     | ❌ No incluido                 |
| **Selfie + Liveness**      | ✅ Incluido                     | ❌ No incluido                 |
| **Face Matching**          | ✅ Incluido                     | ❌ No incluido                 |
| **PEP/Sanciones**          | ✅ Incluido                     | ✅ Llamada API separada        |
| **Medios Adversos**        | Complemento opcional           | ✅ Llamada API separada        |
| **Experiencia de Usuario** | Flujo único para el usuario    | Sin interacción del usuario   |
| **Mejor Para**             | Apertura de cuenta, onboarding | Monitoreo continuo, screening |
| **Endpoint API**           | `POST /api/kyc/validations`    | `POST /entities/:id/analyze`  |

### Verificación Integral de Identidad (KYC Completo)

* **Validación de Documentos**: Autentica documentos de identidad emitidos por el gobierno
* **Verificación Biométrica**: Reconocimiento facial y detección de vida
* **Face Matching**: Compara selfie con la foto del documento (ver nota de seguridad abajo)
* **Screening AML/Sanciones**: Verifica contra listas de vigilancia global
* **Extracción de Datos**: Extrae y verifica información personal

<Warning>
  **Por Qué el Face Matching es Crítico para Bancos y Fintech**

  El face matching (comparar un selfie en vivo con la foto de un documento de identidad) es **esencial para instituciones financieras reguladas** porque:

  1. **Previene Robo de Identidad**: Confirma que la persona que presenta el documento es el propietario legítimo, no alguien usando una ID robada/falsa
  2. **Requisito Regulatorio**: La mayoría de reguladores financieros (FinCEN, FCA, FATF) exigen verificación biométrica para onboarding remoto
  3. **Prevención de Fraude**: Detecta ataques de presentación (sostener una foto impresa, ataques de repetición de video, deepfakes)
  4. **Detección de Vida**: Asegura que una persona real está presente, no una imagen estática o video
  5. **Pista de Auditoría**: Proporciona prueba verificable de identidad para investigaciones de cumplimiento

  **¿Cuándo se requiere face matching?**

  * ✅ Banca digital y neobancos
  * ✅ Exchanges y wallets de criptomonedas
  * ✅ Proveedores de servicios de pago (PSP)
  * ✅ Plataformas de préstamos y finanzas peer-to-peer
  * ✅ Cualquier servicio que transmita dinero o mantenga fondos de clientes

  **¿Cuándo puedes omitirlo?**

  * ❌ Marketplaces de bajo riesgo (no financieros)
  * ❌ Servicios donde verificas identidad en persona
  * ❌ Monitoreo continuo de clientes existentes (usa solo PEP/sanciones)

  Si no estás seguro de si tu caso de uso requiere face matching, consulta con tu equipo de cumplimiento o asesor legal.
</Warning>

### Procesamiento Automático de Documentos

* **Tecnología OCR**: Extrae automáticamente datos de documentos de identidad
* **Soporte Multi-idioma**: Procesa documentos en más de 100 idiomas
* **Autenticación de Documentos**: Detecta documentos falsos o alterados
* **Extracción de Datos**: Incorpora información verificada a tu sistema

### Webhooks en Tiempo Real

* **Notificaciones Instantáneas**: Recibe actualizaciones tan pronto como se complete la verificación
* **Cambios de Estado**: Notificaciones de aprobación, rechazo o revisión manual
* **Entrega Segura**: Firmas de webhook para validación de seguridad
* **Lógica de Reintentos**: Reintentos automáticos para entregas fallidas

### Listo para Cumplimiento

* **Cumplimiento AML/CFT**: Cumple con requisitos anti-lavado de dinero
* **Cumplimiento GDPR**: Estándares de protección de datos y privacidad
* **Registro de Auditoría**: Historial completo de intentos de verificación
* **Retención de Datos**: Políticas de retención configurables

## Casos de Uso

### Aplicaciones Fintech

* **Banca Digital**: Verifica usuarios durante la apertura de cuenta
* **Apps de Pago**: Cumple con regulaciones financieras
* **Plataformas de Préstamos**: Verifica identidad de prestatarios
* **Exchanges de Cripto**: Cumple requisitos KYC para traders

### Marketplaces y Plataformas

* **Plataformas P2P**: Verifica compradores y vendedores
* **Economía Compartida**: Valida proveedores de servicios
* **Economía Gig**: Incorpora freelancers y contratistas
* **Plataformas de Alquiler**: Verifica inquilinos y anfitriones

### Gaming y Apuestas

* **Verificación de Edad**: Confirma que usuarios son mayores de edad
* **Juego Responsable**: Implementa programas de autoexclusión
* **Cumplimiento Regulatorio**: Cumple requisitos de autoridades de juego
* **Prevención de Fraude**: Verifica identidad de jugadores

## Documentos Soportados

Nuestra solución KYC acepta varios documentos de identidad de un amplio conjunto de países que Gu1 puede habilitar para tu organización:

* Cédulas de identidad nacional
* Pasaportes
* Licencias de conducir
* Permisos de residencia
* Documentos emitidos por el gobierno

### Países que Gu1 puede habilitar para validación KYC

La cobertura documental depende del país emisor. Gu1 puede habilitar la validación KYC para los países siguientes (agrupados por continente). Contactá a Gu1 para activar el conjunto que coincida con tus mercados.

<AccordionGroup>
  <Accordion title="América del Norte, Centroamérica y Caribe">
    Anguilla; Antigua and Barbuda; Aruba; Bahamas; Barbados; Belize; Bermuda; Bonaire, Sint Eustatius and Saba; Canada; Cayman Islands; Costa Rica; Cuba; Curaçao; Dominica; Dominican Republic; El Salvador; Greenland; Grenada; Guatemala; Haiti; Honduras; Jamaica; Mexico; Montserrat; Nicaragua; Panama; Puerto Rico; Saint Kitts and Nevis; Saint Lucia; Saint Martin (French part); Saint Vincent and the Grenadines; Sint Maarten (Dutch part); Trinidad and Tobago; Turks and Caicos Islands; United States of America; Virgin Islands (British); Virgin Islands (U.S.)
  </Accordion>

  <Accordion title="América del Sur">
    Argentina; Bolivia; Brazil; Chile; Colombia; Ecuador; Falkland Islands (Malvinas); Guyana; Paraguay; Peru; Suriname; Uruguay; Venezuela
  </Accordion>

  <Accordion title="África">
    Algeria; Angola; Benin; Botswana; Burkina Faso; Burundi; Cameroon; Cape Verde; Central African Republic; Chad; Comoros; Côte d'Ivoire; Democratic Republic of the Congo; Djibouti; Egypt; Equatorial Guinea; Eritrea; Eswatini; Ethiopia; Gabon; Ghana; Guinea; Guinea-Bissau; Kenya; Lesotho; Liberia; Libya; Madagascar; Malawi; Mali; Mauritania; Mauritius; Morocco; Mozambique; Namibia; Niger; Nigeria; Republic of the Congo; The Gambia; Rwanda; Saint Helena; Sao Tome and Principe; Senegal; Seychelles; Sierra Leone; Somalia; South Africa; South Sudan; Sudan; Tanzania; Togo; Tunisia; Uganda; Western Sahara; Zambia; Zimbabwe
  </Accordion>

  <Accordion title="Asia">
    Abkhazia; Afghanistan; Armenia; Azerbaijan; Bahrain; Bangladesh; Bhutan; Brunei Darussalam; Cambodia; China; Christmas Island; Cocos (Keeling) Islands; Hong Kong; India; Indonesia; Iraq; Iran (Islamic Republic of); Israel; Japan; Jordan; Kazakhstan; Kuwait; Kyrgyzstan; Lao People's Democratic Republic; Lebanon; Macao; Malaysia; Maldives; Mongolia; Myanmar; Nepal; North Korea; Oman; Pakistan; Palestine; Philippines; Qatar; Russia; Saudi Arabia; Singapore; South Korea; Sri Lanka; Syrian Arab Republic; Taiwan; Tajikistan; Thailand; Timor-Leste; Turkey; Turkmenistan; United Arab Emirates; Uzbekistan; Vietnam; Yemen
  </Accordion>

  <Accordion title="Oceanía">
    American Samoa; Australia; Cook Islands; Fiji; French Polynesia; Guam; Kiribati; Marshall Islands; Micronesia (Federated States of); Nauru; New Caledonia; New Zealand; Niue; Northern Mariana Islands; Palau; Papua New Guinea; Samoa; Solomon Islands; Tonga; Tuvalu; Vanuatu
  </Accordion>
</AccordionGroup>

<Note>
  La disponibilidad de tipos de documento concretos (cédula, pasaporte, licencia de conducir, etc.) puede variar por país. Gu1 habilita el conjunto de países de tu organización en el onboarding o a pedido.
</Note>

## Comenzando

¿Listo para integrar verificación KYC en tu aplicación?

<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="Obtener URL de Verificación" icon="link" href="/es/use-cases/kyc/get-kyc-url">
    Obtener la URL para compartir con usuarios
  </Card>

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

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

## Resumen de Endpoints API

| Endpoint                               | Método | Descripción                                | Caso de Uso                                                |
| -------------------------------------- | ------ | ------------------------------------------ | ---------------------------------------------------------- |
| `/api/kyc/validations`                 | POST   | Crear una nueva validación KYC             | Iniciar proceso de verificación                            |
| `/api/kyc/validations/{id}`            | GET    | Obtener estado y detalles de validación    | **Polling manual** - verificar estado en cualquier momento |
| `/api/kyc/entities/{entityId}/current` | GET    | Obtener validación actual para una entidad | Recuperar validación activa                                |
| `/api/kyc/webhooks`                    | POST   | Recibir notificaciones webhook             | **Automático** - recibir notificación cuando se complete   |

<Tip>
  **Mejor Práctica**: Usa webhooks para producción para recibir notificaciones instantáneas, pero también implementa `GET /api/kyc/validations/{id}` como respaldo para:

  * Verificación inicial de estado después de la creación
  * Actualización iniciada por el usuario en tu UI
  * Recuperación de fallo de webhook
  * Herramientas de administración/soporte
</Tip>

## Próximos Pasos

1. [Crea tu primera validación KYC](/es/use-cases/kyc/create-validation)
2. [Aprende sobre integración de webhooks](/es/use-cases/kyc/webhook-integration)
3. [Obtén tus credenciales API](https://app.gu1.ai/org-api-keys)