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

# Mapeos de Campos

> Mapea los campos de tus datos al modelo de entidad gu1 con transformaciones — en el pipeline de ingestión de datos de gu1 con esquemas personalizados.

## Descripción General

Los Mapeos de Campos definen cómo se traducen los campos de tu esquema personalizado al modelo de entidad unificado de gu1. Cada mapeo puede incluir transformaciones para formatear, calcular o procesar datos condicionalmente durante la importación.

<Info>
  Los mapeos cierran la brecha entre tu estructura de datos y el modelo de entidad de gu1, permitiendo la ingesta de datos sin interrupciones desde cualquier fuente.
</Info>

## Crear Mapeo de Campos

Crea una configuración de mapeo para tu esquema personalizado.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://api.gu1.ai/custom-schemas/mappings \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "KYB Company Mapping",
      "description": "Maps company data to gu1 entity model",
      "sourceSchemaId": "550e8400-e29b-41d4-a716-446655440000",
      "targetSchemaType": "gueno_entity",
      "mappingData": {
        "mappings": [
          {
            "id": "1",
            "sourceField": "company_name",
            "targetField": "name",
            "transformation": {
              "type": "direct"
            },
            "required": true,
            "dataType": "string"
          },
          {
            "id": "2",
            "sourceField": "tax_id",
            "targetField": "external_id",
            "transformation": {
              "type": "format",
              "expression": "value.trim().toUpperCase()"
            },
            "required": true,
            "dataType": "string"
          },
          {
            "id": "3",
            "sourceField": "annual_revenue",
            "targetField": "entityData.revenue",
            "transformation": {
              "type": "calculate",
              "expression": "value * 1000"
            },
            "required": false,
            "dataType": "number"
          }
        ],
        "validation": {
          "strictMode": true,
          "allowExtraFields": false,
          "requiredFields": ["name", "external_id"]
        }
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://api.gu1.ai/custom-schemas/mappings', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'KYB Company Mapping',
      description: 'Maps company data to gu1 entity model',
      sourceSchemaId: '550e8400-e29b-41d4-a716-446655440000',
      targetSchemaType: 'gueno_entity',
      mappingData: {
        mappings: [
          {
            id: '1',
            sourceField: 'company_name',
            targetField: 'name',
            transformation: { type: 'direct' },
            required: true,
            dataType: 'string'
          }
        ],
        validation: {
          strictMode: true,
          allowExtraFields: false,
          requiredFields: ['name', 'external_id']
        }
      }
    })
  });
  ```
</CodeGroup>

### Cuerpo de la Solicitud

| Campo              | Tipo   | Requerido | Descripción                                       |
| ------------------ | ------ | --------- | ------------------------------------------------- |
| `name`             | string | Sí        | Nombre de la configuración de mapeo               |
| `description`      | string | No        | Descripción del mapeo                             |
| `sourceSchemaId`   | uuid   | No        | ID del esquema personalizado de origen            |
| `targetSchemaType` | string | No        | Tipo de esquema de destino (ej., "gueno\_entity") |
| `sourceSchemaName` | string | No        | Alternativa a sourceSchemaId                      |
| `targetSchemaName` | string | No        | Alternativa a targetSchemaType                    |
| `mappingData`      | object | Sí        | Configuración del mapeo                           |
| `industry`         | string | No        | Contexto de la industria                          |
| `collaborators`    | array  | No        | IDs de usuarios con acceso                        |

### Objeto de Datos de Mapeo

| Campo                    | Tipo   | Requerido | Descripción                    |
| ------------------------ | ------ | --------- | ------------------------------ |
| `mappings`               | array  | Sí        | Array de mapeos de campos      |
| `templates`              | array  | No        | IDs de plantillas a aplicar    |
| `validation`             | object | No        | Reglas de validación           |
| `transformationSettings` | object | No        | Configuración de procesamiento |

### Objeto de Mapeo de Campo

| Campo            | Tipo    | Requerido | Descripción                                              |
| ---------------- | ------- | --------- | -------------------------------------------------------- |
| `id`             | string  | Sí        | Identificador único del mapeo                            |
| `sourceField`    | string  | Sí        | Nombre del campo de origen                               |
| `targetField`    | string  | Sí        | Nombre del campo de destino (soporta notación de puntos) |
| `transformation` | object  | No        | Transformación a aplicar                                 |
| `required`       | boolean | Sí        | ¿El campo es requerido?                                  |
| `dataType`       | string  | Sí        | Tipo de dato esperado                                    |
| `defaultValue`   | any     | No        | Valor por defecto si el origen es nulo/faltante          |
| `validationRule` | string  | No        | Expresión de validación personalizada                    |

### Respuesta

```json theme={null}
{
  "success": true,
  "mapping": {
    "id": "map_abc123",
    "name": "KYB Company Mapping",
    "description": "Maps company data to gu1 entity model",
    "sourceSchemaId": "550e8400-e29b-41d4-a716-446655440000",
    "targetSchemaType": "gueno_entity",
    "organizationId": "org_xyz",
    "createdBy": "user_123",
    "createdAt": "2025-10-03T12:00:00Z",
    "updatedAt": "2025-10-03T12:00:00Z",
    "mappingData": {
      "mappings": [...],
      "validation": {...}
    }
  }
}
```

## Tipos de Transformación

### Mapeo Directo

Copia el valor tal cual sin cambios:

```json theme={null}
{
  "transformation": {
    "type": "direct"
  }
}
```

### Transformación de Formato

Aplica formato de cadena, fecha o número:

```json theme={null}
{
  "transformation": {
    "type": "format",
    "expression": "value.trim().toUpperCase()",
    "parameters": {
      "dateFormat": "ISO8601",
      "decimalPlaces": 2
    }
  }
}
```

**Ejemplos Comunes de Formato:**

```javascript theme={null}
// Recortar y convertir a mayúsculas
"value.trim().toUpperCase()"

