Subir archivos

Importa datos de transacciones a Matcher desde archivos CSV, JSON o XML usando la estructura de campos compatible y las reglas de ingesta.

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

​

Formatos soportados

---

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

• CSV: Valores separados por comas con encabezados. Más común para exportaciones bancarias.
• JSON: Array de objetos de transacción. Mejor para integraciones de API.
• XML: Elementos estructurados. Común para sistemas empresariales.

Además de estos, el endpoint de subida 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 de archivo

---

Cada archivo debe contener registros de transacciones con campos que puedan mapearse al esquema interno de Matcher.

​

Campos requeridos

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

Campo	Tipo	Descripción
transaction_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
reference	String	Referencia externa o descripción
counterparty	String	Otra parte en la transacción
type	String	Tipo de transacción (crédito, débito, etc.)
metadata	Object	Campos personalizados adicionales

​

Ejemplos de formato

---

​

CSV

Requisitos de CSV:

• La primera fila debe ser encabezados de columna
• Codificación UTF-8
• Delimitador de coma (configurable)
• Encerrar entre comillas los campos que contengan 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:

• El elemento raíz debe ser un array
• Nombres de campos consistentes entre objetos
• Codificación UTF-8

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 válido con declaración
• Elemento raíz que contenga elementos de transacción
• Codificación UTF-8

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>

​

Subir vía API

---

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

​

Previsualizar antes de subir

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

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 la API: Preview file

​

Subir 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, el formato se infiere de la extensión del nombre de archivo solo para .csv y .json; .xml nunca se infiere (es una familia de formatos — XML plano, camt.053 — por lo que el campo format explícito es obligatorio; de lo contrario la subida se rechaza). La subida devuelve 202 Accepted con el trabajo creado.

El límite de subida predeterminado es de 1 GiB y se aplica a toda la solicitud multipart, incluidas todas las partes, cabeceras y delimitadores, no solo al archivo. Puedes configurar ingestion.max_upload_bytes entre 1 MiB y 8 GiB.

Referencia de la API: Upload file

​

Respuesta

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

​

Verificar estado de importación

cURL

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

Referencia de la API: Get import status

​

Respuesta (Procesando)

{
  "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",
  "totalRows": 1250,
  "startedAt": "2024-01-20T10:30:05Z"
}

​

Respuesta (Completado)

{
  "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 parseo/normalización por fila no se incluyen en el trabajo. Cuando completedWithErrors es true (o el trabajo está FAILED), obtén los detalles desde GET /v1/imports/contexts/{contextId}/jobs/{jobId}/errors (limitado a 100 filas almacenadas, con conteo de totalErrors/truncated). Para un trabajo completamente FAILED, diagnosis incluye una razón segura de una sola línea.

​

Valores de estado del trabajo de importación

Estado	Descripción
QUEUED	Trabajo recibido, esperando un worker
PROCESSING	El archivo está siendo analizado y normalizado
COMPLETED	Importación finalizada (verifica completedWithErrors para fallas parciales)
FAILED	Importación abortada por completo (ver diagnosis)

​

Validación y manejo de errores

---

Matcher valida los archivos subidos en múltiples etapas.

​

Etapas de validación

1. Validación de formato

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

2. Validación de esquema

   Comprueba que los campos requeridos están presentes y coinciden con el mapeo de campos configurado.

3. Validación de tipo de datos

   Valida que los montos son decimales válidos, las fechas son parseables, las monedas son códigos ISO válidos.

4. Validación de reglas de negocio

   Aplica reglas específicas del contexto como rangos de fechas, límites de monto, etc.

​

Errores de validación comunes

Error	Causa	Solución
INVALID_FORMAT	El archivo no puede ser parseado	Verificar codificación y estructura del archivo
MISSING_REQUIRED_FIELD	Campo requerido no encontrado	Verificar configuración de mapeo de campos
INVALID_AMOUNT	Monto no es un número válido	Verificar símbolos de moneda o comas en números
INVALID_DATE	Fecha no puede ser parseada	Usar formato ISO 8601 (YYYY-MM-DD)
UNKNOWN_CURRENCY	Código de moneda no reconocido	Usar códigos ISO 4217 (USD, EUR, BRL)
DATE_OUT_OF_RANGE	Fecha antes/después del rango permitido	Verificar límites de fecha del contexto

​

Manejo de errores

Por defecto, las filas válidas se importan aunque algunas filas tengan errores. Configura el comportamiento de manejo de errores a través de la configuración del contexto o maneja los errores después de completar la importación revisando la respuesta del estado del trabajo.

​

Detección de duplicados

---

Matcher detecta y maneja automáticamente transacciones duplicadas para prevenir doble conteo.

​

Cómo se detectan los duplicados

Los duplicados se identifican por la clave de deduplicación de la fila dentro de una fuente:

• source_id
• external_id (el identificador de transacción del sistema fuente)

Si una fila repite esa clave —dentro de la misma subida o contra datos ya persistidos— se trata como duplicado.

​

Opciones de manejo de duplicados

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

Política	Comportamiento
KEEP_FIRST (por defecto)	Conserva la primera ocurrencia y descarta silenciosamente las repeticiones, contadas en droppedDuplicateRows
REJECT	Convierte cada fila repetida en un error de fila de ingesta, contado en failedRows
FLAG_AS_EXCEPTION	Descarta la repetición y genera una excepción DUPLICATE_TRANSACTION en la transacción sobreviviente (subconjunto reportado como flaggedDuplicateRows)

Cuando la clave está ausente, se aplica KEEP_FIRST.

​

Ver detalles de duplicados

El resumen de importación muestra cuántos duplicados se encontraron:

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

​

Cargas por lotes

---

Para trabajos de conciliación grandes, puedes subir múltiples archivos en secuencia.

​

Subir múltiples archivos

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

# Subir exportación del libro mayor
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{ledgerSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "file=@ledger_january.csv" \
 -F "format=csv"

​

Esperar todas las importaciones

Antes de ejecutar la conciliación, asegúrate de que todas las importaciones estén completas:

# Listar importaciones del contexto
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 entre 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 la API: Search transactions

Los filtros soportados incluyen amount_min, amount_max, date_from, date_to, currency, source_id, status y búsqueda de texto libre mediante el parámetro q.

​

Mejores prácticas

---

Valida archivos antes de subir

Verifica formato y codificación del archivo localmente antes de subir. Esto detecta errores obvios más rápido.

# Comprobar que el CSV sea válido
head -5 transactions.csv

# Comprobar la codificación
file transactions.csv

Usa formatos de fecha consistentes

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

Incluye IDs de transacción

Siempre incluye IDs de transacción únicos del sistema fuente. Esto permite detección adecuada de duplicados y trazabilidad de auditoría.

Maneja montos negativos consistentemente

Decide una convención (negativo para débitos, positivo para créditos) y aplícala consistentemente. Documenta esto en tu mapeo de campos.

Sube incrementalmente para archivos grandes

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

Configura subidas automatizadas

Para conciliación recurrente, automatiza las subidas de archivos usando trabajos programados o webhooks desde sistemas fuente.

# Ejemplo: subida diaria mediante cron
0 6 * * * /scripts/upload_bank_statement.sh

​

Próximos pasos

---

Revisar conciliaciones

Aprende a interpretar resultados de conciliación y puntajes de confianza.

Mapeo de campos

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