Linha Microsiga Protheus

Árvore de páginas


01. VISÃO GERAL

Configurações necessárias para o registro de boletos online do banco Santander. Existem dois serviços de comunicação com o banco Santander, abaixo iremos destacar algumas características de cada serviço e como utilizar:

Serviço que utiliza comunicação no formato XML

Importante

Esse serviço foi descontinuado pelo banco, portanto novas implementações serão feitas apenas pela Cobrança por API

Serviço que utiliza comunicação no formato JSON.

Esse novo serviço foi disponibilizado após o cobrança por XML, e possui diversas vantagens em relação ao serviço de cobrança por XML.

Caso o ambiente esteja utilizando o serviço Cobrança por XML, você pode editar o seu layout e assim atualizar para a nova versão, depois de habilitar o serviço na conta e obter suas credenciais

Funcionalidade em desenvolvimento

O serviço Cobrança por API está em fase de desenvolvimento e em breve entrará em testes com clientes piloto, portanto ainda não está liberada em nenhum release do Protheus!

Será liberado através de pacote de expedição acumulado do módulo financeiro em data ainda a ser informada.

Essa página poderá sofrer alterações até a data de liberação da funcionalidade!

Rede interna

Cobrança por API → Para a comunicação do Protheus com o banco é necessário configurar a segurança de rede, caso necessário, para aceitar a saída da faixa de IP referente ao DNS: 

https://trust-open.api.santander.com.br

https://trust-sandbox.api.santander.com.br/


02. ITENS NECESSÁRIO (HABILITAR SERVIÇO NA CONTA)

Deve ser solicitado junto ao seu gerente a utilização do produto Cobrança por API (registro de boletos API).

Para estabelecer uma conexão segura com os API Gateways do Santander é necessário enviar um client certificate. Este certificado é usado para estabelecer o mTLS (OAuth 2.0 Mutual Transport Layer Security).

Mais detalhes do processo de geração do certificado devem ser obtidos no portal do SANTANDER : https://developer.santander.com.br/ ou https://developer.santander.com.br/user-guide. O acesso ao mesmo deve ser também solicitado ao seu gerente de conta.

Nesse processo será gerado dois arquivos, um com extensão CRT e outro KEY que serão utilizados no processo de configuração e layout do Novo Gestor Financeiro.

Será encaminhado pelo banco client id, client secret, arquivo do certificado, arquivo chave do certificado que deverão ser informados na configuração de contas.

03. CONFIGURAÇÃO DE CONTAS

Para habilitar a configuração de um layout para o Santander deve ser informado no campo A6_BCOOFI  ( Banco oficial )  o código do Santander 033.

O layout exige que a agência possua 4 posições (sem digito) e a conta 7 posições (sem digito). 

Importante

É necessário o cadastro correto do dígito verificador da conta no campo Dv Conta (A6_DVCTA).

Caso o cadastro esteja incorreto na tabela de bancos (SA6), o ajuste deve ser realizado em sua subconta no Cadastro Parâmetros de bancos (tabela SEE) nos campos Age. Oficial (EE_AGEOFI), Cta. Oficial (EE_CTAOFI) e DV Cta.Ofic. (EE_DVCTOFI).

Exemplo de conta que precisa ser adequada : Conta 12345-6

No cadastro do banco, campo Nro Conta (A6_NUMCOM) = 123456 e DV Conta (A6_DVCTA) = vazio, o ajuste em sua sub conta deve ser Cta. Oficial (EE_CTAOFI) = 12345 e DV Cta.Ofic. (EE_DVCTOFI) = 6

04. CONFIGURAÇÃO DA SUBCONTA

  • O código do Beneficiário da cobrança é configurado na subconta (tabela SEE) pela rotina Parâmetros de Banco (FINA130) no campo Cód. Empresa (EE_CODEMP).
    • Preencher com o convênio completo ou com os 7 dígitos conforme o exemplo abaixo:
      • Convênio completo: 00332271001912345674 → preencher no campo EE_CODEMP o valor 1234567
  • Se o nosso número for gerado pelo sistema, esse deve ser configurado na subconta (tabela SEE) pela rotina Parâmetros de Banco (FINA130) nos campos Faixa Inicio (EE_FAXINI), Faixa Fim (EE_FAXFIM) e Faixa atual (EE_FAXATU).
  • O endereço do cliente deve ter o número separado por vírgula para que seja encaminhado corretamente ao sistema do banco.
  • A configuração para "PROTESTO" de boletos terá como base o campo EE_DIASPRT (Dias para protesto), se este campo estiver preenchido com valor maior que 0 (zero) o layout será configurado como "PROTESTAR" e o numero de dias será o valor do campo. Caso contrario será configurado com "DEVOLVER" em 02 dias.
  • Código da carteira deve ser informado no campo Cód. Carteira (EE_CODCART).
  • Mensagem para instrução de cobrança deve ser informada no campo Mensagem 1 (EE_FORMEN1), vale ressaltar que o banco aceita no máximo 165 caracteres. Recomendamos o uso de letras minúsculas, pois na impressão do boleto existe um espaço pré-definido para exibição da mensagem.

