Pagamento via boleto

1. Recepção de Dados do ERP Externo

• Micro serviço: erpx-bnk-pag-register-boleto
• Ação:
  • O micro serviço escuta a comunicação vinda do ERP externo;
  • Quando uma solicitação é recebida, chama a API registerBankSlipPayment.
• API chamada: registerBankSlipPayment
• Parâmetros: Banco, empresa, filial, pagador e uma lista de títulos que serão registrados para pagamento;
• Validação:
  • Valida o payload recebido;
  • Se o payload estiver correto, prossegue para a próxima etapa.

2. Integração com Foundation

• Micro serviço: erpx-bnk-pag-boleto;
• API chamada: realizarIntegracoesFoundation
• Ação:
  • Integra as informações recebidas com o Foundation;
  • Verifica se precisa criar ou atualizar os registros (empresa, filial, pagador) para cada título:
    • Atualiza: Se o registro existir, ele é atualizado com as novas informações recebidas;
    • Cria: Se o registro não existir, um novo é criado;
• API chamada: registrarPagamentoBoletoAsync
• Ação:
  • Realiza validações de regras de negócio;
  • Persiste os dados no banco de dados.

3. Processamento das Validações

• Resultado das Validações:
  • Falha na validação: A situação do item é marcada como FALHA_NA_VALIDACAO;
  • Título já processado: Se o título recebido já foi processado anteriormente e está com uma das situações PAGAMENTO_EFETUADO, PAGAMENTO_AGENDADO, AGUARDANDO_PAGAMENTO, ou PROCESSANDO_ENVIO_PAGAMENTO, a situação é alterada para PAGAMENTO_INAPTO_PARA_PROCESSAMENTO;
  • Validação bem-sucedida: Se tudo estiver correto, a situação do título é marcada como AGUARDANDO_PAGAMENTO.

4. Verificação e Processamento dos Registros

• Ação: Verifica se há registros para processar;
• Nenhum registro:
  • Chama a API finalizarPagamento que finaliza o processo e comunica o ERP para continuar o processo internamente.
  • API chamada: finalizarPagamento
  • Ação:
    • Atualiza a situação da entidade pagamentoDadosBoleto para FINALIZADO;
    • Recupera todos os itens vinculados ao lote recebido que tiveram erro no processo;
    • Notifica o ERP disparando o evento bankSlipScheduled para que o ERP trate o erro e envie novamente.
• Existem registros:
  • Chama a API executarIntegracaoParceiro.
  • Ação:
    • Atualiza a situação dos títulos aptos para integração de AGUARDANDO_PAGAMENTO para PROCESSANDO_ENVIO_PAGAMENTO;
    • Cria um histórico do processamento;
    • Monta o payload e dispara o evento conforme o parceiro configurado.

5. Retorno das Informações do Parceiro

• API de fachada: retornoPagamentoESales
• Ação:
  • Mapeia os valores recebidos para o DTO padrão do banking, para padronizar o processo para todos os parceiros implementados.
  • Verificação de status:
    • Status: ENVIADO_AO_BANCO, ERRO_DE_COMUNICACAO, INVALIDO;
      • Assim que a solicitação de pagamento é encaminhada, o retorno é assíncrono;
      • O parceiro (eSales) monta o arquivo e envia para o banco.
      • Retorno:
        • Se a solicitação foi bem-sucedida, retorna ENVIADO_AO_BANCO;
        • Se houve problemas, retorna ERRO_DE_COMUNICACAO ou INVALIDO.
      • Chama a API retornoEnvioPagamento para tratar o envio do pagamento ao banco.
    • Novo arquivo: O banco gera um novo arquivo de retorno.
      • A eSales recupera e envia para o Banking;
      • Status do arquivo: INCLUIDO ou REJEITADO;
      • Chama a API retornoConfirmacaoAgendamento;
      • Na última etapa, quando o pagamento foi realmente LIQUIDADO chama o signal retornoPagamentoEfetuado.

6. Confirmação do Envio ao Banco

• Ação: Verifica se houve erro no envio.
  • Sem erro:
    • Atualiza a situação do pagamento para PAGAMENTO_ENVIADO;
    • Cria um registro de histórico;
    • Verifica se todos os títulos do lote foram processados para finalizar o processo.
  • Com erro:
    • Atualiza a situação do pagamento para PAGAMENTO_COM_PROBLEMAS;
    • Cria um registro de histórico;
    • Armazena os erros recebidos;
    • Verifica se todos os títulos do lote foram processados para finalizar o processo.

