# Cargar Importaciones por Lote a través de SFTP ## Descripción General La función de Importación por Lotes SFTP te permite cargar archivos CSV que contienen datos de pagos para automatizar la creación de clientes, métodos de pago y solicitudes de pago a gran escala. Esta es la misma funcionalidad de importación por lotes disponible a través del Portal del Comerciante y la API, pero con la conveniencia adicional de la automatización basada en archivos a través de SFTP. Esta función es ideal para: - **Flujos de trabajo automatizados**: Configura transferencias de archivos programadas desde tus sistemas - **Procesamiento de alto volumen**: Procesa miles de solicitudes de pago de manera eficiente - **Integración de sistemas**: Conecta tus procesos por lotes existentes sin integración de API - **Simplicidad operativa**: Usa clientes SFTP estándar en lugar de código API personalizado Habilitación de la Función Las Importaciones por Lotes SFTP deben estar habilitadas para tu cuenta de comerciante. Contacta al soporte de Belvo para solicitar acceso a esta función. Obtener Consentimiento del Usuario para Debitar Cuentas Antes de realizar cualquier solicitud de pago, debes: 1. Obtener el consentimiento explícito de tus usuarios, autorizándote a debitar fondos de sus cuentas. 2. Mantener evidencia documentada de este consentimiento. Para más información, consulta nuestra guía de Carga Masiva de Consentimientos vía SFTP. ## Cómo Funciona El proceso de importación por lotes SFTP refleja la función de Importación Masiva de Pagos por Débito Directo disponible en el Portal del Comerciante, con automatización basada en archivos: 1. **Subir CSV**: Subes un archivo CSV (usando el mismo formato que las cargas del portal) a tu directorio de entrada SFTP. 2. **Recogida Automática**: Belvo monitorea tu directorio de entrada y recoge nuevos archivos cada 15 minutos, de lunes a viernes. 3. **Procesamiento**: El sistema valida y procesa tu archivo, creando clientes, registrando métodos de pago y enviando solicitudes de pago. 4. **Retroalimentación**: Se genera un archivo de retroalimentación `.txt` en tu directorio de salida con los resultados del procesamiento. Webhooks y Acceso a la API El procesamiento de importación por lotes SFTP desencadena los mismos webhooks y actualiza los mismos recursos de la API que las importaciones por lotes basadas en el portal o la API. El archivo de retroalimentación SFTP es un mecanismo de notificación adicional, no un reemplazo para los webhooks. ## Requisitos previos Antes de cargar archivos de importación por lotes a través de SFTP, asegúrate de tener: 1. **Importaciones por lotes SFTP habilitadas** Contacta al soporte de Belvo para habilitar las importaciones por lotes SFTP para tu cuenta de comerciante. 2. **Credenciales de SFTP** Obtén tus credenciales de acceso SFTP del equipo de soporte de Belvo. Ten en cuenta que solo permitimos una cuenta SFTP por comerciante. 3. **Documentación de consentimiento** Asegúrate de haber obtenido y documentado el consentimiento de todos los clientes incluidos en tu importación por lotes. Puedes cargar los consentimientos utilizando la función de Carga masiva de consentimientos SFTP o la API de Consentimiento. 4. **Archivo CSV preparado** Prepara tu archivo CSV siguiendo el mismo formato utilizado para las cargas en el portal. Para especificaciones de campos, consulta la documentación de Plantillas de archivos de importación por lotes. ## Estructura de Directorios SFTP Tu cuenta SFTP tiene dos directorios dedicados para importaciones por lotes: ``` ├── {merchantId}/ │ ├── inbound/ │ │ └── batch_imports/ ← Sube archivos CSV aquí │ └── outbound/ │ └── batch_imports/ ← Los archivos de retroalimentación aparecen aquí ``` - **Directorio de Entrada** (`{merchantId}/inbound/batch_imports/`): Sube tus archivos CSV a este directorio. Los archivos deben seguir el mismo formato CSV utilizado en el Portal del Comerciante. - **Directorio de Salida** (`{merchantId}/outbound/batch_imports/`): Belvo escribe archivos de retroalimentación `.txt` aquí. **No** creas esta carpeta tú mismo—Belvo la provisiona. **Lees** o descargas desde el directorio de salida cuando los archivos están disponibles. Crea la carpeta de importaciones por lotes si es necesario Si `batch_imports/` no existe bajo `{merchantId}/inbound/`, **crea esa carpeta manualmente** en tu cliente SFTP antes de subir archivos. ## Especificaciones de Archivos ### Formato CSV Los archivos CSV para importación masiva deben seguir el mismo formato que las cargas del portal. Para la especificación completa de los campos, consulta la documentación de Plantillas de archivo de importación masiva. Crear Métodos de Pago en Masa Únicamente También puedes usar esta función para crear en masa clientes y métodos de pago sin realizar solicitudes de pago. Para hacer esto, omite los campos **Referencia Única cliente** e **Importe a cobrar** en tu CSV. ### Nombres de Archivos Puedes usar cualquier nombre de archivo válido para tus archivos CSV. Recomendamos usar nombres descriptivos que incluyan una fecha o un identificador de lote para tus propios fines de seguimiento. ``` Nombres de Archivos Válidos: ✅ payments_2026-04-08.csv ✅ batch_001.csv ✅ monthly_debits_april.csv ``` Objetos ignorados Los archivos vacíos, objetos de cero bytes y las entradas de marcador de posición de directorio bajo `batch_imports` son ignorados y no se procesan. ## Proceso de Carga 1. Conéctate a SFTP usando tu software preferido (por ejemplo, Cyberduck, FileZilla o herramientas de línea de comandos). Utiliza las credenciales proporcionadas por el equipo de soporte de Belvo. 2. Navega a tu directorio `{merchantId}/inbound/batch_imports/`. 3. Sube tu archivo CSV a este directorio. 4. Espera a que el archivo sea procesado. Belvo revisa tu directorio de entrada cada 15 minutos, de lunes a viernes. 5. Revisa el directorio `{merchantId}/outbound/batch_imports/` para encontrar un archivo de retroalimentación `.txt` con los resultados de tu procesamiento. Horario de Procesamiento Los archivos se recogen cada 15 minutos, de lunes a viernes. Los archivos subidos fuera del horario laboral o durante los fines de semana serán procesados el siguiente día hábil. Eliminación de Archivos Después de que un archivo es recogido para su procesamiento, Belvo intenta eliminarlo del directorio de entrada para prevenir un procesamiento duplicado. Si la eliminación tiene éxito, el mismo archivo no será recogido nuevamente. Si la eliminación falla (raro), el objeto puede seguir apareciendo en listados en una ejecución posterior y podría ser procesado nuevamente—contacta al soporte de Belvo o elimina o renombra el archivo manualmente si ves archivos obsoletos después de haber recibido retroalimentación. ## Archivos de Retroalimentación Después del procesamiento, se escribe un archivo de retroalimentación `.txt` bajo `{merchantId}/outbound/batch_imports/`. ### Nomenclatura de archivos de retroalimentación El nombre de salida se deriva del nombre de tu archivo CSV: se mantiene el nombre base y la extensión, **los puntos (`.`) en el nombre o la extensión se reemplazan por guiones bajos**, y se añade un **timestamp Unix en milisegundos**. La extensión siempre es `.txt`. Ejemplos: - `payments_2026-04-08.csv` → `payments_2026-04-08_csv_1775590260741.txt` - `batch.import.csv` → `batch_import_csv_.txt` Utiliza el timestamp (y tu registro de carga) para emparejar los archivos de retroalimentación con las cargas cuando se realicen varias ejecuciones en un corto período de tiempo. ### Cuándo se Genera la Retroalimentación - **Fallos de validación/preparación**: La retroalimentación de fallos se envía en esa ruta tan pronto como la importación por lotes no puede proceder (incluyendo cuando la validación falla antes de que exista un registro de lote). - **Ruta exitosa**: Después de que la validación pasa y el lote es **enviado para procesamiento**, la retroalimentación de éxito o fallo terminal se escribe solo cuando el lote alcanza un estado **terminal** (`processed` o `failed`). El sistema verifica nuevamente aproximadamente **cada minuto**, por lo que puede haber un retraso entre que el archivo desaparece de entrada y el `.txt` aparece en salida. ### Descripción del Formato - La primera línea siempre hace referencia al **nombre original del archivo CSV** e indica si fue **procesado exitosamente** o **no se pudo procesar**. - Cuando existe un registro de importación por lotes, la primera línea incluye `(batchImportId: )`. Si el procesamiento falla antes de que se cree un ID de lote, la primera línea **no** tiene ID de importación por lotes. - Las **filas omitidas** (solo en caso de éxito) se enumeran como **líneas similares a CSV** (con la misma estructura que los datos de la fila de importación masiva), no como resúmenes de “Fila N:”. - Los **errores** utilizan la misma estructura que los errores de validación de filas en el Portal del Comerciante: bloques numerados, mensajes con viñetas y una sección opcional `Fila:` con claves de campo y valores sensibles **enmascarados**. ### Retroalimentación de Éxito Cuando el lote termina con el estado `processed`, el cuerpo se ve así: ``` Ejemplo — éxito limpio Archivo payments_january.csv procesado exitosamente (batchImportId: 3f8e7d6c-5b4a-3210-fedc-ba9876543210). 0 fila(s) fueron omitidas. ``` Con filas omitidas: ``` Ejemplo — éxito con filas omitidas Archivo payments_january.csv procesado exitosamente (batchImportId: 3f8e7d6c-5b4a-3210-fedc-ba9876543210). 2 fila(s) fueron omitidas. Filas omitidas (2): RFC,ABCD123456ABC,john@example.com,John,Doe,+521234567890,****1234,ahorros,500,REF001,,mxn RFC,XYZW987654XYZ,jane@example.com,Jane,Smith,+529876543210,****5678,ahorros,250,REF002,,mxn ``` Valores enmascarados Las cuentas y otros campos sensibles aparecen **enmascarados** en la retroalimentación (por ejemplo, `****1234`), consistente con la experiencia de importación masiva en el Portal del Comerciante. ### Éxito con errores de fila tolerados Esta forma aparece solo cuando el lote **aún se completa como `processed`** pero algunas filas tuvieron problemas de validación tolerables. El título de la sección en el archivo es **`Rows with errors (tolerated)`**: ``` Ejemplo — procesado con errores de fila tolerados El archivo payments_january.csv se procesó exitosamente (batchImportId: 3f8e7d6c-5b4a-3210-fedc-ba9876543210). 1 fila(s) fueron omitidas. Filas omitidas (1): RFC,ABCD123456ABC,john@example.com,John,Doe,+521234567890,****1234,savings,500,REF001,,mxn Filas con errores (tolerados) (1): -- Error 1: * La longitud de accountNumber debe ser de 18 caracteres Fila: firstname: John lastname: Doe accountNumber: ****1234 amount: 500 ``` Si las reglas de validación causan que **todo el lote** falle (por ejemplo, tolerancia desactivada o demasiados errores), recibirás retroalimentación de **fallo** en su lugar, no esta plantilla de éxito. ### Retroalimentación de Fallos Cuando la preparación o el procesamiento terminal falla con errores estructurados: ``` Ejemplo — fallo con errores de validación El archivo payments_january.csv no pudo ser procesado (batchImportId: 3f8e7d6c-5b4a-3210-fedc-ba9876543210). Errores (2): -- Error 1: * email debe ser un correo electrónico Fila: email: not-a-valid-email amount: 50 currency: mxn firstname: Bad lastname: Email -- Error 2: * documentType debe ser uno de los siguientes valores: mx_rfc, mx_curp Fila: email: jane@example.com documentType: mx_xyz documentNumber: BADD141414NNN ``` Cuando aún no existe un ID de importación por lotes: ``` Ejemplo — fallo antes de que exista el ID de importación por lotes El archivo payments_january.csv no pudo ser procesado. Errores (1): -- Error 1: * email debe ser un correo electrónico Fila: email: invalid ... ``` ### Retroalimentación de error inesperado Cuando no hay una lista de errores estructurada (por ejemplo, un error de procesamiento inesperado), el archivo contiene solo el encabezado y una segunda línea fija: ``` Ejemplo — error inesperado El archivo payments_january.csv no pudo ser procesado (batchImportId: 3f8e7d6c-5b4a-3210-fedc-ba9876543210). Debido a un error inesperado. ``` Si no se creó ningún lote, la primera línea es `El archivo .csv no pudo ser procesado.` sin `(batchImportId: ...)`, seguida de una línea en blanco y `Debido a un error inesperado.` ## Ciclo de Vida de Importación por Lotes Las importaciones por lotes subidas a través de SFTP siguen el mismo ciclo de vida que las cargas del portal: | Estado | Descripción | | --- | --- | | `validating` | El archivo está siendo validado para detectar errores de formato y contenido. | | `failed` | El archivo tiene errores críticos y no puede ser procesado. Revisa el archivo de retroalimentación para más detalles. | | `ready_to_send` | La validación fue exitosa. Para las cargas SFTP, el procesamiento continúa automáticamente. | | `processing` | Se están creando clientes, métodos de pago y solicitudes de pago. | | `processed` | Procesamiento completo. Revisa el archivo de retroalimentación para ver los resultados, incluyendo cualquier fila omitida. | Procesamiento Automático A diferencia de las cargas del portal donde debes hacer clic manualmente en "Enviar" después de la validación, las cargas SFTP se envían automáticamente para su procesamiento una vez que la validación es exitosa. ## Solución de problemas ### Archivo no aparece en el directorio de salida | Causa | Solución | | --- | --- | | El archivo aún está siendo procesado | Espera al menos 30 minutos después de la carga. El procesamiento puede tardar más para archivos grandes. | | Archivo cargado fuera del horario de procesamiento | Los archivos se procesan solo de lunes a viernes. Espera hasta el siguiente día hábil. | | El lote aún está procesando solicitudes de pago | Para los lotes que pasan la validación, se genera retroalimentación solo después de que el lote alcanza el estado `processed` o `failed`. | | El archivo fue cargado en el directorio incorrecto | Verifica que hayas cargado en `{merchantId}/inbound/batch_imports/` (no en `bulk-consents`). | ### El archivo permanece en el directorio de entrada En casos raros, un archivo puede permanecer en el directorio de entrada después del procesamiento porque la eliminación falló. Ese objeto podría ser recogido nuevamente en una ejecución posterior. Si ya recibiste retroalimentación para esa carga, contacta al soporte de Belvo o elimina o renombra el archivo manualmente. Si no estás seguro, verifica el estado del lote a través de la API o el Portal del Comerciante antes de volver a cargar. ### Errores comunes de validación Para errores comunes de validación de CSV y sus soluciones, consulta la sección de Solución de problemas y Preguntas Frecuentes en la documentación de Importación Masiva. ## Mejores Prácticas ### Antes de Subir 1. **Valida tu CSV localmente** - Asegúrate de que todos los campos requeridos estén presentes - Verifica que los números CLABE tengan 18 dígitos - Comprueba que las direcciones de correo electrónico sean válidas - Confirma que los tipos de ID sean `mx_curp` o `mx_rfc` 2. **Prueba con lotes pequeños primero** - Sube un archivo con unas pocas filas para verificar que tu formato sea correcto - Revisa el archivo de retroalimentación antes de subir lotes grandes 3. **Asegúrate de que los consentimientos estén en su lugar** - Todos los clientes deben haber confirmado los consentimientos antes de que se creen las solicitudes de pago - Usa la función SFTP Bulk Upload Consents para subir documentos de consentimiento ### Durante la Carga 1. **Usa nombres de archivo descriptivos** - Incluye fechas o identificadores de lote para facilitar el seguimiento - Mantén un registro local de los archivos cargados 2. **Evita cargas duplicadas** - Espera comentarios antes de cargar los mismos datos nuevamente - Usa referencias únicas para cada solicitud de pago ### Después de la Carga 1. **Monitorea los archivos de retroalimentación** - Revisa tu directorio de salida regularmente - Revisa las filas omitidas y los errores de manera oportuna 2. **Rastrea mediante webhooks** - Configura listeners de webhook para eventos de importación por lotes - Usa la API para verificar el estado del lote y obtener información detallada 3. **Mantén registros de auditoría** - Archiva los archivos de retroalimentación para cumplimiento - Documenta cualquier error y sus resoluciones ## Próximos pasos Después de configurar las importaciones por lotes SFTP: - Revisa las especificaciones de campos CSV para asegurarte de que tus archivos estén correctamente formateados. - Configura escuchas de webhooks para recibir notificaciones en tiempo real sobre tus importaciones por lotes. - Utiliza la función de Exportaciones de Pagos para conciliar los pagos procesados.