05. CONFIGURAÇÃO DO LAYOUT

           Para a configuração da etapa de Credenciais será necessário obter junto ao Santander as informações abaixo:

           → Client ID - ID do Cliente: Código de identificação do cliente

           → Client Secret - Chave Secreta do Cliente: Chave secreta de validação do cliente.

           → Arquivo Chave do Certificado - Arquivo de chave do certificado com a extensão key.

           → Arquivo de Certificado - Arquivo de certificado com a extensão crt.

           Os arquivos de certificado devem ser salvo dentro da pasta cert/ngf (protheud_data).


Também deve-se observar as seguintes regras, na transmissão por API do banco Santander:

  • Nosso Número: será enviado ao banco um sequencial de 13 posições, que é composto pela seguinte regra:  sequencial (12 posições) + digito verificador do sequencial (1 posição)

Ex.: Nosso Número com sequencial 999999999999 será enviado como 9999999999996 sendo o número 6 o digito verificador.


  • Número do documento: Neste campo deverá ser informado qual será o número do documento que será transmitido ao banco e posteriormente impresso no boleto.

      Onde poderá ser:

    1. Número do Título (E1_NUM)
    2. ID CNAB (E1_IDCNAB)
    3. Expressão definida pelo usuário.
      • O resultado da expressão será atribuído ao campo “Número do documento”. Para as macros-execuções a expressão a ser executada deverá ser válida. Para informar uma expressão clique na “Engrenagem” que está ao lado do campo.



  • Aceite: Este campo indica o reconhecimento formal da divida (assinatura no documento) pelo pagador, deverá ser informado os valores:
    • Sim - Quando existe a necessidade do pagador reconhecer/aceitar a cobrança.
    • Não - Quando não existe a necessidade de reconhecimento da cobrança.

  • Beneficiário Filial: Neste campo deverá ser informado qual filial que será utilizada para a transmissão e impressão do boleto. 

Os dados cadastrados nessa filial serão utilizados na transmissão e na impressão:


Atenção

Caso este campo não esteja preenchido a Filial Atual (Filial Logado ou Filial configurada no agendamento) será utilizada no dados da transmissão e impressão do boleto.


  • Valor Abatimento: Neste campo poderá ou não ser informado um valor de abatimento para o boleto.  

       Onde poderá ser:

    1. Vazio - Caso o valor nominal já esteja calculado com a dedução dos valores de abatimento ou não exista abatimento para o boleto.
    2. Valor Abatimento (SomaAbat()) - Calculo padrão do sistema conforme a expressão: "SomaAbat(SE1->E1_PREFIXO,SE1->E1_NUM,SE1->E1_PARCELA,"R",SE1->E1_MOEDA,dDataBase,SE1->E1_CLIENTE,SE1->E1_LOJA)" .
    3. Expressão definida pelo usuário.
      • O resultado da expressão será atribuído ao campo “Valor Abatimento”. Para as macros-execuções a expressão a ser executada deverá ser válida. Para informar uma expressão clique na “Engrenagem” que está ao lado do campo.


É possível informar o valor nominal já deduzindo o valor do abatimento. Basta clicar na engrenagem no campo "Valor Nominal" e informar uma expressão válida:

Exemplo:

    • "SE1->E1_SALDO - SomaAbat(SE1->E1_PREFIXO,SE1->E1_NUM,SE1->E1_PARCELA,"R",SE1->E1_MOEDA,dDataBase,SE1->E1_CLIENTE,SE1->E1_LOJA)"

Importante

Caso o valor nominal já esteja calculado com a dedução dos valores de abatimento, o campo "Valor Abatimento" não deve ser preenchido para que não ocorra uma duplicidade no valor de abatimento.

Caso o campo "Valor Abatimento" seja preenchido o campo "Valor Nominal" deverá conter o valor cheio (Sem a dedução do abatimento). Caso exista abatimento será exibida uma mensagem no corpo do boleto informando o valor do abatimento já calculado.


  • Boleto Híbrido (Boleto + Pix): Define se irá utilizar QR Code Pix para pagamento no boleto. Para utilizar essa funcionalidade é preciso configurar a chave pix para o banco no cadastro de banco(MATA070) → Outras Ações → Chaves pix. (boleto híbrido disponível apenas para Cobrança por API).


06. WEBHOOK E FINA715 - RETORNO

           Webhook

           →  Url de Webhook do Santander deve ser configurado na Configuração de Contas do NGF conforme a seguir:

                https://seuendereco:suaporta/api/fin/v1/bb/santander/receivables/

                seuendereco:suaporta → Informar endereço e porta do serviço REST configurado no arquivo appserver.ini.

                /api/fin/v1/bb/santander/receivables/ → API disponível no serviço REST padrão do Protheus preparada para receber o payload de cobrança(boletos) do Santander.       

           A mesma url de Webhook recebe evento de pagameto de boletos pagos via código de barras e pagos via QR Code (Pix).

           O processamento é diferente quando o boleto é pago via código de barras e quando o boleto é pago via QR Code.

          → Pagamento via QR Code (Pix):

                - Boleto já é considerado liquidado e a baixa do título no Protheus é iniciada assim que o Protheus recebe a requisição do banco Santander.

          → Pagamento via Código de Barras:

                - Boleto ainda não pode ser considerado liquidado (Em alguns casos pode ser cancelado ou estornado ao longo do dia pelo banco).

                - A baixa do título não é realizada no momento que o Protheus recebe a comunicação via Webhook. A baixa será processada posteriormente via job FINA715. Para mais detalhes clique aqui.

           FINA715

           →  Banco Santander segue o processo de bancos que não possuem API de listagem. Para mais detalhes clique aqui.