Cobrança via boleto

1 - Escuta de Comunicação Inicial:

• O micro serviço erpx-bnk-cob-register-boleto é responsável por escutar requisições vindas de um ERP externo.

2 - Chamada da API registerBankSlipBilling:

• A API é chamada com os seguintes parâmetros:
  • banco: Informações sobre o banco onde o boleto será registrado;
  • beneficiário: Dados do beneficiário do boleto;
  • lista de títulos a receber: Uma lista contendo os títulos que serão registrados como boletos;
• Esta chamada inicia o processo de registro de boletos.

3 - Validação de Payload:

• O payload recebido na API registerBankSlipBilling é validado para verificar se todas as informações necessárias estão presentes e corretas.

4 - Chamada da API realizarIntegracoesFoundation:

• Esta chamada ocorre dentro do micro serviço erpx-bnk-cob-boleto;
• O sistema verifica se o cliente de cada título já está cadastrado:
  • Se não estiver, procede-se com o cadastro do cliente.

5 - Chamada da API registrarCobrancaBoletoAsync:

• Realiza as validações de negócio necessárias;
• Para títulos que não passam nas validações:
  • A API finalizarCobranca é chamada para atualizar a situação dos títulos para Finalizado e notificar o ERP externo dos erros através do evento bankSlipCreated.

6 - Processamento de Títulos Válidos:

• Para os títulos que passaram pelas validações:
  • A API executarIntegracaoParceiro é chamada;
    • Atualiza a situação dos títulos para Processando;
    • Monta o payload de acordo com as especificações do banco;
    • Envia o payload para o sistema parceiro (eSales) e aguarda retorno.

Fluxo de Erros

• Notificação de Erros:
  • Títulos que não cumprem as validações de negócio são marcados como Finalizado e um evento bankSlipCreated é emitido para notificar o ERP externo dos erros encontrados.

Fluxo de Retorno

A API de fachada de retorno fica no micro serviço erpx-bnk-cob-cobranca é a action retornoCobrancaESales . O Retorno do parceiro acontece em 3 etapas:

1. Retorno da Cobrança (API retornoEnvioCobranca): Quando não ocorre erro, o parceiro notifica o Banking de que o boleto está em processamento. Caso ocorra erro, o retorno é Null. Esta API recupera as cobranças da base e realiza um loop nos títulos para verificar erros, preenchendo tabelas de histórico e erros se necessário. Verifica se todos os títulos estão processados e, se estiverem, chama o signal finalizarCobranca. Ocorre no micro serviço erpx-bnk-cob-boleto;
2. Confirmação de Envio (API retornoConfirmacaoCobranca): Após o envio para o banco, esta API verifica se o arquivo foi aceito (Ativo) ou negado (Negado).
3. Retorno Final do Banco (API retornoPagamentoCobranca): Quando o banco aceita o arquivo e a cobrança está ativa, o retorno final é Concluída.

Todas essas APIs de retorno ficam hospedadas no micro serviço erpx-bnk-cob-boleto.

O processo de cobrança via boleto pelo ERP Banking contempla os seguintes aspectos da implementação e restrições operacionais:

1- Geração de Boletos através do ERP externo

• O cliente que utiliza o ERP externo possui duas opções para a geração de boletos:
  • Terceirização para o banco: O cliente pode optar por terceirizar a geração do boleto, permitindo que o banco gere e envie o boleto para o recebimento no ERP senior X;
  • Geração pelo sistema do cliente: o cliente pode gerar o boleto diretamente usando seu sistema de ERP externo, para posterior recebimento no ERP senior X.
• Campo nossoNumero: este campo é opcional. No entanto, se o ERP externo gerar o boleto com este campo informado, o ERP Senior X executará automaticamente a validação do tamanho, conforme as regras específicas de cada banco:
  • Itaú: 08 posições;
  • Bradesco: 11 posições;
  • CEF: 17 posições;
  • BB: 17 posições;
  • Santander: 08 posições;
  • Sicredi: 09 posições;
  • BTG: 20 posições.
• Se o valor máximo for excedido, é exibida a seguinte mensagem de erro: "Para o [BANCO], só é permitido informar até [VALOR MÁXIMO] caracteres para o campo nosso número."

