> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Mapeo de campos
> Renombra las columnas crudas de cada fuente a los campos canónicos de Matcher: external_id, amount, currency, date, más los espacios opcionales de descripción y de comisión por fuente.
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:
```JSON theme={null}
{
"": ""
}
```
* 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:
```bash cURL theme={null}
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**
```json theme={null}
{
"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](/es/reference/products/matcher/create-field-map)
## 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`.
```bash cURL theme={null}
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](/es/reference/products/matcher/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 crudas:
```csv theme={null}
BankRef,BookingDate,Amount,Ccy,Narrative
BANK-001,2025-01-15,-500.00,USD,Wire to Acme Corp
```
Mapa de campos:
```json theme={null}
{
"mapping": {
"external_id": "BankRef",
"amount": "Amount",
"currency": "Ccy",
"date": "BookingDate",
"description": "Narrative"
}
}
```
### Fuente RIGHT: exportación de ledger (CSV)
Columnas crudas:
```csv theme={null}
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:
```json theme={null}
{
"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
***
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.
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.
Las claves son tokens en minúsculas que distinguen mayúsculas y minúsculas. Matcher trata `External_Id`, `Amount` o `CURRENCY` como claves desconocidas.
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".
Cada valor debe ser una cadena no vacía que nombre una columna de la fuente. Matcher rechaza `null`, números, objetos o `""`.
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.
## Próximos pasos
***
Define cómo Matcher compara y agrupa los campos canónicos.
Importa transacciones usando tus mapas de campos.