Upload em Massa de Consents via SFTP

Copiar

• Copiar para LLM

  Copiar página como Markdown para LLMs
• Ver como Markdown

  Abrir esta página como Markdown
• Abrir no ChatGPT

  Obter insights do ChatGPT
• Abrir no Claude

  Obter insights do Claude
• Conectar ao Cursor

  Instalar servidor MCP no Cursor
• Conectar ao VS Code

  Instalar servidor MCP no VS Code

Visão Geral

O recurso de Upload em Massa de Consentimento via SFTP permite que você carregue múltiplos documentos de consentimento em escala sem usar a API para cada arquivo individual. Isso é ideal para:

• Uploads de alto volume: Processar centenas ou milhares de documentos de consentimento de forma eficiente
• Operações em lote: Carregar múltiplos arquivos simultaneamente
• Integração simplificada: Usar clientes SFTP padrão em vez de integração com API
• Fluxos de trabalho automatizados: Configurar transferências automáticas de arquivos a partir dos seus sistemas

Após os documentos de consentimento serem carregados e confirmados, você pode prosseguir para fazer Solicitações de Pagamento para debitar as contas dos seus clientes.

Fluxo

O processo de upload em massa funciona da seguinte forma:

1. Upload de Arquivos: Você faz o upload de documentos de consentimento para o seu diretório SFTP dedicado.
2. Processamento Automático: Nosso sistema monitora seu diretório e processa novos arquivos a cada 15 minutos. As etapas de processamento incluem:
   • Validação: Cada arquivo é validado quanto ao nome, tamanho e conteúdo.
   • Criação de Consentimento: Os arquivos são automaticamente vinculados a métodos de pagamento e consentimentos existentes.
3. Feedback: Você recebe mensagens de confirmação ou erro no seu diretório de saída.

Pré-requisitos

Antes de enviar arquivos de consentimento via SFTP, você deve:

1. Criar Registros de Clientes e Registrar Métodos de Pagamento

   Você deve ter os clientes e seus Métodos de Pagamento associados registrados na plataforma Belvo antes de realizar a operação de consentimento em massa via SFTP. Recomendamos usar nosso recurso de Importação em Massa de Débitos Diretos para criar automaticamente clientes e métodos de pagamento em massa. No envio inicial, você pode omitir os campos Referencia Única cliente e Importe a cobrar, pois não são necessários para a criação de Cliente e Método de Pagamento.

2. Credenciais SFTP

   Obtenha suas credenciais de acesso SFTP com a equipe de suporte da Belvo. Por favor, note que permitimos apenas uma conta SFTP por comerciante.

Estrutura de Diretório SFTP

Sua conta SFTP possui dois diretórios dedicados:

├── inbound/
│   └── bulk-consents/     ← Faça upload dos documentos de consentimento aqui
└── outbound/
    └── bulk-consents/     ← Mensagens de feedback aparecem aqui

• Diretório Inbound: Faça upload dos seus documentos de consentimento no diretório inbound/bulk-consents/, de acordo com as convenções de nomenclatura e especificações descritas abaixo.
• Diretório Outbound: Arquivos processados e mensagens de feedback estarão disponíveis no diretório outbound/bulk-consents/.

Especificações do Arquivo

Para que os uploads do seu documento de consentimento sejam aceitos, eles devem seguir as seguintes especificações:

Convenção de Nomeação de Arquivos

Todos os arquivos enviados devem seguir este padrão de nomeação exato:

Padrão de Nomeação:
consent_<idDocumentType>_<idDocumentNumber>_<accountNumber>_<documentType>.<extension>

Nomes de Arquivos 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

Nomes de Arquivos Inválidos:
❌ invoice_ABCD123456_012345678901234567_id_front.pdf -> (Prefixo errado - deve ser "consent_")
❌ consent_ABCD_id_front.pdf -> (Número da conta ausente)
❌ consent_ABCD_1234_document.pdf -> (Tipo de documento inválido - deve ser um dos: id_front, id_back, selfie, contract)
❌ consent_ABCD_1234_id_front -> (Extensão do arquivo ausente)
❌ consent_mx_rfc_ABCD123456_12AB_id_front.pdf -> (Número da conta deve ser apenas numérico)

