Subir archivos

Esta guía cubre cómo importar datos de transacciones de fuentes externas a Matcher para la conciliación.

Formatos admitidos

Matcher acepta archivos de transacciones en tres formatos de propósito general:

CSV: valores separados por comas con encabezados. El más común para exportaciones bancarias.
JSON: arreglo de objetos de transacción. El mejor para integraciones de API.
XML: elementos estructurados. Común para sistemas empresariales.

Más allá de estos, el endpoint de carga también acepta formatos bancarios especializados como camt053 y las claves de descriptor con namespace del catálogo de formatos (CNAB, layouts de adquirentes). Consulta Formatos de importación para el catálogo completo.

Requisitos de estructura del archivo

Cada archivo debe contener registros de transacciones con campos que puedas mapear al esquema interno de Matcher.

Campos obligatorios

Cada transacción debe tener estos campos (o equivalentes mapeables):

Campo	Tipo	Descripción
`external_id`	String	Identificador único dentro de la fuente
`amount`	Decimal	Monto de la transacción (positivo o negativo)
`currency`	String	Código de moneda ISO 4217
`date`	Date/DateTime	Fecha de la transacción

Campos opcionales

Campo	Tipo	Descripción
`description`	String	Descripción en texto libre
`fee_amount`	Decimal	Comisión cobrada en la transacción
`fee_currency`	String	Moneda de la comisión
`direction`	Object	Columna que marca cada fila como débito o crédito. Consulta Columna de débito y crédito.

Matcher guarda las columnas no mapeadas como metadatos de la transacción.

Columna de débito y crédito

Algunos archivos marcan cada fila como débito o crédito en una columna separada. Para leer el signo de esa columna, mapea la clave opcional direction a un objeto {column, debit, credit}:

"direction": { "column": "type", "debit": "debit", "credit": "credit" }

Una fila de débito se importa con un monto negativo, y una fila de crédito se importa con un monto positivo. Con direction mapeada, la columna de monto debe venir sin signo. Un monto con signo, una celda de dirección vacía o un valor de dirección desconocido rechaza la fila. Matcher lee direction solo en archivos CSV, JSON y XML.

Ejemplos de formato

CSV

Requisitos de CSV:

La primera fila debe ser de encabezados de columna
Codificación UTF-8 y delimitador de coma de forma predeterminada (configurables)
Entrecomilla los campos que contienen comas o saltos de línea

Ejemplo de código

 transaction_id,amount,currency,date,reference,type
 BANK-2024-001,1500.00,USD,2024-01-15,Invoice #1234,credit
 BANK-2024-002,250.00,USD,2024-01-15,Service fee,debit
 BANK-2024-003,3200.50,USD,2024-01-16,Customer payment,credit
 BANK-2024-004,89.99,USD,2024-01-16,Subscription,debit

JSON

Requisitos de JSON:

Un arreglo de objetos o un solo objeto
Nombres de campo consistentes entre objetos
Codificación UTF-8 de forma predeterminada (configurable)

Ejemplo de código

[
  {
    "transaction_id": "BANK-2024-001",
    "amount": 1500.0,
    "currency": "USD",
    "date": "2024-01-15",
    "reference": "Invoice #1234",
    "type": "credit"
  },
  {
    "transaction_id": "BANK-2024-002",
    "amount": 250.0,
    "currency": "USD",
    "date": "2024-01-15",
    "reference": "Service fee",
    "type": "debit"
  }
]

XML

Requisitos de XML:

XML bien formado
Elementos de registro llamados transaction, row, record, item o entry
Codificación UTF-8 de forma predeterminada (configurable)

Ejemplo de código

  <?xml version="1.0" encoding="UTF-8"?>
  <transactions>
    <transaction>
      <transaction_id>BANK-2024-001</transaction_id>
      <amount>1500.00</amount>
      <currency>USD</currency>
      <date>2024-01-15</date>
     <reference>Invoice #1234</reference>
      <type>credit</type>
    </transaction>
    <transaction>
      <transaction_id>BANK-2024-002</transaction_id>
      <amount>250.00</amount>
      <currency>USD</currency>
      <date>2024-01-15</date>
      <reference>Service fee</reference>
      <type>debit</type>
      </transaction>
  </transactions>

Carga mediante la API

