Mapeo de campos

Un mapa de campos le indica a Matcher qué columna sin procesar de una fuente contiene cada campo de transacción canónico. Como cada fuente (extractos bancarios, exportaciones de ledger, reportes de pasarelas) nombra sus columnas de forma distinta, el mapa de campos normaliza esos nombres de columna en un único vocabulario fijo antes de que se ejecute el matching.

Un mapa de campos solo renombra columnas. No analiza, calcula, transforma ni combina valores. Cada campo canónico se completa a partir de exactamente una columna de origen.

Qué es un mapa de campos

Un mapa de campos pertenece a una única fuente dentro de un contexto. Un contexto concilia dos lados — una fuente LEFT y una fuente RIGHT — y cada fuente tiene su propio mapa de campos. Matcher compara los campos canónicos producidos por ambos mapas, así que ambos lados deben resolverse al mismo vocabulario aunque sus archivos sin procesar no se parezcan en nada. El mapeo es un objeto JSON con la forma:

{ "<canonicalKey>": "<sourceColumnName>" }

La clave es un campo canónico. Las claves provienen de un vocabulario cerrado y sensible a mayúsculas y minúsculas: Matcher rechaza cualquier clave fuera de él.
El valor es el nombre de la columna en la fuente sin procesar que contiene ese campo. Los valores son texto libre (como sea que tu archivo llame a la columna) y deben ser cadenas no vacías.

Vocabulario canónico

El espacio de claves es cerrado. Estas son las únicas claves que Matcher acepta.

Claves requeridas

Todo mapa de campos debe declarar las cuatro:

Clave	Descripción
`external_id`	Identificador único del registro dentro de la fuente
`amount`	Monto de la transacción
`currency`	Código de moneda ISO 4217
`date`	Fecha de la transacción

Claves opcionales

Declara estas solo cuando la fuente las contenga:

Clave	Descripción
`description`	Etiqueta de texto libre copiada en la columna de descripción de la transacción
`fee_amount`	Columna que contiene el monto de una comisión para el registro
`fee_currency`	Columna que contiene la moneda de esa comisión

fee_amount y fee_currency son la ranura de comisión opcional. Cuando están presentes, el valor de la columna mapeada se copia en la metadata de la transacción que lee la verificación de comisiones, de modo que una columna con cualquier nombre (por ejemplo mdr_fee) puede transportar comisiones de extremo a extremo sin metadata construida a mano. Omítelas y el comportamiento es idéntico al de un mapa sin ranura de comisión.

Crear un mapa de campos

Los mapas de campos se crean por fuente. Envía el objeto de mapeo al endpoint de mapa de campos de la fuente:

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{sourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "external_id": "Transaction ID",
     "amount": "Amount",
     "currency": "Currency",
     "date": "Post Date",
     "description": "Memo"
   }
 }'

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mapping": {
    "external_id": "Transaction ID",
    "amount": "Amount",
    "currency": "Currency",
    "date": "Post Date",
    "description": "Memo"
  },
  "version": 1,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}

API Reference: Create field map

Actualizar un mapa de campos

Cada fuente tiene un mapa de campos. Para cambiar un mapeo, hazle PATCH por su propio ID (no el ID de la fuente). Envía el mapeo completo: reemplaza al anterior e incrementa version.

cURL

curl -X PATCH "https://api.matcher.example.com/v1/field-maps/{fieldMapId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "external_id": "Transaction ID",
     "amount": "Amount",
     "currency": "Currency",
     "date": "Value Date",
     "description": "Memo",
     "fee_amount": "Fee",
     "fee_currency": "Fee Currency"
   }
 }'

API Reference: Update field map

Otras operaciones:

Operación	Endpoint
Obtener el mapa de campos de una fuente	`GET /v1/contexts/{contextId}/sources/{sourceId}/field-maps`
Listar todos los mapas de campos de un contexto	`GET /v1/contexts/{contextId}/field-maps`
Eliminar un mapa de campos	`DELETE /v1/field-maps/{fieldMapId}`