Tipos de Documentos de Consentimento

Para cada cliente, você deve enviar quatro arquivos de documentos de consentimento:

Limites de Tamanho de Arquivo

Cada arquivo enviado deve obedecer às seguintes restrições de tamanho:

• Tamanho mínimo: 100 bytes
• Tamanho máximo: 20 MB por arquivo

Formatos de Arquivo Suportados

• PDF: .pdf (recomendado para contratos)
• PNG: .png (recomendado para documentos de identidade e selfies)
• JPEG: .jpg (aceitável para todos os tipos de documentos)

Recomendações de Qualidade de Imagem

• Resolução: Mínimo de 300 DPI para documentos de identificação
• Clareza: Certifique-se de que o texto seja legível e as fotos estejam claras
• Orientação: As imagens devem estar corretamente orientadas (não giradas)
• Cor: Imagens coloridas são preferíveis a preto e branco

Processo de Upload

1. Conecte-se ao SFTP usando seu software preferido (por exemplo, Cyberduck). Use as credenciais fornecidas pela equipe de suporte da Belvo.
2. Navegue até o diretório inbound/bulk-consents/.
3. Faça o upload dos seus arquivos de documentos de consentimento para este diretório.
4. Aguarde o processamento dos arquivos. Nosso sistema verifica seu diretório inbound a cada 15 minutos em busca de novos arquivos. Cada lote de arquivos leva aproximadamente 30 minutos para ser processado, dependendo do volume.
5. Verifique o diretório outbound/bulk-consents/ para arquivos de feedback indicando sucesso ou erros para cada arquivo enviado.

Após o Upload

Após fazer o upload dos seus documentos de consentimento, você precisa verificar os arquivos de feedback no diretório de saída (outbound/bulk-consents/) para confirmar se os uploads foram bem-sucedidos ou se houve algum erro. Você precisará abrir cada arquivo de feedback para ver os resultados do processamento.

Os nomes dos arquivos no diretório de saída corresponderão aos arquivos enviados, por exemplo:

consent_mx_rfc_ABCD123456_012345678901234567_id_front_pdf.txt

Uploads Bem-Sucedidos

Para uploads de arquivos bem-sucedidos (o arquivo foi aceito e vinculado a um ID de consentimento), o arquivo de feedback conterá as seguintes informações:

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.

Uploads Mal-Sucedidos

Para uploads mal-sucedidos, o arquivo de feedback detalhará os motivos da rejeição. Por exemplo:

Arquivo consent_mx_rfc_ABCD123456_012345678901234567_id_front.pdf rejeitado porque:
* originalFilename deve começar com "consent_"
* accountNumber deve ser numérico

Neste caso, você precisará corrigir os problemas mencionados e fazer o upload do arquivo novamente.

Erros Comuns

Erros de Nomeação de Arquivos

originalFilename must start with "consent_"

• Causa: O nome do arquivo não começa com "consent_"
• Solução: Renomeie o arquivo para começar com o prefixo "consent_"

accountNumber deve ser numérico

• Causa: O número da conta contém letras ou caracteres especiais
• Solução: Certifique-se de que o número da conta contenha apenas dígitos (por exemplo, número CLABE)

consentDocumentType deve ser um dos seguintes valores: id_front, id_back, selfie, contract

• Causa: Tipo de documento inválido no nome do arquivo
• Solução: Use apenas: id_front, id_back, selfie, ou contract

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

• Causa: Formato de arquivo não suportado
• Solução: Converta o arquivo para o formato PDF, PNG ou JPG

Erros de Tamanho de Arquivo

File size must be at most 20000000 bytes (20 MB)

• Causa: O arquivo excede o limite máximo de tamanho
• Solução: Comprimir ou redimensionar o arquivo para menos de 20 MB

O tamanho do arquivo deve ser de pelo menos 100 bytes

