> ## 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 Ingesta de Datos

> Aprende a mapear e importar tus datos en gu1 usando esquemas personalizados y mapeos de campos — en el pipeline de ingestión de datos de gu1 con esquemas.

## ¿Qué es la Ingesta de Datos?

El sistema de Ingesta de Datos de gu1 te permite importar datos sin problemas desde cualquier fuente (archivos CSV, APIs, bases de datos o formatos personalizados) definiendo esquemas personalizados y mapeos de campos. Este sistema de mapeo inteligente asegura que tus datos estén estructurados correctamente para el análisis de riesgo.

## Cómo Funciona

<Steps>
  <Step title="Define tu Esquema">
    Crea un esquema personalizado que describa la estructura de tus datos con definiciones de campos, tipos y reglas de validación.
  </Step>

  <Step title="Mapea Campos">
    Crea mapeos de campos que traduzcan tus campos de datos al modelo de entidad unificado de gu1.
  </Step>

  <Step title="Transforma Datos">
    Aplica transformaciones (formato, cálculos, condicionales) mientras los datos fluyen a través del mapeo.
  </Step>

  <Step title="Importa Entidades">
    Usa el esquema mapeado para crear entidades vía API o carga masiva.
  </Step>
</Steps>

## Características Clave

<CardGroup cols={2}>
  <Card title="Esquemas Personalizados" icon="table" href="/api-reference/data-ingestion/custom-schemas">
    Define la estructura de tus datos con tipos de campo flexibles y validación
  </Card>

  <Card title="Mapeos de Campos" icon="arrows-left-right" href="/api-reference/data-ingestion/field-mappings">
    Mapea tus campos al modelo unificado de gu1 con transformaciones
  </Card>

  <Card title="Detección Inteligente" icon="wand-magic-sparkles" href="/api-reference/data-ingestion/custom-schemas">
    Detecta automáticamente tipos de campo, patrones y mapeos sugeridos
  </Card>

  <Card title="Procesamiento Masivo" icon="layer-group" href="/en/api-reference/bulk-imports/overview">
    Importa miles de registros eficientemente con procesamiento por lotes
  </Card>
</CardGroup>

## Tipos de Esquema

gu1 soporta múltiples tipos de esquema para diferentes fuentes de datos:

| Tipo         | Descripción                          | Caso de Uso                           |
| ------------ | ------------------------------------ | ------------------------------------- |
| **database** | Esquemas de base de datos relacional | Integración directa con base de datos |
| **api**      | Estructuras de respuesta de API      | Integración con APIs de terceros      |
| **file**     | Formatos de archivo (CSV, JSON, XML) | Importaciones basadas en archivos     |
| **custom**   | Estructuras de datos personalizadas  | Formatos propietarios                 |

## Categorías de Esquema

Organiza esquemas por dominio de negocio:

<AccordionGroup>
  <Accordion icon="chart-line" title="Financiero">
    Cuentas bancarias, transacciones, estados financieros, datos de pago
  </Accordion>

  <Accordion icon="id-card" title="Identidad">
    Información personal, documentos de identidad, datos KYC
  </Accordion>

  <Accordion icon="shield-check" title="Cumplimiento">
    Listas de sanciones, PEPs, medios adversos, datos regulatorios
  </Accordion>

  <Accordion icon="money-bill-transfer" title="Transaccional">
    Transacciones de pago, transferencias bancarias, historial de transacciones
  </Accordion>

  <Accordion icon="folder" title="General">
    Cualquier otro tipo de datos estructurados
  </Accordion>
</AccordionGroup>

## Tipos de Campo

Tipos de campo soportados para la definición de esquemas:

| Tipo        | Descripción           | Ejemplo                                                    |
| ----------- | --------------------- | ---------------------------------------------------------- |
| **string**  | Datos de texto        | "Acme Corp", "[john@example.com](mailto:john@example.com)" |
| **number**  | Valores numéricos     | 1000, 99.99, -50                                           |
| **boolean** | Verdadero/falso       | true, false                                                |
| **date**    | Fecha/marca de tiempo | "2025-10-03T12:00:00Z"                                     |
| **array**   | Lista de valores      | \["tag1", "tag2"]                                          |
| **object**  | Estructura anidada    | `{"city": "NYC", "country": "US"}`                         |

## Tipos de Transformación

Aplica transformaciones durante el mapeo de campos:

<CardGroup cols={3}>
  <Card title="Directo" icon="arrow-right">
    Copia el campo tal cual sin cambios
  </Card>

  <Card title="Calcular" icon="calculator">
    Realiza cálculos matemáticos
  </Card>

  <Card title="Formatear" icon="text">
    Formatea cadenas, fechas, números
  </Card>

  <Card title="Condicional" icon="code-branch">
    Aplica lógica if/then basada en condiciones
  </Card>

  <Card title="Búsqueda" icon="magnifying-glass">
    Busca valores en tablas de referencia
  </Card>

  <Card title="Personalizado" icon="code">
    Expresiones JavaScript personalizadas
  </Card>
</CardGroup>

## Reglas de Validación

Asegura la calidad de datos con validaciones integradas:

```json theme={null}
{
  "constraints": {
    "minLength": 5,
    "maxLength": 100,
    "pattern": "^[A-Z0-9]+$",
    "enum": ["active", "inactive", "pending"]
  }
}
```

