Mapeo de campos

Un mapa de campos le dice a Matcher qué columna cruda de una fuente lleva cada campo canónico de la transacción. Cada fuente nombra sus columnas de forma distinta: extractos bancarios, exportaciones de ledger, informes de gateway. El mapa de campos normaliza esos nombres de columna en un solo vocabulario fijo antes de que corra la coincidencia.

Un mapa de campos solo renombra columnas. No parsea, calcula, transforma ni combina valores. Exactamente una columna de la fuente rellena cada campo canónico.

Qué es un mapa de campos

Un mapa de campos pertenece a una sola 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 que producen ambos mapas. Ambos lados deben resolverse al mismo vocabulario, incluso cuando sus archivos crudos no se parecen en nada. El mapeo es un objeto JSON con la forma:

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

La clave es un campo canónico. Las claves vienen de un vocabulario cerrado que distingue mayúsculas y minúsculas. Matcher rechaza cualquier clave fuera de él.
El valor es el nombre de la columna en la fuente cruda que lleva 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

Matcher usa un espacio de claves cerrado. Estas son las únicas claves que Matcher acepta.

Claves obligatorias

Cada 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 lleva:

Clave	Descripción
`description`	Etiqueta de texto libre copiada a la columna de descripción de la transacción
`fee_amount`	Columna que lleva un monto de comisión del registro
`fee_currency`	Columna que lleva la moneda de esa comisión

fee_amount y fee_currency son el espacio de comisión opcional. Cuando están presentes, el valor de la columna mapeada se copia a los metadatos de la transacción que lee la verificación de comisiones. Por eso una columna con cualquier nombre, por ejemplo mdr_fee, puede llevar comisiones de punta a punta sin metadatos armados a mano. Omítelas y el comportamiento es idéntico al de un mapa sin espacio de comisión.

Crear un mapa de campos

Creas un mapa de campos 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"
}

Referencia de API: Crear mapa de campos

Actualizar un mapa de campos

Cada fuente tiene un mapa de campos. Para cambiar un mapeo, haz PATCH por su propio ID (no el ID de la fuente). Envía el mapeo completo. Reemplaza el 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"
   }
 }'

Referencia de API: Actualizar mapa de campos

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

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

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

Ahora ambas fuentes exponen external_id, amount, currency y date en el vocabulario canónico. Las reglas de coincidencia pueden compararlas directamente, aunque un archivo llamó al monto Amount y el otro lo llamó 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 pone una clave desconocida (BankRef) a la izquierda, y Matcher rechaza el mapa.

Usar claves fuera del vocabulario

Matcher acepta solo external_id, amount, currency, date, description, fee_amount y fee_currency. Matcher rechaza claves como transaction_id, reference, counterparty o type como claves desconocidas. El error nombra a cada infractor.

Mayúsculas o minúsculas equivocadas

Las claves son tokens en minúsculas que distinguen mayúsculas y minúsculas. Matcher trata External_Id, Amount o CURRENCY como claves desconocidas.

Falta una clave obligatoria

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 la fuente. Matcher rechaza null, números, objetos o "".

Esperar transformaciones

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

Resumen

Guías

Matcher UI

Servidor MCP

Operaciones

Mapeo de campos

Qué es un mapa de campos

Vocabulario canónico

Claves obligatorias

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 coincidencia

Subir archivos

​Qué es un mapa de campos

​Vocabulario canónico

​Claves obligatorias

​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 coincidencia

Subir archivos

Qué es un mapa de campos

Vocabulario canónico

Claves obligatorias

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