Enviar Importações em Lote 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

A funcionalidade de Importação em Lote via SFTP permite que você faça upload de arquivos CSV contendo dados de pagamento para automatizar a criação de clientes, métodos de pagamento e solicitações de pagamento em larga escala. Esta é a mesma funcionalidade de importação em lote disponível através do Portal do Comerciante e da API, mas com a conveniência adicional da automação baseada em arquivos via SFTP.

Esta funcionalidade é ideal para:

• Fluxos de trabalho automatizados: Configure transferências de arquivos agendadas a partir dos seus sistemas
• Processamento de alto volume: Processe milhares de solicitações de pagamento de forma eficiente
• Integração de sistemas: Conecte seus processos em lote existentes sem integração com API
• Simplicidade operacional: Use clientes SFTP padrão em vez de código API personalizado

Como Funciona

O processo de importação em lote via SFTP espelha a funcionalidade de Importação em Lote de Pagamentos por Débito Direto disponível no Portal do Comerciante, com automação baseada em arquivos:

1. Carregar CSV: Você carrega um arquivo CSV (usando o mesmo formato dos uploads do portal) no seu diretório de entrada SFTP.
2. Coleta Automática: A Belvo monitora seu diretório de entrada e coleta novos arquivos a cada 15 minutos, de segunda a sexta-feira.
3. Processamento: O sistema valida e processa seu arquivo, criando clientes, registrando métodos de pagamento e enviando solicitações de pagamento.
4. Feedback: Um arquivo de feedback .txt é gerado no seu diretório de saída com os resultados do processamento.

Pré-requisitos

Antes de enviar arquivos de importação em lote via SFTP, certifique-se de ter:

1. Importações em Lote via SFTP Habilitadas

   Entre em contato com o suporte da Belvo para habilitar importações em lote via SFTP para sua conta de comerciante.

2. Credenciais de 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.

3. Documentação de Consentimento

   Certifique-se de ter obtido e documentado o consentimento de todos os clientes incluídos na sua importação em lote. Você pode enviar os consentimentos usando o recurso Envio em Lote de Consentimentos via SFTP ou a Consent API.

4. Arquivo CSV Preparado

   Prepare seu arquivo CSV seguindo o mesmo formato usado para uploads no portal. Para especificações de campos, consulte a documentação de Modelos de arquivos de importação em lote.

Estrutura de Diretórios SFTP

Sua conta SFTP possui dois diretórios dedicados para importações em lote:

├── {merchantId}/
│   ├── inbound/
│   │   └── batch_imports/     ← Faça upload dos arquivos CSV aqui
│   └── outbound/
│       └── batch_imports/     ← Arquivos de feedback aparecem aqui

• Diretório de Entrada ({merchantId}/inbound/batch_imports/): Faça upload dos seus arquivos CSV neste diretório. Os arquivos devem seguir o mesmo formato CSV usado no Portal do Comerciante.
• Diretório de Saída ({merchantId}/outbound/batch_imports/): A Belvo escreve arquivos de feedback .txt aqui. Você não cria esta pasta por conta própria—a Belvo a provisiona. Você lê ou baixa do diretório de saída quando os arquivos estiverem disponíveis.

Especificações de Arquivo

Formato CSV

Os arquivos CSV de importação em lote devem seguir o mesmo formato dos uploads do portal. Para a especificação completa dos campos, consulte a documentação de Modelos de arquivo de importação em lote.

Nomeação de Arquivos

Você pode usar qualquer nome de arquivo válido para seus arquivos CSV. Recomendamos usar nomes descritivos que incluam uma data ou identificador de lote para seus próprios propósitos de rastreamento.

Nomes de Arquivos Válidos:
✅ payments_2026-04-08.csv
✅ batch_001.csv
✅ monthly_debits_april.csv

Processo de Upload

1. Conecte-se ao SFTP usando seu software preferido (por exemplo, Cyberduck, FileZilla ou ferramentas de linha de comando). Use as credenciais fornecidas pela equipe de suporte da Belvo.
2. Navegue até o diretório {merchantId}/inbound/batch_imports/.
3. Faça o upload do seu arquivo CSV para este diretório.
4. Aguarde o processamento do arquivo. A Belvo verifica seu diretório de entrada a cada 15 minutos, de segunda a sexta-feira.
5. Verifique o diretório {merchantId}/outbound/batch_imports/ para um arquivo de feedback .txt com os resultados do processamento.