2 - Dados do Avalista:

• O avalista é identificado como a filial do ERP, mas os dados (nome e documento) são fornecidos diretamente pela API.

3 - Limitações de Títulos:

• O limite é de 100 títulos por chamada API.

4 - Controle de Resposta:

• Não há controle de resposta por lote, dado que a confirmação de emissão do boleto não é instantânea.

5 - Endereço do Devedor:

• O endereço utilizado é o principal registrado no cadastro de pessoas do foundation.

6 - Campo SeuNúmero:

• Deve ser fornecido pelo ERP externo, com os seguintes critérios específicos por banco:
  • Sicredi - 10 Posições (Não pode conter espaços);
  • Santander - 10 Posições;
  • CEF - 10 Posições;
  • BB - 10 Posições;
  • Bradesco - 25 Posições;
  • Itaú - 25 Posições;
  • BTG: 10 posições.

  Importante: Não é permitida a duplicidade no campo SeuNúmero.

7 - Validações:

• Em caso de beneficiário e avalista idênticos, a transação será recusada pelo banco;
• O banco BTG atende exclusivamente pessoas jurídicas. Assim, ao utilizar seus serviços, o CPF não é aceito, sendo necessário informar o CNPJ.

8 - Data de Emissão:

• É gerenciada pelo sistema bancário, eliminando a necessidade de controle pelo ERP.

9 - Gestão de Ocorrências:

• Criação das tabelas ocorrenciaBanco e motivoOcorrenciaBanco;
• As ocorrências e seus motivos são recebidos no mesmo JSON, mas enviados separadamente ao ERP;
• Ocorrências ou motivos não mapeados geram logs de erro e são devolvidos ao ERP com uma descrição genérica.

10 - Histórico de Transações:

• Histórico detalhado das ocorrências relacionadas a cada boleto.

11 - Abordagem de Fachada:

• Adotada a mesma estratégia de fachada usada para o PIX Cobrança, visando minimizar problemas de comunicação entre ERP e sistema bancário.

12 - Consulta de Endereços:

• A busca de endereços é feita considerando as seguintes formas:
  • Cidade: id ou codrai;
  • Estado: id ou uf;
  • País: id ou codPai.
• Obs.: Para busca do país é utilizado o código do SPED.

13 - Controle de Retorno de Lote:

• Não é feito controle de retorno de lotes para o ERO.
• Por exemplo, o envio de 100 títulos pode não resultar na devolução simultânea dos mesmos no evento bankSlipCreated;.

14 - Descontos e Abatimentos:

• Controle para que o desconto ou abatimento não exceda 100% do valor nominal do título;
• Obs.: O banco Itaú especificamente não permite descontos superiores a 90% do valor nominal.

Informar o nome do banco que deseja realizar a cobrança:

Bancos aceitos:

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

Informação obrigatória.

Informar os dados do beneficiário:

• name: Nome do beneficiário;
• documentNumber: Número do documento;
• 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ção

• Os campos de Nome do beneficiário (name), Dígito da agência (branchDigit) e Dígito da conta(accountDigit) são opcionais;

Informar os dados do título para registrar a cobrança:

• accountReceivableId: Identificador do Título;
• accountReceivableNumber: Número do Título;
• accountReceivableType: Tipo do Título;
• generatePixQrCode: Gera no boleto um QR Code para pagamento via Pix;
• yourNumber: Número de identificação do boleto no sistema emissor;
• customer: Identificador do Cliente;
• dueDate: Data de Vencimento;
• specie: Espécie;
• wallet: Carteira;
• ourNumber: Número de identificação do boleto no banco;

Observações

• Os campos de Avalista (guarantor), Protesto (protest), Mensagens (messages), Espécie (specie), Carteira (wallet), Número de identificação do boleto no banco (ourNumber) e Pix QR Code (generatePixQrCode) são opcionais;
• O campo Pix QR Code (generatePixQrCode), caso não seja preenchido, retorna por padrão o valor Falso. Já, ao preencher este campo como Verdadeiro, o código retornado pelo banco fica disponível no campo Pix copia e cola, localizado nos Detalhes do boleto. Além disso, o boleto é gerado com o QR Code para pagamento via Pix. Essas funcionalidades estão disponíveis apenas para o banco BTG.
• O campo values é obrigatório, mas só é necessário informar o campo Valor Original (original). Os demais campos de Juros (interest), Multas (assessment), Abatimentos (rebate) e Desconto (discount) são opcionais;

