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 campos que contengan comas o saltos de línea entre comillas

Ejemplo de código

 transaction_id,amount,currency,date,reference,type
 BANK-2024-001,1500.00,USD,2024-01-15,Factura #1234,credit
 BANK-2024-002,-250.00,USD,2024-01-15,Cuota de servicio,debit
 BANK-2024-003,3200.50,USD,2024-01-16,Pago de cliente,credit
 BANK-2024-004,-89.99,USD,2024-01-16,Suscripción,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": "Factura #1234",
    "type": "credit"
  },
  {
    "transaction_id": "BANK-2024-002",
    "amount": -250.0,
    "currency": "USD",
    "date": "2024-01-15",
    "reference": "Cuota de servicio",
    "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>Factura #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>Cuota de servicio</reference>
      <type>debit</type>
      </transaction>
  </transactions>

Subir vía API

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

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 "file=@extracto_bancario_enero.csv" \
 -F "format=csv"

Referencia de la API: Subir archivo

Respuesta

{
  "job_id": "{jobId}",
  "status": "QUEUED",
  "context_id": "{contextId}",
  "source_id": "{sourceId}",
  "file_name": "extracto_bancario_enero.csv",
  "file_size_bytes": 15420,
  "created_at": "2024-01-20T10:30:00Z"
}

Verificar estado de importación

cURL

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

Referencia de la API: Obtener estado de importación

Respuesta (Procesando)

{
  "job_id": "{jobId}",
  "status": "PROCESSING",
  "progress": {
    "total_rows": 1250,
    "processed_rows": 800,
    "valid_rows": 795,
    "invalid_rows": 5,
    "duplicate_rows": 12
  },
  "started_at": "2024-01-20T10:30:05Z"
}

Respuesta (Completado)

{
  "job_id": "{jobId}",
  "status": "COMPLETED",
  "summary": {
    "total_rows": 1250,
    "imported": 1233,
    "duplicates_skipped": 12,
    "validation_errors": 5
  },
  "errors": [
    {
      "row": 45,
      "field": "amount",
      "error": "Formato decimal inválido"
    },
    {
      "row": 89,
      "field": "date",
      "error": "Fecha anterior al mínimo permitido"
    },
    {
      "row": 234,
      "field": "currency",
      "error": "Código de moneda desconocido: XXX"
    }
  ],
  "started_at": "2024-01-20T10:30:05Z",
  "completed_at": "2024-01-20T10:30:45Z"
}

Valores de estado del trabajo de importación

Estado	Descripción
`QUEUED`	Trabajo recibido, esperando para iniciar
`PROCESSING`	El archivo está siendo analizado y validado
`COMPLETED`	Importación finalizada exitosamente
`FAILED`	Importación falló (verificar errores)
`CANCELLED`	Importación fue cancelada

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 calculando un hash de campos clave:

transaction_id
source_id
amount
currency
date

Si una transacción con el mismo hash ya existe en el sistema, se marca como duplicada.

Opciones de manejo de duplicados

Opción	Comportamiento
`skip` (por defecto)	Las filas duplicadas se omiten, datos existentes sin cambios
`replace`	Las filas duplicadas reemplazan transacciones existentes
`error`	La importación falla si se encuentran duplicados

Configura el comportamiento de manejo de duplicados a través de la configuración del contexto o la fuente.

Ver detalles de duplicados

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

{
  "summary": {
    "total_rows": 1000,
    "imported": 950,
    "duplicates_skipped": 50,
    "validation_errors": 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=@banco_enero.csv" \
 -F "format=csv"

# Subir exportación del libro contable
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{ledgerSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "file=@libro_enero.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 para el contexto
curl -X GET "https://api.matcher.example.com/v1/imports?context_id={contextId}&status=PROCESSING" \
 -H "Authorization: Bearer $TOKEN"

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.

# Verificar que CSV es válido
head -5 transacciones.csv

# Verificar codificación
file transacciones.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.

# Ejemplo: Subida diaria vía cron
0 6 * * * /scripts/upload_extracto_bancario.sh

Introduction

Primeros pasos

Configuración

Reconciliación diaria

Integraciones

Referencia

Subir archivos

Formatos soportados

Requisitos de estructura de archivo

Campos requeridos

Campos opcionales

Ejemplos de formato

CSV

JSON

XML

Subir vía API

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

Mejores prácticas

Próximos pasos

Revisar conciliaciones

Mapeo de campos

Introduction

Primeros pasos

Configuración

Reconciliación diaria

Integraciones

Referencia

​Formatos soportados

​Requisitos de estructura de archivo

​Campos requeridos

​Campos opcionales

​Ejemplos de formato

​CSV

​JSON

​XML

​Subir vía API

​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

​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

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

Mejores prácticas

Próximos pasos