Arquivos de Feedback

Após o processamento, um arquivo de feedback .txt é gravado em {merchantId}/outbound/batch_imports/.

Nomeação de arquivos de feedback

O nome de saída é derivado do seu arquivo CSV: o nome base e a extensão são mantidos, pontos (.) no nome ou extensão são substituídos por underscores, e um timestamp Unix em milissegundos é adicionado. A extensão é sempre .txt.

Exemplos:

• payments_2026-04-08.csv → payments_2026-04-08_csv_1775590260741.txt
• batch.import.csv → batch_import_csv_<timestamp>.txt

Use o timestamp (e seu log de upload) para associar arquivos de feedback aos uploads quando várias execuções ocorrem próximas umas das outras.

Quando o Feedback é Gerado

• Falhas de validação/preparação: O feedback de falha é enviado nesse caminho assim que a importação em lote não pode prosseguir (incluindo quando a validação falha antes de existir um registro em lote).
• Caminho bem-sucedido: Após a validação ser aprovada e o lote ser enviado para processamento, o feedback de sucesso ou falha terminal é registrado apenas quando o lote atinge um estado terminal (processed ou failed). O sistema verifica novamente aproximadamente a cada minuto, portanto, pode haver um atraso entre o arquivo desaparecer da entrada e o .txt aparecer na saída.

Visão Geral do Formato

• A primeira linha sempre faz referência ao nome original do arquivo CSV e se foi processado com sucesso ou não pôde ser processado.
• Quando um registro de importação em lote existe, a primeira linha inclui (batchImportId: <uuid>). Se o processamento falhar antes de um ID de lote ser criado, a primeira linha não possui ID de importação em lote.
• Linhas puladas (somente em caso de sucesso) são listadas como linhas no formato CSV (mesma estrutura dos dados de linha de importação em massa), não como resumos “Linha N:”.
• Erros usam a mesma estrutura que erros de validação de linha no Portal do Comerciante: blocos numerados, mensagens em lista e uma seção opcional Linha: com chaves de campo e valores sensíveis mascarados.

Feedback de Sucesso

Quando o lote termina com status processed, o corpo se apresenta assim:

Arquivo payments_january.csv processado com sucesso (batchImportId: 3f8e7d6c-5b4a-3210-fedc-ba9876543210).
0 linha(s) foram puladas.

Com linhas puladas:

Arquivo payments_january.csv processado com sucesso (batchImportId: 3f8e7d6c-5b4a-3210-fedc-ba9876543210).
2 linha(s) foram puladas.

Linhas puladas (2):
  RFC,ABCD123456ABC,john@example.com,John,Doe,+521234567890,****1234,poupança,500,REF001,,mxn
  RFC,XYZW987654XYZ,jane@example.com,Jane,Smith,+529876543210,****5678,poupança,250,REF002,,mxn

Sucesso com erros de linha tolerados

Esta forma aparece apenas quando o lote ainda é concluído como processed, mas algumas linhas tiveram problemas de validação toleráveis. O título da seção no arquivo é Rows with errors (tolerated):

Arquivo payments_january.csv processado com sucesso (batchImportId: 3f8e7d6c-5b4a-3210-fedc-ba9876543210).
1 linha(s) foram ignoradas.

Linhas ignoradas (1):
  RFC,ABCD123456ABC,john@example.com,John,Doe,+521234567890,****1234,savings,500,REF001,,mxn

Linhas com erros (tolerados) (1):
--
Erro 1:
  * o comprimento de accountNumber deve ser de 18 caracteres
  Linha:
    firstname: John
    lastname: Doe
    accountNumber: ****1234
    amount: 500

Se as regras de validação causarem a falha de todo o lote (por exemplo, tolerância desativada ou muitos erros), você receberá um feedback de falha em vez deste modelo de sucesso.

Feedback de Falha