O campo de Customer deve ser informado:

• id: Identificador do cliente;
• CPF/CNPJ, documentNumber: Número do documento;
• name: Nome;
• tradeName: Nome fantasia;
• address: Endereço;
• email: E-mail;
• phoneNumber: Número do telefone.
Detalhes da composição do endereço do cliente

adress é composto pelo país, estado, cidade, cep, bairro e a rua. O campo Bairro (neighborhood) é opcional.

"address": {
                    "street": "string",
                    "neighborhood": "string",
                    "country": {
                        
                        "id": "string"
                    },
                    "state": {
                        
                        "code": "string"
                    },
                    "city": {
                        
                        "id": "string"
                    },
                    "postalCode": "string"
                }	

Observações

• Todos os campos são opcionais. Entretanto, é necessário informar ao menos um destes campos: Identificador do cliente (id) ou Número do documento (CPF/CNPJ) (documentNumber).
• Se o Número do documento enviado for CPF ou documentNumber, deve ser informado o campo Nome (name).
• Se o Número do documento enviado for CNPJ, deve ser informado o Nome fantasia (tradeName);

• Informar o campo Tipo de cálculo (calculationType), que será buscado do enumCalculationTypeInterest e o campo Valor ou Percentual (valueOrPercentage).
  • O enumCalculationTypeInterest representa a modalidade de juros para a cobrança.

• Informar o campo Tipo de cálculo (calculationType) que será buscado do enumCalculationType e o campo Valor ou Percentual (valueOrPercentage).
  • O enumCalculationType representa a modalidade de abatimento para a cobrança.

• Informar o campo Tipo de cálculo (calculationType), que será buscado do enumCalculationTypeDiscount , Valor ou Percentual (valueOrPercentage) e o campo Descontos definidos de acordo com a data estabelecida (discountFixedDate).
  • O enumCalculationTypeDiscount representa a modalidade de desconto para a cobrança.

A API pública registerBankSlipOperation é responsável por receber informações de um ERP externo para realizar operações específicas. Ela requer o envio do processo, tipo de operação e uma lista dos títulos que serão processados.

Atualmente, as operações disponíveis com o parceiro eSales incluem a alteração de data de vencimento e a modificação de protesto.

Para garantir o correto processamento das operações, são realizadas as seguintes validações:

Validações

• Não é permitido informar mais de 100 identificadores para o campo accountsReceivableId.
  • Caso esse número seja ultrapassado, uma exceção é disparada indicando que o limite de requisição é de 100 títulos.
• Não é permitido informar valores duplicados para o campo accountsReceivableId.
  • Caso isso ocorra, uma exceção é disparada indicando que títulos duplicados foram informados.
• Não é permitido informar uma string vazia no campo processId.
  • Caso ocorra, uma exceção é disparada indicando que o campo deve ser preenchido.
• Não é permitido informar identificadores inválidos no campo accountsReceivableId.
  • Caso exista algum indicador inválido, uma exceção é disparada indicando que o identificador está inválido.
• Validação do banco. Se o banco não for BTG e receber as operações ALTERAR_VALOR, ALTERAR_JUROS, ALTERAR_MULTA, ALTERAR_DESCONTO:
  • Dispara exceção informando que as operações não estão disponíveis para o banco informado.
• Quando a operação for BAIXAR, PROTESTAR, SUSTAR_PROTESTO:
  • Dispara exceção informando que as operações não estão disponíveis para o banco BTG.
• Quando a operação for ALTERAR_DATA_VENCIMENTO:
  • A nova data de vencimento deve ser maior que a data atual.
• Quando a operação for ALTERAR_JUROS:
  • Se o tipo de juros for PERCENTUAL, a taxa percentual dos juros deve ser menor que 100%;
  • Se o tipo de juros for VALOR_FIXO, o valor dos juros deve ser menor que o valor do título.
• As mesmas regras do juros se aplicam ao desconto.
• A data limite do desconto deve ser menor que a data de vencimento do titulo.