• Causa: O arquivo está vazio ou corrompido
• Solução: Certifique-se de que o arquivo contém conteúdo real e não está corrompido

Erros de Método de Pagamento

método de pagamento não encontrado para a conta e cliente fornecidos

• Causa: Não existe um método de pagamento que corresponda ao número do documento e número da conta
• Solução:

  1. Verifique se idDocumentNumber corresponde exatamente ao registro do seu cliente.

     Você pode usar a solicitação de API Listar todos os clientes, usando o número do documento ou nome no parâmetro de consulta search.

  2. Verifique se o método de pagamento foi criado (usando nossa API). Crie o método de pagamento se ele não existir.

     Você pode usar a solicitação de API Listar todos os métodos de pagamento, usando o parâmetro de consulta customer_id para visualizar todos os métodos de pagamento criados para o cliente. Se um método de pagamento não existir, use a solicitação de API Criar um método de pagamento para criar um novo método de pagamento para o cliente.

  3. Confirme se accountNumber corresponde exatamente ao método de pagamento.

Erros de Processamento de Arquivo

Arquivo não aparece no diretório de saída após 30+ minutos

Possíveis causas e soluções:

Se os arquivos não aparecerem após 60 minutos, por favor, entre em contato com o suporte da Belvo.

Melhores Práticas

Abaixo estão algumas melhores práticas para garantir um processo suave de upload de consentimento em massa via SFTP.

Antes de Fazer o Upload

1. Valide os Dados Primeiro

   • Certifique-se de que os clientes existem no sistema.
   • Verifique se os métodos de pagamento estão registrados.
   • Verifique se os números de documentos e contas correspondem aos registros.

   Confira a seção Erros de Método de Pagamento para dicas de como fazer isso usando nossa API.

2. Teste com um Lote Pequeno Antes de fazer o upload de grandes volumes de arquivos:

   • Faça o upload de um ou dois arquivos primeiro para verificar se a configuração está correta.
   • Verifique as mensagens de feedback.
   • Prossiga com lotes maiores após um teste bem-sucedido.

3. Organize os Arquivos Localmente

   • Mantenha uma cópia local de todos os arquivos enviados (com uma convenção de nomenclatura consistente).
   • Acompanhe quais arquivos pertencem a quais consentimentos.

Durante o Upload

1. Carregar Conjuntos Completos
   • Carregue todos os quatro documentos necessários para cada consentimento quando possível, pois isso aciona o processamento do consentimento.
2. Evite Uploads Duplicados
   • Não carregue o mesmo arquivo várias vezes. Aguarde o feedback antes de recarregar.
3. Verifique a Integridade do Arquivo
   • Verifique se os arquivos não estão corrompidos antes do upload e se abrem corretamente no seu sistema local.

Após o Upload

1. Monitorar Diretório de Feedback
   • Verifique o diretório de saída após 30 minutos
   • Baixe e revise todos os arquivos de feedback
   • Tome medidas sobre os erros prontamente
2. Acompanhar Status de Consentimento
   • Monitore seus eventos de webhook recebidos para verificar os status de consentimento (ou consulte nossa API usando a solicitação de API Obter detalhes de um Consentimento.)
   • Monitore a progressão através de: awaiting_information → submitted → confirmed/rejected
3. Arquivar Arquivos Processados
   • Mantenha registros dos arquivos carregados com sucesso
   • Documente mensagens de feedback
   • Mantenha um rastro de auditoria para conformidade e resolução de problemas

Ciclo de Vida do Consentimento

Uma vez que todos os documentos de consentimento são carregados com sucesso via SFTP, eles progridem através das seguintes etapas do ciclo de vida:

Para verificar os detalhes de um consentimento, use a solicitação de API Obter detalhes de um Consentimento.

Próximos Passos

Uma vez que um consentimento é confirmado:

• Você não precisa tomar nenhuma ação adicional em relação ao consentimento em si. O consentimento é válido até ser revogado pelo cliente ou expirar conforme o acordo
• O Método de Pagamento associado pode ser usado para pagamentos.