Mapeamentos de Campos

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.

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.

Criar Mapeamento de Campo

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

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

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

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

Transformação de Formatação

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

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

Exemplos Comuns de Formatação:

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

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

Exemplos Comuns de Cálculo:

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

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

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

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

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

Regras de Validação

Configure o comportamento de validação:

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

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

GET /custom-schemas/mappings

Resposta

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

GET /custom-schemas/mappings/:id

Resposta

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

PATCH /custom-schemas/mappings/:id

Corpo da Requisição

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

DELETE /custom-schemas/mappings/:id

Exemplo Completo: Mapeamento de Cliente Bancário

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

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

Erro de Transformação

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

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

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

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

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

Próximos Passos

Detecção Inteligente de Campos

Gere mapeamentos automaticamente a partir de dados de amostra

Importar Entidades

Use mapeamentos para importar dados de entidades

Guia de Mapeamento de Dados

Guia completo do fluxo de trabalho

Guia de Transformações

Padrões avançados de transformação

Começando

Referência API

Ingestão de Dados

Entidades

Conheça Seu Negócio (KYB)

Conheça Seu Cliente (KYC)

Monitoramento de Transações

Tutoriais Interativos

​Visão Geral

​Criar Mapeamento de Campo

​Corpo da Requisição

​Objeto Mapping Data

​Objeto Field Mapping

​Resposta

​Tipos de Transformação

​Mapeamento Direto

​Transformação de Formatação

​Transformação de Cálculo

​Transformação Condicional

​Transformação de Consulta

​Transformação Personalizada

​Regras de Validação

​Configurações de Transformação

​Listar Mapeamentos

​Resposta

​Obter Mapeamento

​Resposta

​Atualizar Mapeamento

​Corpo da Requisição

​Excluir Mapeamento

​Exemplo Completo: Mapeamento de Cliente Bancário

​Respostas de Erro

​Erro de Validação

​Erro de Transformação

​Melhores Práticas

​Próximos Passos

Detecção Inteligente de Campos

Importar Entidades

Guia de Mapeamento de Dados

Guia de Transformações

Visão Geral

Criar Mapeamento de Campo

Corpo da Requisição

Objeto Mapping Data

Objeto Field Mapping

Resposta

Tipos de Transformação

Mapeamento Direto

Transformação de Formatação

Transformação de Cálculo

Transformação Condicional

Transformação de Consulta

Transformação Personalizada

Regras de Validação

Configurações de Transformação

Listar Mapeamentos

Resposta

Obter Mapeamento

Resposta

Atualizar Mapeamento

Corpo da Requisição

Excluir Mapeamento

Exemplo Completo: Mapeamento de Cliente Bancário

Respostas de Erro

Erro de Validação

Erro de Transformação

Melhores Práticas

Próximos Passos