Folha de pagamento
Folha de Pagamento — Visão Geral
A API de Folha de Pagamento do BTG Empresas permite que sua empresa gerencie pagamentos em massa e o cadastro de colaboradores de forma centralizada, segura e rastreável. Esta documentação apresenta os principais fluxos disponíveis e como utilizá-los no dia a dia da sua operação.
Fluxo de Pagamentos
O fluxo de pagamentos é organizado em torno do conceito de lote: um agrupamento de pagamentos submetidos juntos para processamento. Isso permite que sua equipe financeira tenha controle granular sobre cada remessa, com rastreabilidade completa de status e histórico de transações.
Criar Lote de Pagamento
O ponto de entrada do fluxo é a submissão de um lote. Nesta etapa, você agrupa os pagamentos que devem ser processados em uma mesma remessa. A API suporta uma ampla variedade de modalidades, como salário, adiantamento, férias, décimo terceiro, rescisão, PLR, pró-labore, bolsa de estágio, benefício, reembolso, comissão, dividendos e outras.
Ao submeter o lote, você define para cada linha o colaborador destinatário, o valor líquido, os dados bancários de crédito e a data agendada para execução. A submissão é processada de forma assíncrona: a API retorna imediatamente com o identificador do lote e o processamento ocorre em segundo plano.
Listagem de Pagamentos
Todos os lotes submetidos ficam disponíveis para consulta. A listagem permite que sua equipe acompanhe o estado de cada remessa — identificando lotes submetidos, em aprovação, liquidados, com falha ou cancelados — e aplique filtros por período, status, referência ou outros critérios relevantes para o seu contexto.
Atenção: a listagem aplica um filtro implícito por janela de tempo. Pagamentos fora da janela padrão podem não aparecer mesmo após liquidação. Utilize os filtros startDate e endDate para ampliar o período de busca quando necessário.
Detalhes do Lote de Pagamento
Para cada lote, é possível acessar uma visão detalhada com todas as linhas de pagamento que o compõem. Esta consulta exibe o status individual de cada transação, os valores envolvidos, contadores de liquidações e falhas, e qualquer informação de retorno do processamento bancário — como confirmações ou erros por linha.
Os estados finais de um lote são settled (liquidado), failed (falhou) e cancelled (cancelado). Use esta visão para auditar remessas específicas, identificar divergências e obter a visão consolidada da operação.
Cancelar Lote de Pagamento
É possível cancelar um lote que já foi submetido, desde que ele ainda esteja nos status submitted (submetido) ou pending_approval (aguardando aprovação). O cancelamento interrompe o processamento do lote integralmente.
Esta operação é irreversível: uma vez cancelado, o lote não pode ser reativado. Caso necessite reprocessar os pagamentos, um novo lote deverá ser criado.
Fluxo de Colaboradores
O gerenciamento de colaboradores é o que viabiliza o fluxo de pagamentos: cada destinatário de um lote precisa estar cadastrado, com conta bancária válida e status ativo na plataforma. A API oferece endpoints para cobrir todo o ciclo de vida de um colaborador — do onboarding até o desligamento e reativação.
Solicitação de Abertura de Conta
Para que um colaborador possa receber pagamentos via folha, é necessário cadastrá-lo e solicitar a abertura de uma conta digital BTG Empresas em seu nome. A solicitação é feita com os dados cadastrais do colaborador — como CPF, nome completo, data de admissão, salário bruto mensal, e-mail, telefone, endereço e documento de identidade com o respectivo emissor — e desencadeia o processo de análise e criação da conta.
A submissão é assíncrona: a API retorna 202 Accepted imediatamente, e o processamento ocorre em segundo plano. O resultado pode ser acompanhado consultando os detalhes do colaborador ou o estado da sua conta bancária.
Listagem de Colaboradores
A listagem apresenta todos os colaboradores vinculados à sua empresa, com seus respectivos status. A partir desta visão, é possível identificar colaboradores com conta ativa (active), onboarding em andamento (pending), conta suspensa (suspended) e colaboradores desligados (inactive).
A listagem suporta filtros por status, nome, CPF, tipo de conta, portabilidade e tipo de contrato, além de paginação por cursor, sendo adequada tanto para uso em interfaces administrativas quanto para integrações automatizadas com sistemas de RH.
Acompanhamento da Abertura de Conta
Por ser um processo assíncrono, a abertura de conta pode ser acompanhada de duas formas: consultando o status do colaborador na listagem geral (onde aparecerá como pending enquanto o onboarding estiver em andamento) ou consultando especificamente os dados da conta bancária do colaborador, que retorna o estado atual do onboarding, a data de conclusão e eventuais erros.
Recomenda-se implementar um mecanismo de polling nessas consultas para monitorar a evolução do status sem a necessidade de verificações manuais recorrentes.
Detalhes do Colaborador
A consulta de detalhes retorna o perfil completo de um colaborador cadastrado: seus dados pessoais, status atual, tipo de contrato, informações de portabilidade, datas de admissão e desligamento, estado de suspensão e as informações de conta bancária vinculada.
Use esta consulta para verificar a elegibilidade de um colaborador para receber pagamentos antes de incluí-lo em um lote, ou para suporte e auditoria de casos específicos.
Inativar e Ativar Colaborador
Ao desligar um colaborador, é possível registrar o encerramento do vínculo empregatício na plataforma. Esta operação está disponível para colaboradores com status active e os move para o status inactive, impedindo que sejam incluídos em novos lotes de pagamento. O desligamento aceita data de rescisão e motivo.
A reativação é igualmente disponível: caso o colaborador retorne à empresa, ele pode ser reativado — desde que esteja no status inactive — voltando ao status active e tornando-se elegível novamente para receber pagamentos via folha.