Usa el endpoint de importación para subir archivos de transacciones.

Previsualiza antes de subir

Antes de confirmar un archivo para la ingesta, puedes previsualizarlo para verificar la detección de columnas y los datos de muestra. Esto ayuda a detectar problemas de mapeo de campos a tiempo.

cURL

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/preview" \
 -H "Authorization: Bearer $TOKEN" \
 -F "file=@bank_statement_january.csv" \
 -F "max_rows=5"

Respuesta

{
  "columns": ["transaction_id", "amount", "currency", "date", "reference"],
  "sampleRows": [
    ["BANK-2024-001", "1500.00", "USD", "2024-01-15", "Invoice #1234"],
    ["BANK-2024-002", "-250.00", "USD", "2024-01-15", "Service fee"]
  ],
  "rowCount": 2,
  "format": "csv"
}

Referencia de API: Previsualizar archivo

Carga de un solo archivo

cURL

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@bank_statement_january.csv"

Envía el campo format antes de la parte file. Si file llega primero, Matcher infiere el formato a partir de la extensión del nombre de archivo solo para .csv y .json. Matcher nunca infiere .xml, porque es una familia de formatos que cubre XML simple y camt.053. Envía el campo format explícito para XML. Matcher rechaza la carga sin él.

Matcher analiza y guarda el archivo completo dentro de la solicitud de carga. La carga devuelve 202 Accepted con el job terminado. Cuando la importación falla, Matcher responde con un error en lugar del job. Matcher lee una clave de idempotencia solo del header X-Idempotency, y solo cuando envías una. Una solicitud que lleva una clave solo en X-Idempotency-Key o Idempotency-Key se rechaza con 400 (MTCH-0015), y no se procesa nada. Una respuesta repetida lleva el header X-Idempotency-Replayed.

El límite de carga predeterminado es 1 GiB. Cuenta todo el cuerpo de la solicitud, con cada parte, header de parte y boundary, no solo el archivo.

Matcher rechaza una carga mayor que el límite de carga con 413 (MTCH-0010). Rechaza una carga que deja de enviar datos durante demasiado tiempo con 408 (MTCH-0311).

Referencia de API: Subir archivo

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "fileName": "bank_statement_january.csv",
  "totalRows": 1250,
  "persistedRows": 1250,
  "droppedDuplicateRows": 0,
  "flaggedDuplicateRows": 0,
  "reviewRows": 0,
  "failureRatePercent": 0,
  "completedWithErrors": false,
  "startedAt": "2024-01-20T10:30:00Z",
  "completedAt": "2024-01-20T10:30:45Z",
  "createdAt": "2024-01-20T10:30:00Z"
}

Consultar el estado de la importación

cURL

curl -X GET https://api.matcher.example.com/v1/imports/contexts/{contextId}/jobs/{jobId} \
 -H "Authorization: Bearer $TOKEN"

Referencia de API: Obtener el estado de la importación

Respuesta (en proceso)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "PROCESSING",
  "fileName": "bank_statement_january.csv",
  "startedAt": "2024-01-20T10:30:05Z"
}

Respuesta (completada)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "completedWithErrors": true,
  "fileName": "bank_statement_january.csv",
  "totalRows": 1250,
  "persistedRows": 1233,
  "droppedDuplicateRows": 12,
  "failedRows": 5,
  "failureRatePercent": 1,
  "reviewRows": 0,
  "diagnosis": "",
  "startedAt": "2024-01-20T10:30:05Z",
  "completedAt": "2024-01-20T10:30:45Z"
}

Los errores de análisis/normalización por fila no están incrustados en el job. Cuando completedWithErrors es true (o el job está en FAILED), obtén los detalles desde GET /v1/imports/contexts/{contextId}/jobs/{jobId}/errors (con un tope de 100 filas guardadas, con la contabilidad de totalErrors/truncated). Para un job FAILED por completo, diagnosis lleva un motivo seguro de una línea.

reviewRows cuenta las filas con external_id vacío que Matcher importa con estado PENDING_REVIEW. Esto ocurre cuando la fuente define blank_external_id como NEEDS_REVIEW en su config. Con el valor predeterminado, REJECT, un external_id vacío hace fallar la fila.

Valores de estado del job de importación

