> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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: * **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** ```csv theme={null} 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** ```json theme={null} [ { "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 theme={null} BANK-2024-001 1500.00 USD 2024-01-15 Invoice #1234 credit BANK-2024-002 -250.00 USD 2024-01-15 Service fee debit ``` ## 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. ```bash cURL theme={null} 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 ```json theme={null} { "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](/es/reference/matcher/preview-upload) ### Subir un solo archivo ```bash cURL theme={null} 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](/es/reference/matcher/upload-transaction-file) #### Respuesta ```json theme={null} { "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 ```bash cURL theme={null} 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](/es/reference/matcher/retrieve-ingestion-job) #### Respuesta (Procesando) ```json theme={null} { "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) ```json theme={null} { "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 Verifica que el archivo es CSV, JSON o XML válido con estructura correcta. Comprueba que los campos requeridos están presentes y coinciden con el mapeo de campos configurado. Valida que los montos son decimales válidos, las fechas son parseables, las monedas son códigos ISO válidos. 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: ```json theme={null} { "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 ```bash theme={null} # 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: ```bash theme={null} # 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. ```bash cURL theme={null} 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 ```json theme={null} { "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](/es/reference/matcher/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 *** Verifica formato y codificación del archivo localmente antes de subir. Esto detecta errores obvios más rápido. ```bash theme={null} # Check CSV is valid head -5 transactions.csv # Check encoding file transactions.csv ``` Estandariza en formato ISO 8601 (`YYYY-MM-DD` o `YYYY-MM-DDTHH:MM:SSZ`) en todas las fuentes para evitar problemas de parseo. Siempre incluye IDs de transacción únicos del sistema fuente. Esto permite detección adecuada de duplicados y trazabilidad de auditoría. Decide una convención (negativo para débitos, positivo para créditos) y aplícala consistentemente. Documenta esto en tu mapeo de campos. 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. Para conciliación recurrente, automatiza las subidas de archivos usando trabajos programados o webhooks desde sistemas fuente. ```bash theme={null} # Example: Daily upload via cron 0 6 * * * /scripts/upload_bank_statement.sh ``` ## Próximos pasos *** Aprende a interpretar resultados de conciliación y puntajes de confianza. Configura cómo los campos de origen se mapean al esquema de Matcher.