# Enviar Importações em Lote via SFTP ## 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 Habilitação da Funcionalidade As Importações em Lote via SFTP devem ser habilitadas para sua conta de comerciante. Entre em contato com o suporte da Belvo para solicitar acesso a esta funcionalidade. Obtenha Consentimento do Usuário para Debitar Contas Antes de fazer qualquer solicitação de pagamento, você deve: 1. Obter consentimento explícito dos seus usuários, autorizando você a debitar fundos de suas contas. 2. Manter evidências documentadas desse consentimento. Para mais informações, consulte nosso guia Upload em Massa de Consentimentos via SFTP. ## 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. Webhooks e Acesso à API O processamento de importação em lote via SFTP aciona os mesmos webhooks e atualiza os mesmos recursos da API que as importações em lote baseadas no portal ou na API. O arquivo de feedback SFTP é um mecanismo de notificação adicional, não um substituto para webhooks. ## 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. Crie a pasta de importações em lote se necessário Se `batch_imports/` não existir em `{merchantId}/inbound/`, **crie essa pasta manualmente** no seu cliente SFTP antes de fazer o upload. ## 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. Criar Métodos de Pagamento em Lote Apenas Você também pode usar este recurso para criar clientes e métodos de pagamento em lote sem fazer solicitações de pagamento. Para isso, omita os campos **Referencia Única cliente** e **Importe a cobrar** no seu CSV. ### 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 ``` Objetos ignorados Arquivos vazios, objetos de zero bytes e entradas de espaço reservado de diretório sob `batch_imports` são ignorados e não são processados. ## 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. Agenda de Processamento Os arquivos são coletados a cada 15 minutos, de segunda a sexta-feira. Arquivos enviados fora do horário comercial ou nos fins de semana serão processados no próximo dia útil. Remoção de Arquivos Após um arquivo ser coletado para processamento, a Belvo tenta removê-lo do diretório de entrada para evitar processamento duplicado. Se a remoção for bem-sucedida, o mesmo arquivo não será coletado novamente. Se a remoção falhar (raro), o objeto ainda pode aparecer em listagens em uma execução posterior e pode ser processado novamente—entre em contato com o suporte da Belvo ou remova ou renomeie o arquivo manualmente se você vir arquivos obsoletos após já ter recebido feedback. ## 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_.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: )`. 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: ``` Exemplo — sucesso limpo Arquivo payments_january.csv processado com sucesso (batchImportId: 3f8e7d6c-5b4a-3210-fedc-ba9876543210). 0 linha(s) foram puladas. ``` Com linhas puladas: ``` Exemplo — sucesso 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 ``` Valores mascarados Campos de conta e outros campos sensíveis aparecem **mascarados** no feedback (por exemplo, `****1234`), consistente com a experiência de importação em massa no Portal do Comerciante. ### 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)`**: ``` Exemplo — processado com erros de linha tolerados 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: ``` Exemplo — falha com erros de validação 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: ``` Exemplo — falha antes de existir 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: ``` Exemplo — erro inesperado 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 .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: | Status | Descrição | | --- | --- | | `validating` | O arquivo está sendo validado para erros de formato e conteúdo. | | `failed` | O arquivo possui erros críticos e não pode ser processado. Verifique o arquivo de feedback para mais detalhes. | | `ready_to_send` | A validação foi aprovada. Para uploads via SFTP, o processamento continua automaticamente. | | `processing` | Clientes, métodos de pagamento e solicitações de pagamento estão sendo criados. | | `processed` | Processamento concluído. Verifique o arquivo de feedback para os resultados, incluindo quaisquer linhas ignoradas. | Processamento Automático Ao contrário dos uploads pelo portal, onde você deve clicar manualmente em "Enviar" após a validação, os uploads via SFTP são automaticamente enviados para processamento assim que a validação é aprovada. ## Solução de Problemas ### Arquivo não aparece no diretório de saída | Causa | Solução | | --- | --- | | Arquivo ainda está sendo processado | Aguarde pelo menos 30 minutos após o upload. O processamento pode demorar mais para arquivos grandes. | | Arquivo enviado fora do horário de processamento | Os arquivos são processados apenas de segunda a sexta-feira. Aguarde até o próximo dia útil. | | Lote ainda está processando solicitações de pagamento | Para lotes que passam na validação, o feedback é gerado apenas após o lote atingir o status `processed` ou `failed`. | | Arquivo foi enviado para o diretório errado | Verifique se você enviou para `{merchantId}/inbound/batch_imports/` (não `bulk-consents`). | ### 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.