Documentação

Português

English
Español

Português

English
Español

Appearance

Folha de pagamento ​

Pré-requisitos de acesso

  • Permissão (módulo): processPayroll (controla os botões na UI) + manageCompanyCharges (criar/editar/excluir) ou viewCompanyCharges (apenas listar) — exigidas pelo backend
  • Licença/Feature: Nenhuma específica.
  • Contêiner do menu: GERAL → grupo Cobranças (rota /manage-payroll)

O que é / quando usar ​

A Folha de pagamento agenda pagamentos recorrentes mensais da empresa para um usuário/funcionário — é a operação inversa das cobranças de usuário: aqui o dinheiro sai da conta do dono da empresa (userIdFrom) e entra na do funcionário (userIdTo), todo mês, no dia configurado, até a competência final.

Use-a para salários, pró-labore, bolsas, repasses fixos e qualquer pagamento periódico a colaboradores. Cada entrada gera um agendamento mensal; um scheduler no CustomerProfileService (CPM) roda periodicamente e efetua cada parcela pendente — via conta digital (quando a moeda é BRL e o recurso DIGITAL_BANKING_CHARGES está habilitado) ou via transação de carteira (token, ou BRL sem o recurso de banking).

Pré-condições ​

  • Permissão: processPayroll cadastrada para a role (libera os botões Adicionar pagamento, editar e excluir na UI). O backend valida manageCompanyCharges para mutações e viewCompanyCharges/manageCompanyCharges para listar. Permissão dupla — enum CPM + módulo dinâmico no DB.
  • Licença/Feature: Nenhuma específica. O comportamento de pagamento em BRL depende do recurso DIGITAL_BANKING_CHARGES estar ligado no tenant.
  • Dependências de outras telas: o funcionário precisa existir e ter carteira/conta válidas; o dono da empresa (owner) é resolvido automaticamente pelo backend como pagador. O usuário-alvo deve estar APPROVED.

Passo a passo ​

  1. Acesse Cobranças → Folha de pagamento (rota /manage-payroll).
  2. Use a busca para filtrar a lista por nome ou e-mail (filtro local).
  3. Clique em Adicionar pagamento para abrir o modal.
  4. Informe E-mail do funcionário, Descrição, Dia (1–31), Mês e ano do último pagamento e Valor.
  5. Confirme. O sistema valida o e-mail (busca o usuário pela carteira), calcula a data do primeiro pagamento e a data de expiração, e grava o agendamento.
  6. Para alterar, use o ícone de lápis; para remover, o de lixeira (abre uma confirmação em bottom-sheet).

Campos (modal de agendamento) ​

CampoO que éObrigatório?Efeito no sistema/backend
E-mailE-mail do funcionário a ser pagoSim (e-mail válido)A tela busca o usuário por getUserByEmailWallet. Se não existir, exibe erro e não salva. O id retornado vira o userIdTo do agendamento.
DescriçãoIdentificação do pagamento (ex.: "Salário Junho")Sim (alfanumérico)Grava description; aparece no extrato/transação.
DiaDia do mês em que o pagamento ocorreSim (1–31)Define o dia da recorrência. Regra: se o dia escolhido já passou no mês corrente, o primeiro pagamento é agendado para o mês seguinte; dias inexistentes (ex.: 31 em mês curto) são ajustados para o último dia do mês.
Mês / Ano do último pagamentoCompetência final da folhaSimCompõe a expirationDate. O sistema impede datas no passado (validação errorInLastDate).
ValorQuantia paga por mêsSimGrava amountRequested. Tratado como BigNumber no processamento. Exibido na listagem com a moeda fiduciária do tenant.

A moeda padrão das chamadas de folha é BRL. O agendamento herda os campos de início (creationDate, calculada a partir do Dia) e fim (expirationDate, a partir de Mês/Ano).

Ações e modais ​

  • Adicionar pagamento: abre o UserPaymentScheduleModalComponent. Só habilita confirmar com formulário válido, e-mail existente e data final não-passada → POST /v1/company-charges/createAdmin. O backend define o pagador (userIdFrom) como o owner da empresa.
  • Editar (lápis): abre o mesmo modal preenchido → POST /v1/company-charges/updateAdmin.
  • Excluir (lixeira): abre um bottom-sheet de confirmação; ao confirmar, chama POST /v1/company-charges/deleteAdmin e recarrega a página.

Step-up / MFA

Operações de folha são movimentações financeiras sensíveis. Conforme a configuração do tenant, ações de pagamento podem exigir step-up (re-autenticação senha + MFA, header X-Step-Up-Token, janela de 5 min). Se solicitado, conclua o re-login antes de a operação ser enviada.

Regras de negócio / cuidados ​

Atenção

  • O e-mail precisa corresponder a um usuário existente — caso contrário a tela bloqueia o salvamento.
  • A data final não pode estar no passado; a tela valida e impede confirmar.
  • O Dia define a primeira competência: dias já vencidos no mês jogam o primeiro pagamento para o mês seguinte; 29/30/31 em meses curtos são ajustados para o último dia.
  • A folha paga o funcionário (sai do owner). Não a confunda com cobranças que debitam o usuário.

Movimentação financeira recorrente

Cada parcela da folha transfere dinheiro real do owner para o funcionário. Revise valor, dia e competência final antes de salvar — parcelas já pagas não são estornadas pela exclusão.

  • Valores financeiros: tratados como BigNumber no scheduler — sem arredondamento; confira casas decimais da moeda/token.
  • Idempotência: cada parcela usa externalId igual ao id do agendamento de pagamento. Em reprocessamento após crash, o FinLib retorna E00021 ("already processed") — sucesso, não erro: o valor já foi pago e a parcela é marcada como aplicada.
  • Status APPROVED: o funcionário precisa estar aprovado para receber (carteira ou conta digital).

Exemplos ​

Cenário 1 — Salário mensal em BRL via conta digital

Empresa com DIGITAL_BANKING_CHARGES habilitado cadastra o funcionário joao@empresa.com, descrição "Salário", dia 5, último pagamento Dezembro/2026, valor R$ 4.500,00. Se hoje é dia 10, o primeiro pagamento cai em julho (dia 5 já passou). A cada mês até dezembro, o scheduler (CPM) credita R$ 4.500,00 da conta do owner para a conta digital do João via BMS giveUserBalance.

Cenário 2 — Pró-labore em token

Funcionário recebe em token (moeda diferente de BRL, ou com DIGITAL_BANKING_CHARGES desligado). Cada parcela vira uma transação de carteira do owner para a carteira do colaborador, no valor e descrição definidos. Útil quando o pagamento é feito em ativo digital e não pela conta bancária.

Cenário 3 — Ajuste de valor de um colaborador

O RH aumentou o salário. O operador abre a entrada pelo lápis, ajusta o Valor e confirma. O agendamento é atualizado (updateAdmin) e as próximas parcelas passam a usar o novo valor; as parcelas já pagas permanecem como estavam.

Telas relacionadas ​