Estado	Descripción
`PROCESSING`	El archivo se está analizando y normalizando
`COMPLETED`	La importación terminó (revisa `completedWithErrors` para los fallos parciales)
`FAILED`	La importación se abortó por completo (consulta `diagnosis`)

Validación y manejo de errores

Matcher valida los archivos subidos en varias etapas.

Etapas de validación

Validación de formato

Verifica que el archivo sea CSV, JSON o XML válido con la estructura correcta.

Validación de esquema

Comprueba que los campos obligatorios estén presentes y coincidan con el mapa de campos configurado.

Validación de tipo de dato

Valida que los montos sean decimales válidos, que las fechas se puedan analizar y que las monedas sean códigos ISO válidos.

Errores de validación comunes

Cada error de fila lleva el número de fila, el campo cuando corresponde y un mensaje. Mensajes comunes:

Mensaje	Causa	Solución
`missing required field`	Un campo obligatorio está vacío en la fila	Completa el campo en el archivo de origen
`invalid decimal amount`	El monto no es un número válido	Busca símbolos de moneda o separadores de miles
`invalid date format`	La fecha no se puede analizar	Usa el formato ISO 8601 (YYYY-MM-DD)
`invalid ISO 4217 currency code`	El código de moneda no se reconoce	Usa códigos ISO 4217 (USD, EUR, BRL)

Manejo de errores

De forma predeterminada, Matcher importa las filas válidas aunque algunas filas tengan errores. Para que el job falle cuando las filas fallidas superan un porcentaje, define fail_on_error_rate_percent (de 1 a 99) en el config de la fuente.

Detección de duplicados

Matcher detecta y maneja automáticamente las transacciones duplicadas para evitar el doble conteo.

Cómo se detectan los duplicados

De forma predeterminada, una fila es duplicada cuando repite el external_id de una fila de la misma fuente, dentro de la misma carga o contra datos ya persistidos. Para detectar duplicados por otros campos, define duplicate_key en el config de la fuente. Su valor es una lista ordenada de nombres del mapeo de campos, como ["external_id", "amount"].

Opciones de manejo de duplicados

Define la clave duplicate_policy en el config de la fuente para controlar el manejo:

Política	Comportamiento
`FLAG_AS_EXCEPTION` (predeterminada)	Descarta la repetición y genera una excepción `DUPLICATE_TRANSACTION` sobre la transacción que sobrevive (el subconjunto de `droppedDuplicateRows` se informa como `flaggedDuplicateRows`)
`KEEP_FIRST`	Conserva la primera aparición y descarta las repeticiones en silencio, contadas en `droppedDuplicateRows`
`REJECT`	Convierte cada fila repetida en un error de fila de ingesta, contado en `failedRows`

Cuando duplicate_policy está ausente, aplica FLAG_AS_EXCEPTION.

Ver los detalles de los duplicados

El resumen de la importación muestra el número de duplicados:

{
  "totalRows": 1000,
  "persistedRows": 950,
  "droppedDuplicateRows": 50,
  "failedRows": 0,
  "failureRatePercent": 0
}

Cargas por lote

Para jobs de conciliación grandes, puedes subir varios archivos en secuencia.

Subir varios archivos

