Exemplo: Folha da pagamento

Exemplo de integração com folha de pagamento através de eventos e requisições

Este guia explica como receber informações das parcelas para fazer os descontos na folha de pagamento em tempo real através de eventos.

1. Consultar parcelas

Você pode consultar as parcelas através de assinatura de eventos, em tempo real, ou eventualmente através de uma requisição.

Através de eventos

Faça a assinatura dos eventos através do Criar uma assinatura. Esses são os eventos relevantes para esse caso de uso:

  • installment.created
    • Ocorre quando uma parcela é criada.
  • installment.voided
    • Ocorre quando uma parcela é anulada.
  • installment.paid
    • Ocorre quando uma parcela é paga integralmente.
  • installment.unpaid
    • Ocorre quando uma parcela volta a ser devida. Pode ocorrer quando acontece um reembolso ou posterior falha no pagamento recebido.
  • installment.transaction.created
    • Ocorre quando uma transação é adicionada ao extrato da parcela. Pode ocorrer, por exemplo, em um pagamento parcial. Nesses casos é importante consultar o amountRemaining através do Obter uma parcela.

Os dados de uma parcela não podem ser alterados. Em alguns cenários, o plano de pagamento do empréstimo pode ser alterado. Nesses casos a parcela é anulada e criada com novos dados.

Através de requisições

Utilize o Listar todas as parcelas para consultar as parcelas que devem ser descontadas.

Recomendamos o uso dos filtros due_date_start, due_date_end e status para consultar somente as parcelas necessárias.

Exemplo:
/v1/installments?due_date_start=2023-01-01&due_date_end=2023-01-31&status=unpaid

2. Informar desconto da parcela

Após o processamento da folha de pagamento os valores descontados precisam ser informados através de uma fatura para que a cobrança da empresa seja feita e o status de cada parcela seja atualizado para o cliente.

  1. Utilize o Criar uma fatura para criar uma fatura rascunho. Crie pelo menos uma fatura por empresa/convênio. As intenções de pagamento, como boletos, são criadas posteriormente por fatura.
  2. Utilize o Criar um item em uma fatura para adicionar as parcelas descontadas na respectiva fatura. Se o valor da parcela não foi descontado integralmente, informe apenas o valor descontado em amount. O campo discount deve ser usado somente para casos de antecipação de pagamento ou realmente um desconto que o cliente não será cobrado.
  3. Após adicionar todos os itens da fatura, utilize o Finalizar uma fatura. Não é possível adicionar itens após fechar uma fatura. Você pode anular uma fatura fechada e/ou criar uma nova fatura.
  4. Com a fatura fechada, utilize o Criar uma intenção de pagamento para gerar um boleto a qualquer momento. É recomendável gerar as intenções de pagamento somente quando o cliente solicitar o boleto para evitar custos desnecessários com as emissões.

3. Casos de excessão

Se necessário, você pode alterar o responsável pelo pagamento de uma parcela.

  1. Utilize o Obter uma parcela para consultar as informações atualizadas.
  2. Utilize o Criar uma parcela para criar uma nova parcela com as alterações desejadas.
  3. Utilize o Anular uma parcela para anular a parcela original.