O que é spool e como funciona na prática
Spool é um arquivo de lote usado por bancos e operadoras de pagamento na América Latina para transmitir ordens financeiras. O processo de enviando dados para spool consiste em gerar um arquivo com formatação específica, entregar ao banco ou sistema processador e confirmar que as transações foram executadas. Nada de mágica. É apenas um contrato de formato entre você e a instituição financeira. O arquivo spool geralmente segue o padrão CNAB (Centralizadora de Notas e Boletos) no Brasil, ou formatos proprietários em outros países. Cada banco tem sua versão. O Itaú usa um layout diferente do Bradesco, que por sua vez difere do Santander. Se você trabalha com múltiplas instituições, vai precisar manter pelo menos três geradores de arquivo activos.
Envio de dados para spool: o passo a passo real
Aqui vai o fluxo que eu uso no dia a dia, sem rodeios. 1. Gere o arquivo de lote a partir do seu sistema. A maioria dos ERPs e sistemas de cobrança gera isso automaticamente. O arquivo deve conter cabeçalho, registros de transacção e trailer. Cada campo tem posição fixa. Um erro de alinhamento e o banco rejeita o lote inteiro.
2. Valide o arquivo antes de enviar. Eu uso validadores gratuitos disponíveis nos portais dos bancos. O do Itaú, por exemplo, permite subir o arquivo e mostra erros linha por linha. Leva uns 30 segundos. Fazer isso economiza horas de back-and-forth com a relationship manager do banco quando o lote é rejeitado. 3. Faça o envio pelo canal apropriado. Bancos grandes aceitam spool via SFTP, portal bancário ou API. SFTP é o mais comum em operações de volume alto. Você sobe o arquivo numa pasta designada e o banco processa no horário de lote seguinte. O tempo de processamento varia de algumas horas a um dia inteiro, dependendo do banco e do horário de envio.
4. Acompanhe o retorno. O arquivo de retorno é tão importante quanto o envio. Ele informa quais transacções foram aceitas, recusadas ou precisam de ajuste. Ler um arquivo de retorno CNAB 400 posições requer paciência. Cada posição tem um significado específico: status do pagamento, data de compensação, motivo de rejeição e assim por diante.
Problemas que eu enfrentei e como resolvi
Há alguns anos, tive um problema específico com envio de spool para o Bradesco. O arquivo era gerado correctamente, validado no validador oficial e mesmo assim rejeitado. O motivo da rejeição não aparecia no arquivo de retorno. Fiquei três dias sem conseguir identificar o problema. A solução veio de forma inesperada. Eu.comparei character por character o meu arquivo com um arquivo que o banco aceitou. Descobri que havia um carácter invisível — um byte BOM (Byte Order Mark) — no início do ficheiro. O gerador do meu sistema adicionava automaticamente o BOM UTF-8. O validador do banco não reclamava, mas o sistema de processamento do Bradesco sim. A correção foi simples: forçar a codificação ASCII ou ISO-8859-1 no gerador de arquivos. Problema resolvido.
Isso me ensinou uma lição prática: o validador oficial do banco não é onipotente. Ele verifica formato, mas nem sempre valida tudo que o sistema de processamento real verifica. Sempre envie um arquivo de teste com valor baixo antes de processar um lote grande.
Erros comuns que iniciantes cometem
Multiplicação de títulos duplicados. Enviar o mesmo boleto duas vezes no mesmo lote spool. O sistema do banco processa ambas as cópias. Você recebe os dois pagamentos e precisa estornar um depois. Simples e doloroso. Ignorar o campo de carteira. No CNAB, o campo carteira define as regras de processamento do título. Carteira errada significa que o banco pode aceitar o arquivo mas processar a transacção de forma incorrecta, ou simplesmente rejeitar. Verifique sempre a tabela de carteiras do banco no manual técnico.
Não considerar prazos de compensação. Spool enviado às 17h de uma sexta-feira pode só ser processado na segunda. Isso afecta datas de vencimento e juros. Planeje os envios com antecedência, especialmente no final de semana. Confundir spool com transferência electrónica. Spool é envio em lote. Transferência electrónica (como TED ou DOC) é transacção individual em tempo real. São coisas diferentes. Você não usa spool para fazer uma transferência urgente de um único pagamento.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Dados técnicos importantes sobre spool
Formatos comuns incluem CNAB 240 e CNAB 400 no Brasil. O CNAB 240 é mais moderno, com mais campos disponíveis e menos propenso a erros de posicionamento. O 400 ainda é amplamente usado por bancos menores e em operações mais antigas. No México, o formato SPEI é usado para transferências, mas spool também existe para operação de massa com bancos como BBVA e Banorte. Cada um com seu próprio manual técnico.
Na Colômbia, o sistema PSE lida com autorizações, enquanto spool é usado para liquidacao de lote de boletos e tributos junto ao Banco da Republica e outros agentes. O tamanho máximo do arquivo varia por banco. Alguns aceitam até 50 MB, outros limitam a 10.000 registos por lote. Verifique essas limitações antes de montar arquivos massivos.
Alternativas ao spool tradicional
Se o seu volume é baixo — digamos menos de 200 transacções por dia — o spool pode ser Overkill. Muitos bancos oferecem APIs REST para criação e consulta de títulos. É mais simples de implementar, permite e elimina a dor de cabeça com arquivos de texto fixo. Por outro lado, se você processa milhares de pagamentos diariamente, o spool continua sendo a opção mais eficiente em termos de custo e throughput. A integração via API para volumes altos fica cara rapidamente, tanto em implementação quanto em custos de transação.
Outra alternativa que vale considerar é o uso de plataformas de pagamento terceirizadas como Gerencianet, Iugu ou Vindi. Elas abstraem a complexidade do spool e oferecem dashboard, relatores e conciliação automática. O custo por transação é maior, mas o tempo de desenvolvimento cai drasticamente.
Manuais técnicos e onde encontrar
Cada banco publica manuais técnicos completos sobre o formato spool. Eles estão quase sempre na seção de central de desenvolvedor ou relacionamento empresarial do site do banco. Para o Itaú, o manual CNAB está em desenvolvedor.itau.com.br. Para o Bradesco, consulte o portal do empresário ou a área de e-business. Para o Santander, a seção de soluções corporativas. Esses manuais têm entre 100 e 300 páginas. Eles descrevem cada campo, cada posição, cada código de status. Ler o manual inteiro antes de implementar é recomendável. Eu recomendo pelo menos um leitura atenta dos capítulos sobre layout de arquivo, códigos de retorno e instruções de envio.
Não tente implementar spool sem consultar o manual técnico do banco específico que você vai usar. Cada instituição tem particularidades que não estão documentadas em lugares genéricos. O que funciona para um banco pode falhar silenciosamente em outro.
Quanto tempo leva para implementar
Uma implementação básica de geração e envio de spool leva entre 40 e 80 horas de desenvolvimento, dependendo da complexidade. Isso inclui ler o manual do banco, implementar o gerador de arquivos, criar o validador, testar com o banco e ajustar. Se você usar uma biblioteca existente, esse tempo cai para 10 a 20 horas. Bibliotecas open source como o cnab240 para PHP, Python ou Java poupam muito trabalho. Mas fique atento: bibliotecas genéricas podem não cobrir todas as particularidades do seu banco. Teste sempre com um lote real antes de colocar em produção.
A manutenção também merece atenção. Manuais técnicos mudam. Novos campos aparecem, codes de retorno são actualizados, limites de arquivo são ajustados. Revisar os manuais a cada seis meses é uma boa prática. Eu perdia tempo precioso porque não atualizava minha implementação quando o banco mudou o formato de um campo específico.
Resumo prático
Envio de dados para spool é um processo operativo, não criativo. Seguir o manual técnico do banco à risca resolve a maioria dos problemas. Validar antes de enviar evita frustração. Testar com valores baixos previne prejuízos. E manter os manuais actualizados evita surpresas desagradáveis. O spool não é perfeito. Ele exige atenção a detalhes, tolerância zero para ambiguidade e paciência para lidar com retornos complexos. Mas para operações de volume médio a alto no segmento financeiro latino-americano, continua sendo a ferramenta padrão por um motivo: funciona, desde que você respeite as regras.
