El mapeo de campos convierte datos de transacciones específicos de la fuente al esquema canónico de Matcher.
Esta normalización es necesaria para comparar transacciones entre sistemas y aplicar reglas de conciliación de manera consistente.
¿Por qué mapeo de campos? Los sistemas externos rara vez comparten los mismos nombres de campos, formatos o convenciones de signo. Por ejemplo:
Sistema Campo de monto Campo de fecha Campo de referencia Banco A transactionAmountpostDatecheckNumberBanco B amttransaction_dateref_numERP AMOUNT_USDGL_DATEDOC_NUM
Los mapeos de campos estandarizan estas variaciones en un único esquema que Matcher puede validar, normalizar y conciliar.
Esquema estándar de Matcher Campos requeridos Cada transacción debe proporcionar estos campos después del mapeo:
Campo Tipo Descripción Ejemplo transaction_idString Identificador único dentro de la fuente "TXN-2024-001"amountDecimal Monto de la transacción (hasta 4 decimales) 1234.56currencyString Código de moneda ISO 4217 "USD"dateDate Fecha de la transacción (YYYY-MM-DD) "2024-01-15"
Campos opcionales Campo Tipo Descripción Ejemplo referenceString Referencia externa o descripción "Factura #1234"counterpartyString Otra parte en la transacción "Acme Corp"typeString Dirección/tipo de transacción "credit", "debit"categoryString Categoría de transacción "payment", "fee"posting_dateDate Fecha de contabilización "2024-01-16"value_dateDate Fecha de valor/liquidación "2024-01-17"external_idString Identificador del sistema externo "BANK-REF-999"metadataObject Campos específicos de la fuente {"department": "sales"}
Creando mapeos de campos Mapeo de campos básico curl -X POST "https://api.matcher.example.com/v1/field-maps" \ -H "Authorization: Bearer $TOKEN " \ -H "Content-Type: application/json" \ -d '{ "name": "Formato de extracto de Chase Bank", "description": "Mapea exportaciones CSV de Chase Bank al esquema de Matcher", "source_type": "csv", "mappings": [ { "source_field": "Transaction ID", "target_field": "transaction_id" }, { "source_field": "Amount", "target_field": "amount" }, { "source_field": "Currency", "target_field": "currency" }, { "source_field": "Post Date", "target_field": "date" }, { "source_field": "Description", "target_field": "reference" } ] }'
Respuesta { "id" : "{fieldMapId}" , "name" : "Formato de extracto de Chase Bank" , "description" : "Mapea exportaciones CSV de Chase Bank al esquema de Matcher" , "source_type" : "csv" , "mappings" : [ { "source_field" : "Transaction ID" , "target_field" : "transaction_id" }, { "source_field" : "Amount" , "target_field" : "amount" }, { "source_field" : "Currency" , "target_field" : "currency" }, { "source_field" : "Post Date" , "target_field" : "date" }, { "source_field" : "Description" , "target_field" : "reference" } ], "created_at" : "2024-01-15T10:00:00Z" }
Los mapeos de campos se crean para una fuente específica dentro de un contexto. La asignación se realiza automáticamente al crear el mapeo usando el endpoint /v1/config/contexts/{contextId}/sources/{sourceId}/field-maps.
Los mapeos de campos pueden aplicar transformaciones para normalizar formatos y convenciones antes de la conciliación.
Transformación Descripción Ejemplo uppercaseConvertir a mayúsculas "abc" → "ABC"lowercaseConvertir a minúsculas "ABC" → "abc"trimEliminar espacios al inicio/final " abc " → "abc"parse_dateAnalizar fecha por formato "01/15/2024" → "2024-01-15"parse_numberAnalizar número con configuración regional "1,234.56" → 1234.56absValor absoluto -100 → 100negateNegar número 100 → -100multiplyMultiplicar por factor 100 × 0.01 → 1replaceReemplazo de cadena "USD$" → "USD"extractExtracción con regex Extraer números de cadena defaultValor por defecto si está vacío null → "UNKNOWN"concatConcatenar campos field1 + field2
curl -X POST "https://api.matcher.example.com/v1/field-maps" \ -H "Authorization: Bearer $TOKEN " \ -H "Content-Type: application/json" \ -d '{ "name": "Formato de banco legacy con transformaciones", "source_type": "csv", "mappings": [ { "source_field": "TXN_NUM", "target_field": "transaction_id", "transformations": [ { "type": "trim" }, { "type": "uppercase" } ] }, { "source_field": "AMOUNT", "target_field": "amount", "transformations": [ { "type": "parse_number", "options": { "locale": "en-US" } }, { "type": "multiply", "options": { "factor": 0.01 } } ] }, { "source_field": "TXN_DATE", "target_field": "date", "transformations": [ { "type": "parse_date", "options": { "format": "MM/DD/YYYY" } } ] }, { "source_field": "CURR", "target_field": "currency", "transformations": [ { "type": "replace", "options": { "search": "$", "replace": "" } }, { "type": "uppercase" }, { "type": "default", "options": { "value": "USD" } } ] } ] }'
Respuesta { "id" : "{fieldMapId}" , "name" : "Formato de banco legacy con transformaciones" , "mappings" : [ { "source_field" : "TXN_NUM" , "target_field" : "transaction_id" , "transformations" : [ { "type" : "trim" }, { "type" : "uppercase" } ] }, { "source_field" : "AMOUNT" , "target_field" : "amount" , "transformations" : [ { "type" : "parse_number" , "options" : { "locale" : "en-US" } }, { "type" : "multiply" , "options" : { "factor" : 0.01 } } ] }, { "source_field" : "TXN_DATE" , "target_field" : "date" , "transformations" : [ { "type" : "parse_date" , "options" : { "format" : "MM/DD/YYYY" } } ] }, { "source_field" : "CURR" , "target_field" : "currency" , "transformations" : [ { "type" : "replace" , "options" : { "search" : "$" , "replace" : "" } }, { "type" : "uppercase" }, { "type" : "default" , "options" : { "value" : "USD" } } ] } ] }
Patrones comunes de parse_date:
Patrón Entrada de ejemplo Salida YYYY-MM-DD2024-01-152024-01-15MM/DD/YYYY01/15/20242024-01-15DD/MM/YYYY15/01/20242024-01-15YYYY-MM-DDTHH:mm:ssZ2024-01-15T10:30:00Z2024-01-15MMM DD, YYYYJan 15, 20242024-01-15DD-MMM-YYYY15-Jan-20242024-01-15
Campos calculados Usa campos calculados cuando los valores deben derivarse en lugar de copiarse de un único campo de origen.
Concatenación { "target_field" : "reference" , "computed" : true , "expression" : { "type" : "concat" , "fields" : [ "DOC_TYPE" , "DOC_NUM" ], "separator" : "-" } }
Entrada: DOC_TYPE: "INV", DOC_NUM: "12345"
Salida: reference: "INV-12345"Mapeo condicional { "target_field" : "type" , "computed" : true , "expression" : { "type" : "conditional" , "conditions" : [ { "if" : { "field" : "DR_CR" , "equals" : "D" }, "then" : "debit" }, { "if" : { "field" : "DR_CR" , "equals" : "C" }, "then" : "credit" } ], "default" : "unknown" } }
Signo de monto basado en tipo { "target_field" : "amount" , "computed" : true , "expression" : { "type" : "conditional" , "conditions" : [ { "if" : { "field" : "TXN_TYPE" , "equals" : "DEBIT" }, "then" : { "type" : "negate" , "field" : "AMOUNT" } } ], "default" : { "field" : "AMOUNT" } } }
Ejemplos de mapeo por tipo de fuente Transaction ID, Post Date, Description, Amount, Balance CHK001, 01/15/2024, Cheque #1234, -500.00, 10500.00 DEP001, 01/15/2024, Depósito móvil, 1500.00, 12000.00 FEE001, 01/15/2024, Cuota de servicio mensual, -12.00, 11988.00
Mapeo de campos { "name" : "CSV de extracto bancario" , "source_type" : "csv" , "mappings" : [ { "source_field" : "Transaction ID" , "target_field" : "transaction_id" }, { "source_field" : "Post Date" , "target_field" : "date" , "transformations" : [ { "type" : "parse_date" , "options" : { "format" : "MM/DD/YYYY" } } ] }, { "source_field" : "Description" , "target_field" : "reference" }, { "source_field" : "Amount" , "target_field" : "amount" , "transformations" : [ { "type" : "parse_number" , "options" : { "locale" : "en-US" } } ] }, { "target_field" : "currency" , "computed" : true , "expression" : { "type" : "constant" , "value" : "USD" } }, { "target_field" : "type" , "computed" : true , "expression" : { "type" : "conditional" , "conditions" : [ { "if" : { "field" : "Amount" , "less_than" : 0 }, "then" : "debit" } ], "default" : "credit" } } ] }
Resultado [ { "transaction_id" : "CHK001" , "date" : "2024-01-15" , "reference" : "Cheque #1234" , "amount" : -500.0 , "currency" : "USD" , "type" : "debit" }, { "transaction_id" : "DEP001" , "date" : "2024-01-15" , "reference" : "Depósito móvil" , "amount" : 1500.0 , "currency" : "USD" , "type" : "credit" } ]
Sistemas ERP (json) { "entries" : [ { "DOC_ID" : "JE-2024-001" , "GL_DATE" : "2024-01-15" , "GL_ACCOUNT" : "1000" , "AMOUNT_USD" : 150000 , "DR_CR" : "D" , "DESCRIPTION" : "Pago a proveedor - Acme Corp" } ] }
Mapeo de campos { "name" : "Formato de asiento contable ERP" , "source_type" : "json" , "root_path" : "entries" , "mappings" : [ { "source_field" : "DOC_ID" , "target_field" : "transaction_id" }, { "source_field" : "GL_DATE" , "target_field" : "date" }, { "source_field" : "AMOUNT_USD" , "target_field" : "amount" , "transformations" : [ { "type" : "multiply" , "options" : { "factor" : 0.01 } } ] }, { "target_field" : "currency" , "computed" : true , "expression" : { "type" : "constant" , "value" : "USD" } }, { "source_field" : "DESCRIPTION" , "target_field" : "reference" }, { "target_field" : "type" , "computed" : true , "expression" : { "type" : "conditional" , "conditions" : [ { "if" : { "field" : "DR_CR" , "equals" : "D" }, "then" : "debit" }, { "if" : { "field" : "DR_CR" , "equals" : "C" }, "then" : "credit" } ] } }, { "source_field" : "GL_ACCOUNT" , "target_field" : "metadata.gl_account" } ] }
Resultado { "transaction_id" : "JE-2024-001" , "date" : "2024-01-15" , "amount" : 1500.0 , "currency" : "USD" , "reference" : "Pago a proveedor - Acme Corp" , "type" : "debit" , "metadata" : { "gl_account" : "1000" } }
Pasarelas de pago (xml) < transactions > < transaction > < id > PAY-2024-001 </ id > < timestamp > 2024-01-15T14:30:00Z </ timestamp > < amount currency = "USD" > 99.99 </ amount > < merchant > Tienda #123 </ merchant > < status > completed </ status > </ transaction > </ transactions >
Mapeo de campos { "name" : "Formato XML de pasarela de pago" , "source_type" : "xml" , "root_path" : "transactions/transaction" , "mappings" : [ { "source_field" : "id" , "target_field" : "transaction_id" }, { "source_field" : "timestamp" , "target_field" : "date" , "transformations" : [ { "type" : "parse_date" , "options" : { "format" : "ISO8601" } } ] }, { "source_field" : "amount" , "target_field" : "amount" , "transformations" : [ { "type" : "parse_number" } ] }, { "source_field" : "amount@currency" , "target_field" : "currency" }, { "source_field" : "merchant" , "target_field" : "reference" }, { "target_field" : "type" , "computed" : true , "expression" : { "type" : "constant" , "value" : "credit" } } ] }
Resultado { "transaction_id" : "PAY-2024-001" , "date" : "2024-01-15" , "amount" : 99.99 , "currency" : "USD" , "reference" : "Tienda #123" , "type" : "credit" }
Mejores prácticas
Nombra los mapeos de campos como versiones
Haz explícitos los cambios de formato (por ejemplo, CSV Banco v2.0) para preservar la reimportación y auditabilidad.
Explica las transformaciones no obvias
Agrega descripciones para transformaciones que cambian la semántica (por ejemplo, “Monto en centavos, dividir por 100”).
Define valores por defecto intencionalmente
Usa default solo para campos opcionales y elige valores que hagan explícito el comportamiento posterior.
Normaliza las convenciones de signo
Estandariza débitos y créditos entre fuentes antes de conciliar.
Versiona en lugar de editar en su lugar
Cuando los formatos de origen cambian, crea un nuevo mapeo de campos en lugar de modificar uno existente.
Próximos pasos 
