Mapeos de Campos

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.

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.

Crear Mapeo de Campos

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

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"]
      }
    }
  }'

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

{
  "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:

{
  "transformation": {
    "type": "direct"
  }
}

Transformación de Formato

Aplica formato de cadena, fecha o número:

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

Ejemplos Comunes de Formato:

// 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:

{
  "transformation": {
    "type": "calculate",
    "expression": "value * 1000",
    "parameters": {
      "operator": "multiply",
      "operand": 1000
    }
  }
}

Ejemplos Comunes de Cálculo:

// 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:

{
  "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:

{
  "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:

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

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

Reglas de Validación

Configura el comportamiento de validación:

{
  "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:

{
  "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:

GET /custom-schemas/mappings

Respuesta

{
  "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:

GET /custom-schemas/mappings/:id

Respuesta

{
  "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:

PATCH /custom-schemas/mappings/:id

Cuerpo de la Solicitud

{
  "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:

DELETE /custom-schemas/mappings/:id

Ejemplo Completo: Mapeo de Cliente Bancario

{
  "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

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

Error de Transformación

{
  "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

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

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

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

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

Próximos Pasos

Detección Inteligente de Campos

Genera mapeos automáticamente desde datos de muestra

Importar Entidades

Usa mapeos para importar datos de entidades

Guía de Mapeo de Datos

Guía completa del flujo de trabajo

Guía de Transformaciones

Patrones avanzados de transformación

Comenzando

Referencia API

Ingesta de Datos

Entidades

Documentos

Conozca Su Negocio (KYB)

Conozca Su Cliente (KYC)

Monitoreo de Transacciones

Tutoriales Interactivos

​Descripción General

​Crear Mapeo de Campos

​Cuerpo de la Solicitud

​Objeto de Datos de Mapeo

​Objeto de Mapeo de Campo

​Respuesta

​Tipos de Transformación

​Mapeo Directo

​Transformación de Formato

​Transformación de Cálculo

​Transformación Condicional

​Transformación de Búsqueda

​Transformación Personalizada

​Reglas de Validación

​Configuración de Transformación

​Listar Mapeos

​Respuesta

​Obtener Mapeo

​Respuesta

​Actualizar Mapeo

​Cuerpo de la Solicitud

​Eliminar Mapeo

​Ejemplo Completo: Mapeo de Cliente Bancario

​Respuestas de Error

​Error de Validación

​Error de Transformación

​Mejores Prácticas

​Próximos Pasos

Detección Inteligente de Campos

Importar Entidades

Guía de Mapeo de Datos

Guía de Transformaciones

Descripción General

Crear Mapeo de Campos

Cuerpo de la Solicitud

Objeto de Datos de Mapeo

Objeto de Mapeo de Campo

Respuesta

Tipos de Transformación

Mapeo Directo

Transformación de Formato

Transformación de Cálculo

Transformación Condicional

Transformación de Búsqueda

Transformación Personalizada

Reglas de Validación

Configuración de Transformación

Listar Mapeos

Respuesta

Obtener Mapeo

Respuesta

Actualizar Mapeo

Cuerpo de la Solicitud

Eliminar Mapeo

Ejemplo Completo: Mapeo de Cliente Bancario

Respuestas de Error

Error de Validación

Error de Transformación

Mejores Prácticas

Próximos Pasos