**Restricciones Disponibles:**

* `minLength` / `maxLength` - Límites de longitud de cadena
* `min` / `max` - Rangos de valores numéricos
* `pattern` - Validación de expresión regular
* `enum` - Lista de valores permitidos
* `required` - Campo obligatorio

## Ejemplo: Esquema de Datos Bancarios

Aquí hay un ejemplo completo de definición de un esquema para datos de clientes bancarios:

```json theme={null}
{
  "name": "Banking Customer Data",
  "version": "1.0.0",
  "type": "database",
  "category": "financial",
  "schemaData": {
    "fields": [
      {
        "name": "customer_id",
        "type": "string",
        "required": true,
        "description": "Unique customer identifier",
        "constraints": {
          "pattern": "^CUST[0-9]{8}$"
        }
      },
      {
        "name": "full_name",
        "type": "string",
        "required": true,
        "description": "Customer full legal name",
        "constraints": {
          "minLength": 2,
          "maxLength": 200
        }
      },
      {
        "name": "account_balance",
        "type": "number",
        "required": false,
        "description": "Current account balance in USD",
        "constraints": {
          "min": 0
        }
      },
      {
        "name": "risk_level",
        "type": "string",
        "required": true,
        "description": "Risk classification",
        "constraints": {
          "enum": ["low", "medium", "high", "critical"]
        }
      },
      {
        "name": "onboarding_date",
        "type": "date",
        "required": true,
        "description": "Date customer was onboarded"
      },
      {
        "name": "kyc_verified",
        "type": "boolean",
        "required": true,
        "description": "Whether KYC verification is complete"
      }
    ],
    "metadata": {
      "sourceFormat": "database",
      "encoding": "UTF-8"
    }
  }
}
```

## Mejores Prácticas

<AccordionGroup>
  <Accordion icon="lightbulb" title="Diseño de Esquema">
    * Usa nombres de campo descriptivos que coincidan con tus datos de origen
    * Incluye descripciones detalladas para campos complejos
    * Establece restricciones de validación apropiadas
    * Versiona tus esquemas (1.0.0, 1.1.0, etc.)
  </Accordion>

  <Accordion icon="arrows-spin" title="Mapeo de Campos">
    * Comienza con mapeos directos, agrega transformaciones según sea necesario
    * Prueba los mapeos con datos de muestra antes de la importación masiva
    * Documenta la lógica de transformación personalizada
    * Maneja valores nulos/faltantes con elegancia
  </Accordion>

  <Accordion icon="shield" title="Calidad de Datos">
    * Valida los datos en el origen antes de importar
    * Usa modo estricto para entornos de producción
    * Monitorea importaciones fallidas y errores de validación
    * Implementa limpieza de datos para problemas conocidos
  </Accordion>

  <Accordion icon="gauge-high" title="Rendimiento">
    * Usa procesamiento masivo para conjuntos de datos grandes (>1000 registros)
    * Establece tamaños de lote apropiados (100-1000 registros)
    * Programa las importaciones durante horas de menor actividad
    * Monitorea tiempos de procesamiento y ajusta tamaños de lote
  </Accordion>
</AccordionGroup>

## Casos de Uso Comunes

<CardGroup cols={2}>
  <Card title="Importación de Archivo CSV" icon="file-csv" href="/csv-import-guide">
    Importa datos de clientes desde archivos CSV con detección automática de campos
  </Card>

  <Card title="Integración de API" icon="plug" href="/api-reference/data-ingestion/overview">
    Conecta APIs de terceros y sincroniza datos en tiempo real
  </Card>

  <Card title="Sincronización de Base de Datos" icon="database" href="/DATABASE_SYNC_GUIDE">
    Sincroniza datos desde tus bases de datos existentes
  </Card>

  <Card title="Onboarding Bancario" icon="building-columns" href="/use-cases/kyb/example">
    Flujo de trabajo KYB completo con ejemplo de mapeo de datos
  </Card>
</CardGroup>

## Endpoints de API

<CardGroup cols={2}>
  <Card title="Crear Esquema" icon="plus" href="/api-reference/data-ingestion/custom-schemas#create-schema">
    POST /custom-schemas
  </Card>

  <Card title="Listar Esquemas" icon="list" href="/api-reference/data-ingestion/custom-schemas#list-schemas">
    GET /custom-schemas
  </Card>

  <Card title="Crear Mapeo" icon="plus" href="/api-reference/data-ingestion/field-mappings#create-mapping">
    POST /custom-schemas/mappings
  </Card>

  <Card title="Detección Inteligente" icon="wand-magic-sparkles" href="/api-reference/data-ingestion/custom-schemas">
    POST /custom-schemas/detect-fields
  </Card>
</CardGroup>

## Próximos Pasos

<Steps>
  <Step title="Crea tu Primer Esquema">
    Sigue la [guía de Esquemas Personalizados](/api-reference/data-ingestion/custom-schemas) para definir la estructura de tus datos
  </Step>

  <Step title="Mapea tus Campos">
    Aprende cómo mapear campos al modelo de gu1 en la [guía de Mapeos de Campos](/api-reference/data-ingestion/field-mappings)
  </Step>

  <Step title="Importa Datos">
    Comienza a importar entidades usando la [API de Entidades](/api-reference/entities/create)
  </Step>
</Steps>