// Formatear fecha
"new Date(value).toISOString()"

// Formatear moneda
"parseFloat(value).toFixed(2)"

// Limpiar número de teléfono
"value.replace(/[^0-9]/g, '')"
```

### Transformación de Cálculo

Realiza cálculos matemáticos:

```json theme={null}
{
  "transformation": {
    "type": "calculate",
    "expression": "value * 1000",
    "parameters": {
      "operator": "multiply",
      "operand": 1000
    }
  }
}
```

**Ejemplos Comunes de Cálculo:**

```javascript theme={null}
// Convertir miles al valor real
"value * 1000"

// Calcular porcentaje
"(value / total) * 100"

// Sumar múltiples campos
"sourceData.field1 + sourceData.field2"

// Cálculo de promedio
"(field1 + field2 + field3) / 3"
```

### Transformación Condicional

Aplica lógica if/then:

```json theme={null}
{
  "transformation": {
    "type": "conditional",
    "expression": "value > 1000000 ? 'high' : value > 100000 ? 'medium' : 'low'",
    "parameters": {
      "conditions": [
        {"if": "value > 1000000", "then": "high"},
        {"if": "value > 100000", "then": "medium"},
        {"else": "low"}
      ]
    }
  }
}
```

### Transformación de Búsqueda

Busca valores en tablas de referencia:

```json theme={null}
{
  "transformation": {
    "type": "lookup",
    "expression": "lookupTable[value] || 'unknown'",
    "parameters": {
      "lookupTable": {
        "US": "United States",
        "UK": "United Kingdom",
        "CA": "Canada"
      },
      "defaultValue": "unknown"
    }
  }
}
```

### Transformación Personalizada

Ejecuta JavaScript personalizado:

```json theme={null}
{
  "transformation": {
    "type": "custom",
    "expression": "const parts = value.split('-'); return parts[0].toUpperCase();",
    "parameters": {
      "allowedFunctions": ["split", "toUpperCase", "trim"]
    }
  }
}
```

<Warning>
  Las transformaciones personalizadas tienen restricciones de seguridad. Solo se permiten funciones JavaScript en la lista blanca.
</Warning>

## Reglas de Validación

Configura el comportamiento de validación:

```json theme={null}
{
  "validation": {
    "strictMode": true,
    "allowExtraFields": false,
    "requiredFields": ["name", "external_id", "country"]
  }
}
```

| Configuración      | Tipo    | Descripción                              |
| ------------------ | ------- | ---------------------------------------- |
| `strictMode`       | boolean | Falla ante cualquier error de validación |
| `allowExtraFields` | boolean | Permite campos de origen sin mapear      |
| `requiredFields`   | array   | Campos que deben tener valores           |

## Configuración de Transformación

Configura el comportamiento de procesamiento:

```json theme={null}
{
  "transformationSettings": {
    "errorHandling": "default",
    "batchSize": 100,
    "timeout": 30000
  }
}
```

| Configuración   | Tipo   | Descripción                      |
| --------------- | ------ | -------------------------------- |
| `errorHandling` | enum   | `skip`, `fail`, o `default`      |
| `batchSize`     | number | Registros por lote (1-1000)      |
| `timeout`       | number | Tiempo de espera en milisegundos |

## Listar Mapeos

Obtén todas las configuraciones de mapeo para tu organización:

```bash theme={null}
GET /custom-schemas/mappings
```

### Respuesta

```json theme={null}
{
  "success": true,
  "mappings": [
    {
      "id": "map_abc123",
      "name": "KYB Company Mapping",
      "sourceSchemaId": "550e8400-e29b-41d4-a716-446655440000",
      "targetSchemaType": "gueno_entity",
      "createdAt": "2025-10-03T12:00:00Z"
    }
  ]
}
```

## Obtener Mapeo

Recupera una configuración de mapeo específica:

```bash theme={null}
GET /custom-schemas/mappings/:id
```

### Respuesta

```json theme={null}
{
  "success": true,
  "mapping": {
    "id": "map_abc123",
    "name": "KYB Company Mapping",
    "description": "Maps company data to gu1 entity model",
    "mappingData": {
      "mappings": [...],
      "validation": {...}
    }
  }
}
```

## Actualizar Mapeo

Actualiza una configuración de mapeo existente:

```bash theme={null}
PATCH /custom-schemas/mappings/:id
```

### Cuerpo de la Solicitud

```json theme={null}
{
  "description": "Updated description",
  "mappingData": {
    "mappings": [
      {
        "id": "4",
        "sourceField": "new_field",
        "targetField": "entityData.newField",
        "transformation": { "type": "direct" },
        "required": false,
        "dataType": "string"
      }
    ]
  }
}
```

## Eliminar Mapeo

Elimina una configuración de mapeo:

```bash theme={null}
DELETE /custom-schemas/mappings/:id
```

## Ejemplo Completo: Mapeo de Cliente Bancario

```json theme={null}
{
  "name": "Banking Customer to Entity Mapping",
  "description": "Complete mapping for retail banking customers",
  "sourceSchemaId": "schema_banking_001",
  "targetSchemaType": "gueno_entity",
  "mappingData": {
    "mappings": [
      {
        "id": "1",
        "sourceField": "customer_id",
        "targetField": "external_id",
        "transformation": {
          "type": "format",
          "expression": "value.trim().toUpperCase()"
        },
        "required": true,
        "dataType": "string"
      },
      {
        "id": "2",
        "sourceField": "full_name",
        "targetField": "name",
        "transformation": { "type": "direct" },
        "required": true,
        "dataType": "string"
      },
      {
        "id": "3",
        "sourceField": "email",
        "targetField": "entityData.contact.email",
        "transformation": {
          "type": "format",
          "expression": "value.toLowerCase().trim()"
        },
        "required": true,
        "dataType": "string",
        "validationRule": "/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(value)"
      },
      {
        "id": "4",
        "sourceField": "account_balance",
        "targetField": "entityData.financial.balance",
        "transformation": {
          "type": "calculate",
          "expression": "Math.round(value * 100) / 100"
        },
        "required": false,
        "dataType": "number",
        "defaultValue": 0
      },
      {
        "id": "5",
        "sourceField": "account_balance",
        "targetField": "entityData.financial.balanceTier",
        "transformation": {
          "type": "conditional",
          "expression": "value > 100000 ? 'premium' : value > 10000 ? 'standard' : 'basic'"
        },
        "required": false,
        "dataType": "string"
      },
      {
        "id": "6",
        "sourceField": "country_code",
        "targetField": "country",
        "transformation": {
          "type": "lookup",
          "parameters": {
            "lookupTable": {
              "US": "United States",
              "UK": "United Kingdom",
              "CA": "Canada",
              "MX": "Mexico"
            },
            "defaultValue": "Unknown"
          }
        },
        "required": true,
        "dataType": "string"
      },
      {
        "id": "7",
        "sourceField": "risk_score",
        "targetField": "riskScore",
        "transformation": {
          "type": "calculate",
          "expression": "Math.min(Math.max(value, 0), 100)"
        },
        "required": false,
        "dataType": "number",
        "defaultValue": 0
      }
    ],
    "validation": {
      "strictMode": true,
      "allowExtraFields": false,
      "requiredFields": ["external_id", "name", "country"]
    },
    "transformationSettings": {
      "errorHandling": "default",
      "batchSize": 500,
      "timeout": 60000
    }
  }
}
```

## Respuestas de Error

### Error de Validación

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Mapping validation failed",
    "details": [
      {
        "mappingId": "3",
        "field": "email",
        "error": "Invalid email format"
      }
    ]
  }
}
```

