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

# Mapeamentos de Campos

> Mapeie os campos de seus dados para o modelo de entidade gu1 com transformações — no pipeline de ingestão de dados da gu1 com schemas personalizados.

## Visão Geral

Os Mapeamentos de Campos definem como os campos do seu schema personalizado são traduzidos para o modelo de entidade unificado do gu1. Cada mapeamento pode incluir transformações para formatar, calcular ou processar dados condicionalmente durante a importação.

<Info>
  Os mapeamentos fazem a ponte entre a sua estrutura de dados e o modelo de entidade do gu1, permitindo a ingestão de dados perfeita de qualquer fonte.
</Info>

## Criar Mapeamento de Campo

Crie uma configuração de mapeamento para seu schema 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>

### Corpo da Requisição

| Campo              | Tipo   | Obrigatório | Descrição                                       |
| ------------------ | ------ | ----------- | ----------------------------------------------- |
| `name`             | string | Sim         | Nome da configuração de mapeamento              |
| `description`      | string | Não         | Descrição do mapeamento                         |
| `sourceSchemaId`   | uuid   | Não         | ID do schema personalizado de origem            |
| `targetSchemaType` | string | Não         | Tipo do schema de destino (ex: "gueno\_entity") |
| `sourceSchemaName` | string | Não         | Alternativa ao sourceSchemaId                   |
| `targetSchemaName` | string | Não         | Alternativa ao targetSchemaType                 |
| `mappingData`      | object | Sim         | Configuração do mapeamento                      |
| `industry`         | string | Não         | Contexto da indústria                           |
| `collaborators`    | array  | Não         | IDs de usuários com acesso                      |

### Objeto Mapping Data

| Campo                    | Tipo   | Obrigatório | Descrição                      |
| ------------------------ | ------ | ----------- | ------------------------------ |
| `mappings`               | array  | Sim         | Array de mapeamentos de campos |
| `templates`              | array  | Não         | IDs de templates para aplicar  |
| `validation`             | object | Não         | Regras de validação            |
| `transformationSettings` | object | Não         | Configurações de processamento |

### Objeto Field Mapping

| Campo            | Tipo    | Obrigatório | Descrição                                           |
| ---------------- | ------- | ----------- | --------------------------------------------------- |
| `id`             | string  | Sim         | Identificador único do mapeamento                   |
| `sourceField`    | string  | Sim         | Nome do campo de origem                             |
| `targetField`    | string  | Sim         | Nome do campo de destino (suporta notação de ponto) |
| `transformation` | object  | Não         | Transformação a ser aplicada                        |
| `required`       | boolean | Sim         | O campo é obrigatório                               |
| `dataType`       | string  | Sim         | Tipo de dados esperado                              |
| `defaultValue`   | any     | Não         | Valor padrão se a origem for null/ausente           |
| `validationRule` | string  | Não         | Expressão de validação personalizada                |

### Resposta

```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 Transformação

### Mapeamento Direto

Copia o valor como está, sem alterações:

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

### Transformação de Formatação

Aplica formatação de string, data ou número:

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

**Exemplos Comuns de Formatação:**

```javascript theme={null}
// Remover espaços e converter para maiúsculas
"value.trim().toUpperCase()"

// Formatar data
"new Date(value).toISOString()"

// Formatar moeda
"parseFloat(value).toFixed(2)"

// Limpar número de telefone
"value.replace(/[^0-9]/g, '')"
```

### Transformação de Cálculo

Realiza cálculos matemáticos:

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

**Exemplos Comuns de Cálculo:**

```javascript theme={null}
// Converter milhares para valor real
"value * 1000"

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

// Somar múltiplos campos
"sourceData.field1 + sourceData.field2"

// Cálculo de média
"(field1 + field2 + field3) / 3"
```

### Transformação 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"}
      ]
    }
  }
}
```

### Transformação de Consulta

Consulta valores de tabelas de referência:

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

### Transformação Personalizada

Executa JavaScript personalizado:

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

<Warning>
  Transformações personalizadas têm restrições de segurança. Somente funções JavaScript da lista de permissões são permitidas.
</Warning>

## Regras de Validação

Configure o comportamento de validação:

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

| Configuração       | Tipo    | Descrição                             |
| ------------------ | ------- | ------------------------------------- |
| `strictMode`       | boolean | Falha em qualquer erro de validação   |
| `allowExtraFields` | boolean | Permite campos de origem não mapeados |
| `requiredFields`   | array   | Campos que devem ter valores          |

## Configurações de Transformação

Configure o comportamento de processamento:

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

| Configuração    | Tipo   | Descrição                    |
| --------------- | ------ | ---------------------------- |
| `errorHandling` | enum   | `skip`, `fail`, ou `default` |
| `batchSize`     | number | Registros por lote (1-1000)  |
| `timeout`       | number | Timeout em milissegundos     |

## Listar Mapeamentos

Obtenha todas as configurações de mapeamento da sua organização:

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

### Resposta

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

## Obter Mapeamento

Recupere uma configuração de mapeamento específica:

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

### Resposta

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

## Atualizar Mapeamento

Atualize uma configuração de mapeamento existente:

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

### Corpo da Requisição

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

## Excluir Mapeamento

Exclua uma configuração de mapeamento:

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

## Exemplo Completo: Mapeamento de Cliente Bancário

```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
    }
  }
}
```

## Respostas de Erro

### Erro de Validação

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

### Erro de Transformação

```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"
    }
  }
}
```

## Melhores Práticas

<AccordionGroup>
  <Accordion icon="bolt" title="Comece Simples">
    * Comece com mapeamentos diretos para a maioria dos campos
    * Adicione transformações apenas quando necessário
    * Teste cada transformação individualmente
    * Aumente gradualmente a complexidade
  </Accordion>

  <Accordion icon="vial" title="Testes">
    * Teste mapeamentos com dados de amostra antes da produção
    * Valide casos extremos (valores null, vazios, inválidos)
    * Monitore erros de transformação nos logs
    * Use strictMode em ambientes de produção
  </Accordion>

  <Accordion icon="shield" title="Qualidade de Dados">
    * Defina defaultValue apropriado para campos opcionais
    * Use validationRule para validações complexas
    * Aplique transformações de formatação para consistência
    * Trate valores ausentes/null explicitamente
  </Accordion>

  <Accordion icon="gauge" title="Performance">
    * Evite transformações personalizadas complexas em caminhos críticos
    * Use processamento em lote para grandes conjuntos de dados
    * Defina valores de timeout razoáveis
    * Monitore os tempos de execução das transformações
  </Accordion>
</AccordionGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Detecção Inteligente de Campos" icon="wand-magic-sparkles" href="/api-reference/data-ingestion/custom-schemas">
    Gere mapeamentos automaticamente a partir de dados de amostra
  </Card>

  <Card title="Importar Entidades" icon="upload" href="/api-reference/entities/create">
    Use mapeamentos para importar dados de entidades
  </Card>

  <Card title="Guia de Mapeamento de Dados" icon="book" href="/api-reference/data-ingestion/overview">
    Guia completo do fluxo de trabalho
  </Card>

  <Card title="Guia de Transformações" icon="arrow-right-arrow-left" href="/api-reference/data-ingestion/field-mappings">
    Padrões avançados de transformação
  </Card>
</CardGroup>