# Carga Masiva de Consentimientos a través de SFTP

## Descripción general

La función de carga masiva de consentimientos por SFTP te permite subir múltiples documentos de consentimiento a gran escala sin usar la API para cada archivo individual. Esto es ideal para:

- **Cargas de alto volumen**: Procesa cientos o miles de documentos de consentimiento de manera eficiente
- **Operaciones por lotes**: Sube múltiples archivos simultáneamente
- **Integración simplificada**: Usa clientes SFTP estándar en lugar de integración con API
- **Flujos de trabajo automatizados**: Configura transferencias de archivos automatizadas desde tus sistemas


Después de que tus documentos de consentimiento sean subidos y confirmados, puedes proceder a realizar Solicitudes de Pago para debitar las cuentas de tus clientes.

Obtén el Consentimiento de tu Cliente
Asegúrate de tener el consentimiento adecuado de los clientes antes de subir sus documentos:

- Permiso explícito para procesar sus documentos de identidad.
- Acuerdo con los términos de pago por débito directo.
- Cumplimiento con las regulaciones de privacidad locales.


## Flujo

El proceso de carga masiva funciona de la siguiente manera:

1. **Subir Archivos**: Subes documentos de consentimiento a tu directorio SFTP dedicado.
2. **Procesamiento Automático**: Nuestro sistema monitorea tu directorio y procesa nuevos archivos cada 15 minutos. Los pasos de procesamiento incluyen:
  - **Validación**: Cada archivo se valida en cuanto a nombre, tamaño y contenido.
  - **Creación de Consentimiento**: Los archivos se vinculan automáticamente a métodos de pago y consentimientos existentes.
3. **Retroalimentación**: Recibes mensajes de confirmación o error en tu directorio de salida.


## Requisitos previos

Antes de cargar archivos de consentimiento a través de SFTP, debes:

1. **Crear registros de clientes y registrar métodos de pago**
Debes tener los clientes y sus métodos de pago asociados registrados en la plataforma de Belvo antes de realizar la operación de consentimiento masivo por SFTP. Recomendamos usar nuestra función de Importación Masiva de Pagos por Débito Directo para crear automáticamente clientes y métodos de pago en masa. En la carga inicial, puedes omitir los campos *Referencia Única cliente* e *Importe a cobrar*, ya que no son necesarios para la creación de Clientes y Métodos de Pago.
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.


## Estructura de Directorios SFTP

Tu cuenta SFTP tiene dos directorios dedicados:


```
├── inbound/
│   └── bulk-consents/     ← Sube los documentos de consentimiento aquí
└── outbound/
    └── bulk-consents/     ← Los mensajes de retroalimentación aparecen aquí
```

- **Directorio Inbound**: Sube tus documentos de consentimiento al directorio `inbound/bulk-consents/`, de acuerdo con las convenciones de nomenclatura y especificaciones descritas a continuación.
- **Directorio Outbound**: Los archivos procesados y los mensajes de retroalimentación estarán disponibles en el directorio `outbound/bulk-consents/`.


## Especificaciones de Archivos

Para que las cargas de tus documentos de consentimiento sean aceptadas, deben cumplir con las siguientes especificaciones:

### Convención de Nombres de Archivos

Todos los archivos subidos **deben** seguir este patrón de nomenclatura exacto:


```
Patrón de Nomenclatura:
consent_<idDocumentType>_<idDocumentNumber>_<accountNumber>_<documentType>.<extension>

Nombres de Archivos Válidos:
✅ consent_mx_rfc_ABCD123456_012345678901234567_id_front.pdf
✅ consent_mx_curp_XYZ789012_987654321098765432_id_back.png
✅ consent_mx_rfc_DOC123456_111122223333444455_selfie.jpg
✅ consent_mx_curp_TEST789_666677778888999900_contract.pdf

Nombres de Archivos Inválidos:
❌ invoice_ABCD123456_012345678901234567_id_front.pdf -> (Prefijo incorrecto - debe ser "consent_")
❌ consent_ABCD_id_front.pdf -> (Falta el número de cuenta)
❌ consent_ABCD_1234_document.pdf -> (Tipo de documento inválido - debe ser uno de: id_front, id_back, selfie, contract)
❌ consent_ABCD_1234_id_front -> (Falta la extensión del archivo)
❌ consent_mx_rfc_ABCD123456_12AB_id_front.pdf -> (El número de cuenta debe ser solo numérico)
```

