Subir archivos

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:

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.

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 (.csv/.json/.xml). La subida devuelve 202 Accepted con el trabajo creado.

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

Validación de formato

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

Validación de esquema

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

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.

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

# Upload bank statement
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"

# Upload ledger export
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:

# 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 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.

# Check CSV is valid
head -5 transactions.csv

# Check encoding
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 muy grandes (>50MB), considera dividirlos en partes más pequeñas por rango de fechas. Esto mejora la confiabilidad y permite reintentos parciales.

Configura subidas automatizadas

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

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

Subir archivos

Formatos soportados

Requisitos de estructura de archivo

Campos requeridos

Campos opcionales

Ejemplos de formato

CSV

JSON

XML

Subir vía API

Previsualizar antes de subir

Respuesta

Subir un solo archivo

Respuesta

Verificar estado de importación

Respuesta (Procesando)

Respuesta (Completado)

Valores de estado del trabajo 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 detalles de duplicados

Cargas por lotes

Subir múltiples archivos

Esperar todas las importaciones

Buscar transacciones subidas

Respuesta

Mejores prácticas

Próximos pasos

Revisar conciliaciones

Mapeo de campos

​Formatos soportados

​Requisitos de estructura de archivo

​Campos requeridos

​Campos opcionales

​Ejemplos de formato

​CSV

​JSON

​XML

​Subir vía API

​Previsualizar antes de subir

​Respuesta

​Subir un solo archivo

​Respuesta

​Verificar estado de importación

​Respuesta (Procesando)

​Respuesta (Completado)

​Valores de estado del trabajo 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 detalles de duplicados

​Cargas por lotes

​Subir múltiples archivos

​Esperar todas las importaciones

​Buscar transacciones subidas

​Respuesta

​Mejores prácticas

​Próximos pasos

Revisar conciliaciones

Mapeo de campos

Formatos soportados

Requisitos de estructura de archivo

Campos requeridos

Campos opcionales

Ejemplos de formato

CSV

JSON

XML

Subir vía API

Previsualizar antes de subir

Respuesta

Subir un solo archivo

Respuesta

Verificar estado de importación

Respuesta (Procesando)

Respuesta (Completado)

Valores de estado del trabajo 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 detalles de duplicados

Cargas por lotes

Subir múltiples archivos

Esperar todas las importaciones

Buscar transacciones subidas

Respuesta

Mejores prácticas

Próximos pasos