Ejemplo: ambos lados de un contexto

Un contexto concilia un feed bancario contra una exportación de ledger interna. Los dos archivos usan nombres de columna distintos, así que cada fuente declara su propio mapa, pero ambos se resuelven a las mismas claves canónicas.

Fuente LEFT — extracto bancario (CSV)

Columnas sin procesar:

BankRef,BookingDate,Amount,Ccy,Narrative
BANK-001,2025-01-15,-500.00,USD,Wire to Acme Corp

Mapa de campos:

{
  "mapping": {
    "external_id": "BankRef",
    "amount": "Amount",
    "currency": "Ccy",
    "date": "BookingDate",
    "description": "Narrative"
  }
}

Fuente RIGHT — exportación de ledger (CSV)

Columnas sin procesar:

entry_id,posted_at,value,asset,memo,mdr_fee,fee_ccy
LDG-9931,2025-01-15,-500.00,USD,Payment Acme Corp,2.50,USD

Mapa de campos:

{
  "mapping": {
    "external_id": "entry_id",
    "amount": "value",
    "currency": "asset",
    "date": "posted_at",
    "description": "memo",
    "fee_amount": "mdr_fee",
    "fee_currency": "fee_ccy"
  }
}

Ambas fuentes ahora exponen external_id, amount, currency y date en el vocabulario canónico, de modo que las reglas de matching pueden compararlas directamente, aunque un archivo llamara al monto Amount y el otro lo llamara value.

Errores comunes

Invertir la dirección

La clave es el campo canónico y el valor es tu columna — {"external_id": "BankRef"}, no {"BankRef": "external_id"}. Escribirlo al revés coloca una clave desconocida (BankRef) a la izquierda y se rechaza.

Usar claves fuera del vocabulario

Solo se aceptan external_id, amount, currency, date, description, fee_amount y fee_currency. Claves como transaction_id, reference, counterparty o type se rechazan como claves desconocidas, y el error nombra a cada infractora.

Mayúsculas incorrectas

Las claves son tokens en minúsculas y sensibles a mayúsculas y minúsculas. External_Id, Amount o CURRENCY se tratan como claves desconocidas.

Falta una clave requerida

Todas las claves external_id, amount, currency y date deben estar presentes. Un mapa al que le falte alguna falla la validación con un mensaje “missing required keys”.

Valores vacíos o que no son cadenas

Cada valor debe ser una cadena no vacía que nombre una columna de origen. null, números, objetos o "" se rechazan.

Esperar transformaciones

Los mapas de campos no analizan fechas, dividen montos, concatenan columnas ni aplican condicionales. Entrega los valores ya con la forma esperada desde el archivo de origen, o normaliza aguas arriba antes de subirlos.

Resumen

Guías

Matcher UI

Servidor MCP

Operaciones

Mapeo de campos

Qué es un mapa de campos

Vocabulario canónico

Claves requeridas

Claves opcionales

Crear un mapa de campos

Actualizar un mapa de campos

Ejemplo: ambos lados de un contexto

Fuente LEFT — extracto bancario (CSV)

Fuente RIGHT — exportación de ledger (CSV)

Errores comunes

Próximos pasos

Reglas de match

Subir archivos

​Qué es un mapa de campos

​Vocabulario canónico

​Claves requeridas

​Claves opcionales

​Crear un mapa de campos

​Actualizar un mapa de campos

​Ejemplo: ambos lados de un contexto

​Fuente LEFT — extracto bancario (CSV)

​Fuente RIGHT — exportación de ledger (CSV)

​Errores comunes

​Próximos pasos

Reglas de match

Subir archivos

Qué es un mapa de campos

Vocabulario canónico

Claves requeridas

Claves opcionales

Crear un mapa de campos

Actualizar un mapa de campos

Ejemplo: ambos lados de un contexto

Fuente LEFT — extracto bancario (CSV)

Fuente RIGHT — exportación de ledger (CSV)

Errores comunes

Próximos pasos