Dispersão de folha por lote: do arquivo à execução

Uma empresa brasileira que paga prestadores de serviço em vários países da América Latina raramente pensa no fechamento do mês como um único evento. Pensa nele como um arquivo: linhas de pessoas, colunas de valores e, se algo sai errado, uma linha que precisa ser encontrada antes que o resto do pagamento fique travado atrás dela. Programar a data ou repetir o ciclo todo mês é a parte fácil. O arquivo em si é o que decide se o pagamento sai limpo.

Na Soulbit Academy escrevemos este guia sobre essa peça específica: como se constrói o arquivo de um lote de folha, o que o sistema valida antes de aceitá-lo, o que acontece quando uma linha falha e que evidência fica para o fechamento contábil. A Soulbit é um trilho de pagamento e tesouraria em stablecoins para empresas, não um software de cálculo de folha nem uma integração com o sistema de RH da empresa.

O que é a dispersão de folha por lote e quando usá-la

A dispersão de folha por lote é a execução de um pagamento em massa, em uma única operação, a partir de um arquivo que reúne todos os beneficiários de um período. A empresa carrega o arquivo uma vez, com valores e dados já definidos, e o sistema dispersa para cada destino sem transferências individuais.

Vale distinguir esse mecanismo da folha recorrente. O lote é uma execução pontual: serve para a primeira folha da empresa, para um pagamento extraordinário como um bônus ou uma rescisão, ou para um mês em que a lista de beneficiários mudou por completo. A folha recorrente, por sua vez, reaproveita a mesma lista de beneficiários ciclo após ciclo sem reconstruir o arquivo. O detalhe operacional desse segundo mecanismo está em como programar folha recorrente em stablecoin, e vale a leitura antes de decidir qual dos dois usar a cada mês.

O lote também não é uma forma de contornar a periodicidade legal do salário. Cada país onde a empresa paga sua equipe tem seu próprio limite de periodicidade, e esse limite não muda porque o pagamento saiu de um arquivo em vez de um ciclo recorrente. Um caso típico ilustra a diferença: uma empresa com equipe distribuída em folha recorrente na Colômbia, no México e no Brasil paga um bônus de fim de ano a um grupo de prestadores, com valores que não têm relação com o ciclo mensal recorrente. Esse bônus sai como um lote separado, porque sua lista, seus valores e seu momento não pertencem ao ciclo recorrente. A mesma lógica vale para o pagamento final de um prestador cujo contrato termina no meio do mês, ou para um acerto único com um grupo de fornecedores que não vai se repetir.

As colunas que o arquivo de folha por lote precisa ter

O arquivo de folha por lote precisa de seis colunas mínimas para que o sistema consiga validá-lo sem depender de uma ligação ou um e-mail de esclarecimento.

Coluna	O que contém	Por que é validada
Referência do período	Referência interna da empresa para o mês ou o pagamento	Permite cruzar o lote com a folha própria da empresa
Identificação do destinatário	Documento ou identificador único de cada pessoa	Evita pagar a um destinatário duplicado ou sem cadastro completo
Tipo de relação	Funcionário ou prestador, conforme a classificação da empresa	O sistema não decide essa classificação: apenas a registra
Moeda ou ativo de pagamento	USDC, USDT ou fiat em USD, EUR ou GBP, conforme definido	Determina o canal de liquidação usado em cada linha
Valor líquido a pagar	O valor já calculado pela empresa para aquele período	É comparado com o saldo disponível antes da execução
Endereço de destino verificado	O endereço ou conta de recebimento já validado no cadastro	É o dado irreversível: um envio para um endereço errado não pode ser desfeito

O valor líquido de cada linha chega já calculado pela empresa. O arquivo não recalcula salários, não aplica retenções nem determina contribuições previdenciárias: recebe o resultado desse cálculo, produzido pelo sistema ou pelo contador da própria empresa, e o transforma em um lote executável.

Esse ponto merece uma resposta direta, porque é a primeira pergunta de uma equipe de sistemas ao avaliar o mecanismo.

Por que um arquivo em vez de uma conexão direta com o sistema de folha ou RH da empresa?

Porque a Soulbit não oferece hoje uma API nem um conector com ERP. O arquivo é o mecanismo de entrada da V1: a empresa exporta sua folha já calculada para esse formato e a carrega manualmente. Não é uma limitação escondida, é o alcance real do produto hoje.

O que o sistema valida antes de aceitar o lote

Antes de aceitar um lote, o sistema roda duas verificações bloqueantes: a identidade de cada destinatário contra o cadastro verificado e se o saldo disponível cobre o total. Erros de formato do arquivo e de endereço de destino não param a carga inteira: são marcados linha por linha, como detalha a seção seguinte.

A verificação de identidade depende de um cadastro prévio. Nenhum destinatário novo entra em um lote sem antes ter completado seu cadastro, com documento, contrato ou nota fiscal vigente e endereço de destino confirmado por um canal diferente daquele pelo qual chegou a solicitação. Esse cadastro é feito uma única vez e reaproveitado em cada lote seguinte, e sua lógica completa está no guia de folha recorrente citado acima, porque o cadastro é o mesmo para os dois mecanismos.

O saldo é verificado antes da execução, não durante. O sistema compara o total do lote, incluída a taxa de rede, com o saldo disponível na conta operacional. Se o saldo for insuficiente, o lote inteiro fica retido, não apenas as linhas que excedem o saldo: é a única validação que afeta o arquivo completo, porque o saldo é uma condição de todo o lote, não de uma linha isolada.

A verificação da empresa é a condição que precisa estar concluída antes de qualquer checagem de identidade ou de saldo. Sem ter concluído o processo de KYB, que valida a sociedade, sua atividade e seus beneficiários finais, não existe conta operacional a partir da qual carregar nenhum arquivo. Esse cadastro é resolvido uma única vez, na abertura da conta, e não se repete a cada lote.

