Cargar Importaciones por Lote a través de SFTP
Copiar para LLM
Copiar página como Markdown para LLMs
Ver como Markdown
Abrir esta página como Markdown
Abrir en ChatGPT
Obtener información de ChatGPT
Abrir en Claude
Obtener información de Claude
Conectar a Cursor
Instalar servidor MCP en Cursor
Conectar a VS Code
Instalar servidor MCP en VS Code

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:

Obtener el consentimiento explícito de tus usuarios, autorizándote a debitar fondos de sus cuentas.
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:

Subir CSV: Subes un archivo CSV (usando el mismo formato que las cargas del portal) a tu directorio de entrada SFTP.
Recogida Automática: Belvo monitorea tu directorio de entrada y recoge nuevos archivos cada 15 minutos, de lunes a viernes.
Procesamiento: El sistema valida y procesa tu archivo, creando clientes, registrando métodos de pago y enviando solicitudes de pago.
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:

Importaciones por lotes SFTP habilitadas
Contacta al soporte de Belvo para habilitar las importaciones por lotes SFTP para tu cuenta de comerciante.
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.
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.
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

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.
Navega a tu directorio {merchantId}/inbound/batch_imports/.
Sube tu archivo CSV a este directorio.
Espera a que el archivo sea procesado. Belvo revisa tu directorio de entrada cada 15 minutos, de lunes a viernes.
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_<timestamp>.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: <uuid>). 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 <name>.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

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

Usa nombres de archivo descriptivos
- Incluye fechas o identificadores de lote para facilitar el seguimiento
- Mantén un registro local de los archivos cargados
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

Monitorea los archivos de retroalimentación
- Revisa tu directorio de salida regularmente
- Revisa las filas omitidas y los errores de manera oportuna
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
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.