Após as validações, se tudo estiver correto, a API privada registrarOperacaoBoletoAsync é chamada. Esta API recebe as mesmas informações da registerBankSlipOperation.

Processamento dos Títulos

Para cada título recebido, é feita uma busca na entidade cobrancaItemBoleto para verificar a sua situação atual:

• Se a situação for igual a COBRANCA_GERADA, o processamento é permitido;
• Se a situação for diferente de COBRANCA_GERADA, o processamento não é permitido, e a situação do título é alterada para OPERACAO_NAO_PERMITIDA;
• Se o título estiver apto para processamento, sua situação é atualizada para PROCESSANDO_OPERACAO.

Além disso, é vinculado o registro na entidade cobrancaItemBoleto e criado um registro correspondente na entidade de histórico.

Agrupamento e Execução das Operações

Após a verificação dos títulos aptos para processamento:

• Os títulos aptos são agrupados por banco;
• A API executarOperacaoESales é chamada para os títulos aptos, atualizando a situação deles e criando o registro histórico. Um payload é montado e o evento iniciarIntegracaoOperacaoBoletoESales é disparado. Após o envio de todos os títulos, a primitiva finalizarOperacao é chamada.

Finalização das Operações

A API finalizarOperacao atualiza a situação da entidade OperacaoBoleto para FINALIZADO e dispara o evento operationSent.

Retorno das Operações

A API retornoCobrancaESales é utilizada para retornar informações do parceiro. Essa API pode receber retornos de cobranças de diferentes modalidades, como Boleto, PIX e outras, na mesma lista de cobranças. Portanto, é necessário iterar pela lista de cobranças recebidas e separá-las em listas específicas para cada cenário.

Após iterar por cada cobrança e preencher as listas:

• Se o retorno for de operações, os valores são mapeados para o Banking, e a API retornoOperacoes é chamada;
• A API retornoOperacoes recupera as cobranças da base de dados, itera sobre os resultados recebidos, atualiza a situação do boleto, cria registros históricos e dispara o evento operationFinished.

• processId: identifica o processo que está sendo executado;
• operationType: a operação que será executada;
• accountsReceivableId: lista dos títulos das operações;
• dueDate e protest: As operações possíveis junto ao parceiro eSales atualmente são: alteração de data de vencimento e de protesto. Ambos são opcionais;
• newValue, interest, assessment e discount: As operações possíveis junto ao parceiro BTG são: alterações do valor do boleto, do juros, da multa ou do desconto.

A API não retorna dados específicos em uma resposta de sucesso. Uma resposta bem-sucedida é indicada pela ausência de erros e pelo código HTTP 200.

Possíveis códigos de resposta da API:

• 400 - Requisição inválida: Parâmetros obrigatórios não foram informados ou algum campo foi preenchido incorretamente;
• 403 - Permissão negada: O usuário não possui permissão para realizar essa ação;
• 404 - Registro não encontrado: O registro não foi localizado com base no ID ERPX ou na chave de negócio fornecidos.

"Query de listagem do status dos títulos de cobrança boleto
### Resources
- res://senior.com.br/erpx_bnk_cob/register_boleto/queries/getStatusBankSlipBilling"
public query getStatusBankSlipBilling {
    in {
        "Filtro"				
        filter : recFilterGetStatusBankSlipBilling?
        "Controle de paginação e ordenação"
        pageRequest : recPageRequest
    }
    
    out {
        "Dados da cobrança boleto"
        recBankSlipBilling : recBankSlipBilling*
    }
    
    responses {
        400 : "Requisição inválida, parâmetros obrigatórios não informados ou campo informado incorretamente"
        403 : "Permissão negada"
        404 : "Registro não encontrado"
    }
}

recFilterGetStatusBankSlipBilling

• Filtro de status dos títulos de cobrança Boleto;
• Se o filtro incluir IDs de títulos e um intervalo de datas, a consulta prioriza os IDs, desconsiderando as datas informadas;
• Caso o ID não seja informado, é obrigatório fornecer uma data inicial e uma data final. A data inicial não pode ser futura, e o intervalo entre as datas deve ser de, no máximo, 7 dias corridos.
• O filtro aceita apenas IDs, apenas datas ou uma combinação de IDs e datas.