O que acontece quando uma linha do arquivo falha

Uma linha que falha não trava o lote inteiro. Ela fica marcada como pendente, com o motivo específico da rejeição, enquanto as demais linhas seguem seu curso rumo à aprovação.

Erro na linha	O que provoca	Como se resolve
Endereço de destino não verificado	A linha fica pendente até confirmar o cadastro do destinatário	Verificar por um canal diferente e, se for um cadastro novo, fazer uma transferência de teste
Valor zerado ou negativo	O sistema rejeita a linha por dado inválido	Corrigir o valor no arquivo e reenviar apenas essa linha
Destinatário duplicado no mesmo lote	Risco de pagamento duplicado à mesma pessoa	Remover a linha repetida antes de aprovar o lote
Moeda ou ativo não suportado para o destinatário	A linha fica pendente de definição	Ajustar a moeda de pagamento conforme combinado com o destinatário
Cadastro do destinatário incompleto	A linha não pode ser validada contra nenhum dado de referência	Completar o cadastro antes de incluir a pessoa no lote

É possível reenviar só a linha corrigida sem refazer o lote inteiro?

Sim. A correção se aplica à linha específica, e o lote mantém as linhas já validadas. Isso evita o cenário mais custoso operacionalmente: reconstruir um arquivo de quarenta ou cem linhas porque uma única linha carregava um dado errado.

Aprovação e duplo controle: o passo entre carregar e executar

Nenhum lote é executado apenas com o carregamento do arquivo. Ele passa primeiro por uma aprovação de alguém diferente de quem construiu o arquivo, mesmo quando a equipe financeira da empresa é composta por duas pessoas.

Esse duplo controle existe porque um pagamento on-chain, uma vez executado, não pode ser revertido com uma ligação ao banco. Quem aprova revisa o total do lote, a quantidade de linhas pendentes frente às validadas e o saldo disponível, e só então confirma a execução. O registro de quem aprovou e quando fica associado ao lote.

Executado o lote, cada destinatário na Colômbia recebe pesos ou dólares reais por canais bancários locais, conforme definido linha por linha pela empresa. Esse fluxo de conversão e o trilho local estão documentados em dispersão de pagamentos em COP e USD, que vale a leitura junto com este guia, porque o arquivo é a entrada e o trilho local é a saída do mesmo processo. Fora da Colômbia, o lote é liquidado em stablecoins ou em fiat limitado a USD, EUR e GBP, e cada destinatário resolve a conversão para sua moeda local por conta própria.

O fechamento contábil: a evidência que cada lote executado deixa

Cada lote executado deixa um identificador on-chain por destinatário, a peça que transforma um pagamento em massa em um conjunto de lançamentos contábeis defensáveis em uma auditoria.

A conciliação é feita linha por linha, cruzando destinatário, valor bruto, taxa de rede e data com esse identificador. O procedimento completo, incluindo como separar valor bruto e taxa, está em como conciliar pagamentos em stablecoin na contabilidade.

Essa evidência não substitui as obrigações tributárias próprias de cada país, que correm em paralelo ao lote. Para destinatários na Colômbia, a DIAN exige gerar e transmitir o documento de suporte da folha eletrônica dentro dos primeiros dez dias do mês seguinte ao período pago, conforme a própria DIAN. O detalhe dessa obrigação, que já tem desenvolvimento próprio, está em folha eletrônica perante a DIAN.

As contribuições à PILA seguem um calendário à parte: vencem entre o segundo e o décimo sexto dia útil do mês seguinte, conforme os dois últimos dígitos do NIT (o identificador tributário colombiano) do empregador, segundo o Decreto 1990 de 2016. O guia completo dessa obrigação está em PILA: contribuições à seguridade social na Colômbia.

Por que guardar a evidência de cada lote além do fechamento do mês?

Porque a UGPP colombiana pode fiscalizar contribuições de até cinco anos atrás, e autoridades trabalhistas equivalentes em outros países da região mantêm suas próprias janelas de fiscalização. Um lote sem identificador rastreável, sem cadastro de destinatário verificado e sem registro de aprovação é uma lacuna documental que aparece justamente quando já não é simples reconstruí-la.

O que a Soulbit V1 entrega em folha por lote e o que não entrega

A V1 executa a dispersão de folha por lote a partir de um arquivo carregado pela empresa, com validação de formato, identidade, endereço de destino e saldo, além de duplo controle antes da execução. Inclui custódia institucional, saldos em USDC e USDT, fiat em USD, EUR e GBP, e trilho bancário local apenas na Colômbia.

O que não entrega delimita o mecanismo com precisão. Não calcula salários, contribuições nem retenções. Não gera o documento de suporte da folha eletrônica nem a planilha PILA na Colômbia: essas obrigações permanecem com a empresa. E, o limite que mais gera perguntas de equipes de sistemas, não oferece API nem conector com o ERP ou o software de folha da empresa. O arquivo é, hoje, o único mecanismo de entrada.

Não oferecer uma API não é um defeito a esconder. Um arquivo padronizado, validado linha por linha, com duplo controle e evidência on-chain, resolve o mesmo problema que uma integração automática resolveria, com menos superfície para erro humano do que copiar e colar valores um a um. A diferença está em quem monta o arquivo: hoje, a empresa, não um conector automático.

Para uma equipe financeira brasileira que paga prestadores em três ou quatro países, essa troca costuma ser aceitável. O arquivo substitui uma sequência de transferências internacionais individuais, cada uma com seu prazo e sua dedução, por um único carregamento validado e uma única execução. Ele não substitui as obrigações fiscais e trabalhistas próprias da empresa em cada país, e não é essa a sua função.