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.

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.

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 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
`direction`	Objeto que nombra una columna de débito o crédito (ver abajo)

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.

direction sirve para un archivo que marca cada fila como débito o crédito en una columna propia. Su valor es un objeto con tres cadenas no vacías, por ejemplo {"column": "DC", "debit": "D", "credit": "C"}. column nombra esa columna, y debit y credit son los dos valores que contiene. Matcher compara estos valores sin distinguir mayúsculas y minúsculas, y deben ser distintos. Una fila de débito se importa con un monto negativo, y una fila de crédito con un monto positivo. La columna de monto debe entonces contener montos sin signo. Matcher rechaza una fila con un monto con signo, o con una celda de dirección vacía o que no contiene ninguno de los dos valores. direction se aplica solo a cargas CSV, JSON y XML.

Crear un mapa de campos

Creas un mapa de campos por fuente. Un segundo mapa de campos para la misma fuente se rechaza con 409. Actualiza el mapa existente. 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

Para cambiar un mapeo, haz PATCH al mapa de campos 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 rechaza claves fuera del vocabulario, 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”.

Nombres de columna vacíos o que no son cadenas

Un nombre de columna debe ser una cadena no vacía. Matcher rechaza null, números, objetos o "" en su lugar.

Dejar fuera un campo de la clave de duplicados

El config de una fuente puede declarar duplicate_key, la lista ordenada de campos que identifican una fila duplicada. La clave predeterminada es solo external_id. El mapa de campos debe mapear cada campo que nombra duplicate_key. Matcher rechaza un mapa de campos que deja alguno de ellos fuera.

Esperar transformaciones

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

Resumen

Guías

Console

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