| Componente | Descripción | Formato | Ejemplo |
|  --- | --- | --- | --- |
| `consent` | Siempre debe comenzar con `consent`. | Minúsculas | `consent` |
| `idDocumentType` | El tipo de documento. Puede ser uno de: `mx_rfc` o `mx_curp`. | Minúsculas | `mx_rfc` |
| `idDocumentNumber` | El número de documento correspondiente para el `idDocumentType` (RFC o CURP). | Alfanumérico | `ABCD123456` |
| `accountNumber` | El número de cuenta bancaria del cliente (CLABE). | Solo numérico | `012345678901234567` |
| `documentType` | El tipo de documento de consentimiento. Para más información sobre el propósito de cada tipo de documento, ver [Tipos de Documentos de Consentimiento](#consent-document-types). | Debe ser uno de: `id_front`, `id_back`, `selfie`, `contract` | `id_front` |
| `extension` | La extensión del archivo. Por ejemplo, `.pdf`, `.png`, o `.jpg` | `.pdf`, `.png`, o `.jpg` | `.pdf` |


### Tipos de Documentos de Consentimiento

Los cuatro documentos deben ser cargados para que el consentimiento sea enviado para revisión. Puedes cargarlos en cualquier orden o todos a la vez.

Para cada cliente, debes cargar cuatro archivos de documentos de consentimiento:

| documentType | Descripción | Propósito |
|  --- | --- | --- |
| `id_front` | La parte frontal de la identificación de un cliente. | Verificación de identidad |
| `id_back` | La parte trasera de la identificación de un cliente. | Verificación de identidad |
| `selfie` | La foto selfie del cliente. | Verificación de vivacidad |
| `contract` | El acuerdo de consentimiento firmado por el cliente. | Documentación de autorización |


### Límites de Tamaño de Archivo

Cada archivo subido debe cumplir con las siguientes restricciones de tamaño:

- **Tamaño mínimo**: 100 bytes
- **Tamaño máximo**: 20 MB por archivo


Si tus archivos superan los 20 MB, comprime o redimensiona las imágenes antes de subirlas. Para PDFs, considera reducir la calidad de las imágenes.

### Formatos de Archivo Soportados

- **PDF**: `.pdf` (recomendado para contratos)
- **PNG**: `.png` (recomendado para identificaciones y selfies)
- **JPEG**: `.jpg` (aceptable para todos los tipos de documentos)


### Recomendaciones de Calidad de Imagen

- **Resolución**: Mínimo 300 DPI para documentos de identificación
- **Claridad**: Asegúrate de que el texto sea legible y las fotos sean claras
- **Orientación**: Las imágenes deben estar correctamente orientadas (no rotadas)
- **Color**: Se prefieren imágenes a color sobre blanco y negro


## Proceso de Carga

Requisitos Previos
Antes de comenzar el proceso de carga, asegúrate de que:

- Has creado los clientes relevantes y los métodos de pago relacionados.
- Has nombrado los archivos de acuerdo con la convención de nombres.
- Has verificado que los tamaños de los archivos están dentro de los límites.
- Has comprobado que los formatos de archivo son compatibles.
- Tienes tus credenciales de SFTP listas.


1. Conéctate a SFTP usando tu software preferido (por ejemplo, Cyberduck). Usa las credenciales proporcionadas por el equipo de soporte de Belvo.
2. Navega al directorio `inbound/bulk-consents/`.
3. Sube tus archivos de documentos de consentimiento a este directorio.
4. Espera a que los archivos sean procesados. Nuestro sistema revisa tu directorio `inbound` cada 15 minutos en busca de nuevos archivos. Cada lote de archivos tarda aproximadamente 30 minutos en procesarse, dependiendo del volumen.
5. Revisa el directorio `outbound/bulk-consents/` para encontrar archivos de retroalimentación que indiquen éxito o errores para cada archivo cargado.


Notificaciones de Webhook
Además de recibir archivos de retroalimentación en el directorio `outbound/bulk-consents/`, Belvo también enviará notificaciones de webhook sobre el estado de tus documentos de consentimiento cargados. Para obtener detalles sobre qué notificaciones de webhook se envían en cada etapa del ciclo de vida del consentimiento, consulta la sección [Ciclo de Vida del Consentimiento](#consent-lifecycle) a continuación.

## Después de la Carga

Después de cargar tus documentos de consentimiento, necesitas verificar los archivos de retroalimentación en el directorio de salida (`outbound/bulk-consents/`) para confirmar si las cargas fueron exitosas o si hubo algún error. Necesitarás abrir cada archivo de retroalimentación para ver los resultados del procesamiento.

Los nombres de los archivos en el directorio de salida coincidirán con los archivos cargados, por ejemplo:


```text Nombre de Archivo de Retroalimentación de Ejemplo
consent_mx_rfc_ABCD123456_012345678901234567_id_front_pdf.txt
```

#### Cargas Exitosas

Para las cargas de archivos exitosas (el archivo fue aceptado y vinculado a un ID de consentimiento), el archivo de retroalimentación contendrá la siguiente información:


``` Contenido de Ejemplo de Archivo de Retroalimentación Exitoso
File 120890e5-21fd-47d1-bba1-3f2a6a1fe6d2/inbound/bulk-consents/consent_mx_rfc_ABCD123456_012345678901234567_id_front.pdf successfully stored for consent 2455bbd7-1b12-4195-8de0-121c10268886.
```

#### Cargas no exitosas

Para las cargas no exitosas, el archivo de retroalimentación detallará las razones del rechazo. Por ejemplo:


``` Contenido de ejemplo de archivo de retroalimentación no exitoso
Archivo consent_mx_rfc_ABCD123456_012345678901234567_id_front.pdf rechazado porque:
* originalFilename debe comenzar con "consent_"
* accountNumber debe ser numérico
```

En este caso, necesitarás corregir los problemas mencionados y volver a cargar el archivo.

### Errores Comunes

#### Errores de Nomenclatura de Archivos

##### `originalFilename must start with "consent_"`

- **Causa**: El nombre del archivo no comienza con "consent_"
- **Solución**: Renombrar el archivo para que comience con el prefijo "consent_"


##### `accountNumber must be numeric`

- **Causa**: El número de cuenta contiene letras o caracteres especiales
- **Solución**: Asegúrate de que el número de cuenta contenga solo dígitos (por ejemplo, número CLABE)


##### `consentDocumentType debe ser uno de los siguientes valores: id_front, id_back, selfie, contract`

- **Causa**: Tipo de documento inválido en el nombre del archivo
- **Solución**: Usa solo: `id_front`, `id_back`, `selfie`, o `contract`


##### `extension must be one of the following values: pdf, png, jpg`

- **Causa**: Formato de archivo no compatible
- **Solución**: Convertir el archivo a formato PDF, PNG o JPG


### Errores de Tamaño de Archivo

##### `El tamaño del archivo debe ser como máximo 20000000 bytes (20 MB)`

- **Causa**: El archivo excede el límite máximo de tamaño
- **Solución**: Comprimir o redimensionar el archivo a menos de 20 MB


##### `El tamaño del archivo debe ser al menos de 100 bytes`

- **Causa**: El archivo está vacío o dañado
- **Solución**: Asegúrate de que el archivo contenga contenido real y no esté dañado


### Errores de Método de Pago

##### `método de pago no encontrado para la cuenta y cliente dados`

- **Causa**: No existe un método de pago que coincida con el número de documento y número de cuenta
- **Solución**:
  1. Verifica que `idDocumentNumber` coincida exactamente con el registro de tu cliente.
Puedes usar la solicitud de API Listar todos los clientes, utilizando el número de documento o nombre en el parámetro de consulta `search`.
  2. Verifica que el método de pago fue creado (usando nuestra API). Crea el método de pago si no existe.
Puedes usar Listar todos los métodos de pago, utilizando el parámetro de consulta `customer_id` para ver todos los métodos de pago creados para el cliente. Si no existe un método de pago, utiliza la solicitud de API Crear un método de pago para crear un nuevo método de pago para el cliente.
  3. Confirma que `accountNumber` coincida exactamente con el método de pago.


### Errores de Procesamiento de Archivos

##### Archivo no aparece en el directorio de salida después de más de 30 minutos

**Posibles causas y soluciones**:

| Causa | Solución |
|  --- | --- |
| El archivo aún está en cola para procesamiento | Espere al menos 30 minutos antes de verificar |
| El nombre del archivo no coincide con la convención | Verifique que el nombre del archivo siga la convención exacta |
| El archivo fue subido al directorio incorrecto | Verifique que haya subido al directorio de entrada correcto |


Si los archivos no aparecen después de 60 minutos, por favor contacte al soporte de Belvo.

## Mejores Prácticas

A continuación se presentan algunas mejores prácticas para asegurar un proceso fluido de carga masiva de consentimientos a través de SFTP.

### Antes de Subir

1. **Validar Datos Primero**
  - Asegúrate de que los clientes existan en el sistema.
  - Verifica que los métodos de pago estén registrados.
  - Revisa que los números de documento y cuenta coincidan con los registros.
Consulta la sección de [Errores de Método de Pago](#payment-method-errors) para obtener consejos sobre cómo hacer esto usando nuestra API.
2. **Prueba con un Lote Pequeño**
Antes de subir grandes volúmenes de archivos:
  - Sube uno o dos archivos primero para verificar que la configuración sea correcta.
  - Revisa los mensajes de retroalimentación.
  - Procede con lotes más grandes después de una prueba exitosa.
3. **Organiza Archivos Localmente**
  - Mantén una copia local de todos los archivos subidos (con una convención de nombres consistente).
  - Lleva un registro de qué archivos pertenecen a qué consentimientos.


### Durante la Carga

1. **Carga de Conjuntos Completos**
  - Carga los cuatro documentos requeridos para cada consentimiento cuando sea posible, ya que esto activa el procesamiento del consentimiento.
2. **Evitar Cargas Duplicadas**
  - No cargues el mismo archivo varias veces. Espera comentarios antes de volver a cargar.
3. **Verificar la Integridad del Archivo**
  - Verifica que los archivos no estén corruptos antes de cargarlos y que se abran correctamente en tu sistema local.


### Después de la Carga

1. **Monitorear el Directorio de Retroalimentación**
  - Verificar el directorio de salida después de 30 minutos
  - Descargar y revisar todos los archivos de retroalimentación
  - Tomar medidas sobre los errores de inmediato
2. **Rastrear el Estado del Consentimiento**
  - Monitorear tus eventos de webhook recibidos para verificar los estados de consentimiento (o consultar nuestra API usando la solicitud de API Obtener los detalles de un Consentimiento.)
  - Monitorear la progresión a través de: awaiting_information → submitted → confirmed/rejected
3. **Archivar Archivos Procesados**
  - Mantener registros de los archivos cargados exitosamente
  - Documentar los mensajes de retroalimentación
  - Mantener un rastro de auditoría para cumplimiento y resolución de problemas


## Ciclo de Vida del Consentimiento

Una vez que todos los documentos de consentimiento se cargan exitosamente a través de SFTP, progresan a través de las siguientes etapas del ciclo de vida:

| Estado | Descripción | Webhook |
|  --- | --- | --- |
| `awaiting_information` | Esperando que se carguen todos los archivos para el consentimiento. | Ninguno |
| `submitted` | Se han cargado los cuatro archivos requeridos. | `consent_submitted` |
| `processing` | La validación KYC está en progreso (generalmente requiere entre 24 a 48 horas). | Ninguno |
| `confirmed` | El consentimiento ha sido aprobado y está listo para pagos. | `consent_confirmed` |
| `rejected` | El consentimiento no fue aprobado. | `consent_rejected` |
| `incomplete_information` | El consentimiento requiere documentos adicionales o correcciones. | `consent_incomplete_information` |


Para verificar los detalles de un consentimiento, utiliza la solicitud de API Obtener los detalles de un Consentimiento.

## Próximos pasos

Una vez que un consentimiento es **confirmado**:

- No necesitas realizar ninguna acción adicional con respecto al consentimiento en sí. El consentimiento es válido hasta que sea revocado por el cliente o expire según el acuerdo.
- El Método de Pago asociado puede ser utilizado para pagos.