### Error de Transformación

```json theme={null}
{
  "success": false,
  "error": {
    "code": "TRANSFORMATION_ERROR",
    "message": "Error applying transformation",
    "details": {
      "mappingId": "4",
      "sourceField": "account_balance",
      "error": "Cannot multiply undefined by 1000"
    }
  }
}
```

## Mejores Prácticas

<AccordionGroup>
  <Accordion icon="bolt" title="Comienza Simple">
    * Comienza con mapeos directos para la mayoría de los campos
    * Agrega transformaciones solo cuando sea necesario
    * Prueba cada transformación individualmente
    * Aumenta gradualmente la complejidad
  </Accordion>

  <Accordion icon="vial" title="Pruebas">
    * Prueba los mapeos con datos de muestra antes de producción
    * Valida casos extremos (valores nulos, vacíos, inválidos)
    * Monitorea errores de transformación en los registros
    * Usa strictMode en entornos de producción
  </Accordion>

  <Accordion icon="shield" title="Calidad de Datos">
    * Establece un defaultValue apropiado para campos opcionales
    * Usa validationRule para validaciones complejas
    * Aplica transformaciones de formato para consistencia
    * Maneja valores faltantes/nulos explícitamente
  </Accordion>

  <Accordion icon="gauge" title="Rendimiento">
    * Evita transformaciones personalizadas complejas en rutas críticas
    * Usa procesamiento por lotes para conjuntos de datos grandes
    * Establece valores de tiempo de espera razonables
    * Monitorea los tiempos de ejecución de transformaciones
  </Accordion>
</AccordionGroup>

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Detección Inteligente de Campos" icon="wand-magic-sparkles" href="/api-reference/data-ingestion/custom-schemas">
    Genera mapeos automáticamente desde datos de muestra
  </Card>

  <Card title="Importar Entidades" icon="upload" href="/api-reference/entities/create">
    Usa mapeos para importar datos de entidades
  </Card>

  <Card title="Guía de Mapeo de Datos" icon="book" href="/api-reference/data-ingestion/overview">
    Guía completa del flujo de trabajo
  </Card>

  <Card title="Guía de Transformaciones" icon="arrow-right-arrow-left" href="/api-reference/data-ingestion/field-mappings">
    Patrones avanzados de transformación
  </Card>
</CardGroup>