7. Retorno da Confirmação do Agendamento

• API chamada: retornoConfirmacaoAgendamento
• Ação: Recupera e verifica se o pagamento foi agendado.
  • Pagamento agendado:
    • Atualiza a situação do pagamento para PAGAMENTO_AGENDADO.
  • Pagamento não agendado:
    • Atualiza a situação do pagamento para PAGAMENTO_NAO_AGENDADO.
  • Finalização:
    • Cria um registro de histórico;
    • Monta o payload;
    • Dispara o evento bankSlipScheduled.

8. Confirmação do Pagamento Efetuado

• API chamada: retornoPagamentoEfetuado
• Ação:
  • Recupera os pagamentos da base de dados;
  • Cria um registro na tabela pagamentoItemBoletoRegistro;
  • Atualiza a situação do pagamento para PAGAMENTO_EFETUADO;
  • Cria um registro de histórico;
  • Monta o payload;
  • Dispara o evento bankSlipPaid;
  • Finaliza o processo.

Documentação

• Pagamento de boleto integrado com o parceiro eSales, conforme documentação eSales.

Bancos Aceitos

• BB;
• Bradesco;
• CEF;
• Itaú;
• Santander;
• Sicredi.

Comunicação

• Comunicação assíncrona conforme tecnologia e estrutura do ERP Banking;
• Limitação de 100 pagamentos por chamada.

Eventos de Webhook Tratados

• Enviado ao banco, Inválido ou Erro de comunicação;
• Incluído ou Rejeitado;
• Liquidado.

Regras e Limitações

• Dígito da agência e da conta serão opcionais para alguns bancos e devem ser string;
• A API aceitará as informações de pagamento como linha digitável ou código de barras;
• É utilizado o foundation para a empresa e filial;
• Data de pagamento deve ser atual ou futura (não é possível enviar pagamento com data passada);
• Data de vencimento pode ser uma data passada, desde que as informações do pagamento sigam as instruções de juros e multa do boleto;
• O campo seunúmero tem um limite de 20 caracteres e é padrão para todos os bancos;
• Não será enviado o TXID para a eSales.

Ocorrências de Retorno

• As ocorrências de retorno não são separadas por motivo + ocorrência e seguem a classificação conforme esta planilha.

Informar o nome do banco do pagamento.

Bancos aceitos:

• Banco do Brasil - 001;
• Santander - 033;
• Caixa Econômica Federal - 104;
• Bradesco - 237;
• Itaú - 341;
• Sicredi - 748.

Informação obrigatória.

Informar os dados da empresa que fará a solicitação do pagamento:

• id: identificador da empresa;
• code: código da empresa.

Todos os campos são opcionais, mas pelo menos um deles devem ser enviados para geração do pagamento;

Informar os dados da filial que fará a solicitação do pagamento:

• id: identificador da filial;
• code: código da filial;
• documentNumber: número do documento (CPF/CNPJ);
• nifNumber: número de identificação fiscal.

Todos os campos são opcionais, mas pelo menos um deles devem ser enviados para geração do pagamento.

Informar os dados do pagador:

• covenant: convênio;
• branchNumber: número da agência;
• branchDigit: dígito da agência;
• accountNumber: número da conta;
• accountDigit: dígito da conta.

Observações

• Os campos Convênio (covenant), Número da agência (branchNumber) e Número da conta (accountNumber) são obrigatórios;
• Como existem agências e contas que não possuem dígito, os dígitos das agências e contas são opcionais.

Informar os dados do título para registrar o pagamento:

• accountPayableId: identificador do título;
• accountPayableNumber: número do título;
• accountPayableType: tipo do título;
• barCode: código de barras;
• favored: identificador do favorecido;
• dueDate: data de vencimento;
• payableDate: data do pagamento.

Observações

• Os campos de Avalista(guarantor) e Aviso ao favorecido (favoredAlert) são opcionais;
• O campo values é obrigatório, mas é necessário apenas informar o campo Valor Original (original). os demais campos de Juros (interest), Multas (assessment), Abatimentos (rebate) e Desconto (discount) são opcionais;
• O favored é composto pelos campos: Número do documento (documentNumber) e o Nome (name).