# Upload bank statement
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{bankSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@bank_january.csv"

# Upload ledger export
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{ledgerSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@ledger_january.csv"

Espera a que terminen todas las importaciones

Antes de ejecutar la coincidencia, confirma que todas las importaciones estén completas.

# List imports for context
curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/jobs" \
 -H "Authorization: Bearer $TOKEN"

Buscar transacciones subidas

Después de importar archivos, puedes buscar en todas las transacciones de un contexto para verificar la calidad de los datos o investigar registros específicos.

cURL

curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/transactions/search?q=Invoice&amount_min=1000&status=UNMATCHED" \
 -H "Authorization: Bearer $TOKEN"

Respuesta

{
  "items": [
    {
      "id": "019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
      "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amount": "1500.00",
      "currency": "USD",
      "date": "2024-01-15T00:00:00Z",
      "description": "Invoice #1234",
      "status": "UNMATCHED"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Referencia de API: Buscar transacciones

Entre los filtros admitidos están amount_min, amount_max, date_from, date_to, currency, source_id, status, la coincidencia exacta de external_id mediante el parámetro reference y la búsqueda de texto libre mediante el parámetro q.

Mejores prácticas

Valida los archivos antes de subirlos

Revisa el formato y la codificación del archivo en local antes de subirlo. Esto detecta los errores obvios más rápido.

# Check CSV is valid
head -5 transactions.csv

# Check encoding
file transactions.csv

Usa formatos de fecha consistentes

Estandariza el formato ISO 8601 (YYYY-MM-DD o YYYY-MM-DDTHH:MM:SSZ) en todas las fuentes para evitar problemas de análisis.

Incluye los IDs de transacción

Incluye siempre IDs de transacción únicos del sistema de origen. Esto habilita una detección de duplicados y unos registros de auditoría correctos.

Maneja los montos negativos de forma consistente

Decide una convención (negativo para débitos, positivo para créditos) y aplícala de forma consistente. Cuando un archivo marca débitos y créditos en una columna separada, mapea esa columna con la clave direction en su lugar.

Sube de forma incremental los archivos grandes

Para archivos de más de 50 MB, considera dividirlos en trozos más pequeños por rango de fechas. Esta es una recomendación de confiabilidad, no el límite de carga, y permite reintentos parciales.

Configura cargas automatizadas

Para la conciliación recurrente, automatiza las cargas de archivos con jobs programados.

# Example: Daily upload via cron
0 6 * * * /scripts/upload_bank_statement.sh

Próximos pasos

Revisar coincidencias

Conoce cómo interpretar los resultados de coincidencia y las puntuaciones de confianza.

Mapeo de campos

Configura cómo los campos de la fuente se mapean al esquema de Matcher.

Resumen

Guías

Console

Operaciones

Subir archivos

Formatos admitidos

Requisitos de estructura del archivo

Campos obligatorios

Campos opcionales

Columna de débito y crédito

Ejemplos de formato

CSV

JSON

XML

Carga mediante la API

Previsualiza antes de subir

Respuesta

Carga de un solo archivo

Respuesta

Consultar el estado de la importación

Respuesta (en proceso)

Respuesta (completada)

Valores de estado del job de importación

Validación y manejo de errores

Etapas de validación

Errores de validación comunes

Manejo de errores

Detección de duplicados

Cómo se detectan los duplicados

Opciones de manejo de duplicados

Ver los detalles de los duplicados

Cargas por lote

Subir varios archivos

Espera a que terminen todas las importaciones

Buscar transacciones subidas

Respuesta

Mejores prácticas

Próximos pasos

Revisar coincidencias

Mapeo de campos

​Formatos admitidos

​Requisitos de estructura del archivo

​Campos obligatorios

​Campos opcionales

​Columna de débito y crédito

​Ejemplos de formato

​CSV

​JSON

​XML

​Carga mediante la API

​Previsualiza antes de subir

​Respuesta

​Carga de un solo archivo

​Respuesta

​Consultar el estado de la importación

​Respuesta (en proceso)

​Respuesta (completada)

​Valores de estado del job de importación

​Validación y manejo de errores

​Etapas de validación

​Errores de validación comunes

​Manejo de errores

​Detección de duplicados

​Cómo se detectan los duplicados

​Opciones de manejo de duplicados

​Ver los detalles de los duplicados

​Cargas por lote

​Subir varios archivos

​Espera a que terminen todas las importaciones

​Buscar transacciones subidas

​Respuesta

​Mejores prácticas

​Próximos pasos

Revisar coincidencias

Mapeo de campos

Formatos admitidos

Requisitos de estructura del archivo

Campos obligatorios

Campos opcionales

Columna de débito y crédito

Ejemplos de formato

CSV

JSON

XML

Carga mediante la API

Previsualiza antes de subir

Respuesta

Carga de un solo archivo

Respuesta

Consultar el estado de la importación

Respuesta (en proceso)

Respuesta (completada)

Valores de estado del job de importación

Validación y manejo de errores

Etapas de validación

Errores de validación comunes

Manejo de errores

Detección de duplicados

Cómo se detectan los duplicados

Opciones de manejo de duplicados

Ver los detalles de los duplicados

Cargas por lote

Subir varios archivos

Espera a que terminen todas las importaciones

Buscar transacciones subidas

Respuesta

Mejores prácticas

Próximos pasos