Field Mappings

Gerencie mapeamentos de campos que transformam e normalizam os dados extraídos.

Visão Geral

Field Mappings permitem:

• Mapear campos extraídos para campos do seu sistema
• Aplicar transformações automáticas (datas, moedas, etc.)
• Definir valores padrão para campos ausentes
• Priorizar mapeamentos conflitantes

Endpoints

Método	Endpoint	Descrição
POST	/api/v1/data-extraction/templates/:templateId/mappings	Criar mapeamento
GET	/api/v1/data-extraction/templates/:templateId/mappings	Listar mapeamentos
GET	/api/v1/data-extraction/templates/:templateId/mappings/:id	Obter mapeamento
PATCH	/api/v1/data-extraction/templates/:templateId/mappings/:id	Atualizar mapeamento
DELETE	/api/v1/data-extraction/templates/:templateId/mappings/:id	Excluir mapeamento

Criar Mapeamento

POST https://data-extraction.stg.catalisa.app/api/v1/data-extraction/templates/:templateId/mappings
Authorization: Bearer {token}
Content-Type: application/json

Request Body

{
  "data": {
    "type": "field-mapping",
    "attributes": {
      "sourceField": "dataNascimento",
      "targetField": "birthDate",
      "transformType": "DATE_FORMAT",
      "transformConfig": {
        "from": "DD/MM/YYYY",
        "to": "YYYY-MM-DD"
      },
      "isRequired": true,
      "priority": 1
    }
  }
}

Atributos

Campo	Tipo	Obrigatório	Descrição
sourceField	string	Sim	Nome do campo extraído
targetField	string	Sim	Nome do campo de destino
transformType	enum	Não	Tipo de transformação (default: NONE)
transformConfig	object	Não	Configuração da transformação
isRequired	boolean	Não	Se o campo é obrigatório (default: false)
defaultValue	string	Não	Valor padrão se ausente
priority	integer	Não	Prioridade (menor = maior prioridade)

Response (201 Created)

{
  "data": {
    "type": "field-mapping",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "links": {
      "self": "/api/v1/data-extraction/templates/.../mappings/550e8400-e29b-41d4-a716-446655440000"
    },
    "attributes": {
      "sourceField": "dataNascimento",
      "targetField": "birthDate",
      "transformType": "DATE_FORMAT",
      "transformConfig": {
        "from": "DD/MM/YYYY",
        "to": "YYYY-MM-DD"
      },
      "isRequired": true,
      "defaultValue": null,
      "priority": 1,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  }
}

Tipos de Transformação

NONE

Sem transformação. O valor é copiado diretamente.

{
  "transformType": "NONE"
}

DATE_FORMAT

Converte formatos de data.

{
  "transformType": "DATE_FORMAT",
  "transformConfig": {
    "from": "DD/MM/YYYY",
    "to": "YYYY-MM-DD",
    "locale": "pt-BR"
  }
}

Parâmetro	Descrição
from	Formato de entrada
to	Formato de saída
locale	Locale para parsing (opcional)

Tokens de formato:

• DD - Dia (01-31)
• MM - Mês (01-12)
• YYYY - Ano (4 dígitos)
• YY - Ano (2 dígitos)

Exemplos:

• 15/01/2024 (DD/MM/YYYY) → 2024-01-15 (YYYY-MM-DD)
• 01-15-2024 (MM-DD-YYYY) → 2024-01-15 (YYYY-MM-DD)

CURRENCY_NORMALIZE

Normaliza valores monetários para formato numérico.

{
  "transformType": "CURRENCY_NORMALIZE",
  "transformConfig": {
    "locale": "pt-BR"
  }
}

Parâmetro	Descrição
locale	Locale para parsing (determina separadores)

Exemplos:

• R$ 1.234,56 → 1234.56
• R$1234,56 → 1234.56
• 1.234,56 → 1234.56

NUMBER_PARSE

Converte string numérica para número.

{
  "transformType": "NUMBER_PARSE",
  "transformConfig": {
    "locale": "pt-BR"
  }
}

Exemplos:

• 1.234,56 → 1234.56
• 1,234.56 (en-US) → 1234.56

STRING_TRIM

Remove espaços em branco.

{
  "transformType": "STRING_TRIM"
}

Exemplos:

• " João Silva " → "João Silva"

REGEX_EXTRACT

Extrai parte do valor usando expressão regular.

{
  "transformType": "REGEX_EXTRACT",
  "transformConfig": {
    "pattern": "\\d{3}\\.\\d{3}\\.\\d{3}-\\d{2}",
    "group": 0
  }
}

Parâmetro	Descrição
pattern	Expressão regular
group	Grupo de captura (0 = match completo)

Exemplos:

• Pattern: (\d{2})/(\d{2})/(\d{4}), Group: 3 → Extrai apenas o ano

Exemplo Completo

Configurando mapeamentos para um template de RG:

const templateId = 'template-uuid';
const baseUrl = 'https://data-extraction.stg.catalisa.app';

// Mapeamento de data de nascimento
await fetch(`${baseUrl}/api/v1/data-extraction/templates/${templateId}/mappings`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    data: {
      type: 'field-mapping',
      attributes: {
        sourceField: 'dataNascimento',
        targetField: 'birthDate',
        transformType: 'DATE_FORMAT',
        transformConfig: { from: 'DD/MM/YYYY', to: 'YYYY-MM-DD' },
        isRequired: true,
        priority: 1
      }
    }
  })
});

// Mapeamento de CPF (extrai apenas números)
await fetch(`${baseUrl}/api/v1/data-extraction/templates/${templateId}/mappings`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    data: {
      type: 'field-mapping',
      attributes: {
        sourceField: 'cpf',
        targetField: 'documentNumber',
        transformType: 'REGEX_EXTRACT',
        transformConfig: { pattern: '\\d+', group: 0 },
        isRequired: false,
        priority: 2
      }
    }
  })
});

// Mapeamento de nome (trim)
await fetch(`${baseUrl}/api/v1/data-extraction/templates/${templateId}/mappings`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    data: {
      type: 'field-mapping',
      attributes: {
        sourceField: 'nome',
        targetField: 'fullName',
        transformType: 'STRING_TRIM',
        isRequired: true,
        priority: 1
      }
    }
  })
});

Resultado do Mapeamento

Após a extração, os dados mapeados ficam disponíveis no campo mappedData:

{
  "rawData": {
    "nome": "  JOÃO DA SILVA  ",
    "dataNascimento": "15/01/1990",
    "cpf": "123.456.789-00"
  },
  "mappedData": {
    "fullName": "JOÃO DA SILVA",
    "birthDate": "1990-01-15",
    "documentNumber": "12345678900"
  }
}

Listar Mapeamentos

GET https://data-extraction.stg.catalisa.app/api/v1/data-extraction/templates/:templateId/mappings
Authorization: Bearer {token}

Response (200 OK)

{
  "data": [
    {
      "type": "field-mapping",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "attributes": {
        "sourceField": "dataNascimento",
        "targetField": "birthDate",
        "transformType": "DATE_FORMAT",
        "priority": 1
      }
    }
  ]
}

Erros Comuns

Código	Erro	Descrição
400	VALIDATION_ERROR	Configuração de transformação inválida
404	NOT_FOUND	Template ou mapeamento não encontrado
409	CONFLICT	Mapeamento duplicado para o mesmo sourceField