Skip to main content

​
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

CampoTipoObrigatórioDescrição
namestringSimNome da configuração de mapeamento
descriptionstringNãoDescrição do mapeamento
sourceSchemaIduuidNãoID do schema personalizado de origem
targetSchemaTypestringNãoTipo do schema de destino (ex: “gueno_entity”)
sourceSchemaNamestringNãoAlternativa ao sourceSchemaId
targetSchemaNamestringNãoAlternativa ao targetSchemaType
mappingDataobjectSimConfiguração do mapeamento
industrystringNãoContexto da indústria
collaboratorsarrayNãoIDs de usuários com acesso

​
Objeto Mapping Data

CampoTipoObrigatórioDescrição
mappingsarraySimArray de mapeamentos de campos
templatesarrayNãoIDs de templates para aplicar
validationobjectNãoRegras de validação
transformationSettingsobjectNãoConfigurações de processamento

​
Objeto Field Mapping

CampoTipoObrigatórioDescrição
idstringSimIdentificador único do mapeamento
sourceFieldstringSimNome do campo de origem
targetFieldstringSimNome do campo de destino (suporta notação de ponto)
transformationobjectNãoTransformação a ser aplicada
requiredbooleanSimO campo é obrigatório
dataTypestringSimTipo de dados esperado
defaultValueanyNãoValor padrão se a origem for null/ausente
validationRulestringNãoExpressã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çãoTipoDescrição
strictModebooleanFalha em qualquer erro de validação
allowExtraFieldsbooleanPermite campos de origem não mapeados
requiredFieldsarrayCampos que devem ter valores

​
Configurações de Transformação

Configure o comportamento de processamento: 
{
  "transformationSettings": {
    "errorHandling": "default",
    "batchSize": 100,
    "timeout": 30000
  }
}
ConfiguraçãoTipoDescrição
errorHandlingenumskip, fail, ou default
batchSizenumberRegistros por lote (1-1000)
timeoutnumberTimeout 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 com mapeamentos diretos para a maioria dos campos
  • Adicione transformações apenas quando necessário
  • Teste cada transformação individualmente
  • Aumente gradualmente a complexidade
  • 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
  • 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
  • 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