Quando a preparação ou o processamento terminal falha com erros estruturados:

O arquivo payments_january.csv não pôde ser processado (batchImportId: 3f8e7d6c-5b4a-3210-fedc-ba9876543210).

Erros (2):
--
Erro 1:
  * email deve ser um email
  Linha:
    email: not-a-valid-email
    amount: 50
    currency: mxn
    firstname: Bad
    lastname: Email
--
Erro 2:
  * documentType deve ser um dos seguintes valores: mx_rfc, mx_curp
  Linha:
    email: jane@example.com
    documentType: mx_xyz
    documentNumber: BADD141414NNN

Quando ainda não existe um ID de importação em lote:

O arquivo payments_january.csv não pôde ser processado.

Erros (1):
--
Erro 1:
  * email deve ser um email
  Linha:
    email: invalid
    ...

Feedback de erro inesperado

Quando não há uma lista de erros estruturada (por exemplo, um erro de processamento inesperado), o arquivo contém apenas o cabeçalho e uma segunda linha fixa:

O arquivo payments_january.csv não pôde ser processado (batchImportId: 3f8e7d6c-5b4a-3210-fedc-ba9876543210).

Devido a um erro inesperado.

Se nenhum lote foi criado, a primeira linha é O arquivo <name>.csv não pôde ser processado. sem (batchImportId: ...), seguida por uma linha em branco e Devido a um erro inesperado.

Ciclo de Vida de Importação em Lote

Importações em lote enviadas via SFTP seguem o mesmo ciclo de vida que os uploads pelo portal:

Solução de Problemas

Arquivo não aparece no diretório de saída

Arquivo permanece no diretório de entrada

Em casos raros, um arquivo pode permanecer no diretório de entrada após o processamento porque a exclusão falhou. Esse objeto pode ser capturado novamente em uma execução posterior. Se você já recebeu feedback para esse upload, entre em contato com o suporte da Belvo ou remova ou renomeie o arquivo manualmente. Se estiver em dúvida, verifique o status do lote via API ou Portal do Comerciante antes de fazer o upload novamente.

Erros comuns de validação

Para erros comuns de validação de CSV e suas soluções, consulte a seção Solução de Problemas e FAQs na documentação de Importação em Massa.

Melhores Práticas

Antes de Fazer o Upload

1. Valide seu CSV localmente

   • Certifique-se de que todos os campos obrigatórios estão presentes
   • Verifique se os números CLABE têm 18 dígitos
   • Cheque se os endereços de email são válidos
   • Confirme se os tipos de ID são mx_curp ou mx_rfc

2. Teste com pequenos lotes primeiro

   • Faça o upload de um arquivo com algumas linhas para verificar se o formato está correto
   • Verifique o arquivo de feedback antes de fazer upload de grandes lotes

3. Garanta que os consentimentos estão em ordem

   • Todos os clientes devem ter confirmado os consentimentos antes que as solicitações de pagamento sejam criadas
   • Use o recurso SFTP Bulk Upload Consents para fazer upload dos documentos de consentimento

Durante o Upload

1. Use nomes de arquivos descritivos

   • Inclua datas ou identificadores de lote para facilitar o rastreamento
   • Mantenha um registro local dos arquivos enviados

2. Evite uploads duplicados

   • Aguarde feedback antes de enviar os mesmos dados novamente
   • Use referências únicas para cada solicitação de pagamento

Após o Upload

1. Monitore arquivos de feedback

   • Verifique seu diretório de saída regularmente
   • Revise linhas ignoradas e erros prontamente

2. Acompanhe via webhooks

   • Configure listeners de webhook para eventos de importação em lote
   • Use a API para verificar o status do lote para informações detalhadas

3. Mantenha trilhas de auditoria

   • Arquive arquivos de feedback para conformidade
   • Documente quaisquer erros e resoluções

Próximos Passos

Após configurar as importações em lote via SFTP:

• Revise as especificações de campos CSV para garantir que seus arquivos estejam formatados corretamente.
• Configure ouvintes de webhook para receber notificações em tempo real sobre suas importações em lote.
• Utilize o recurso Exportações de Pagamentos para reconciliar os pagamentos processados.