> ## 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 sin procesar de cada fuente a los campos de transacción canónicos de Matcher usando un vocabulario de mapeo cerrado, para que cada lado de una conciliación se compare de forma consistente.
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:
```
{ "": "" }
```
* 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:
```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"
}
```
API Reference: [Create field map](/es/reference/matcher/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`.
```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"
}
}'
```
API Reference: [Update field map](/es/reference/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 sin procesar:
```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 sin procesar:
```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"
}
}
```
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
***
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.
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.
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.
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 origen. `null`, números, objetos o `""` se rechazan.
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.
## Próximos pasos
***
Define cómo se comparan y agrupan los campos canónicos.
Importa transacciones usando tus mapas de campos.