GF - Como Fazer - Open Banking

Objetivo

O open banking CIGAM é um projeto que visa implementar as APIs bancárias (interfaces online de comunicação) nos módulos financeiros do ERP CIGAM. O maior benefício obtido com estas integrações é a eliminação do uso de arquivos CNAB (*.txt) e a migração para uma conexão direta com o banco. Assim o usuário passa a fazer tudo dentro do CIGAM sem precisar entrar no gerenciador financeiro do banco.

Com base em estatísticas colhidas com nossos clientes, após a implementação do open banking CIGAM é possível reduzir cerca de 5 a 8 horas semanais de envolvimento com os gerenciadores bancários! Isso é mais tempo para o que realmente importa!

O presente manual visa apresentar o escopo completo do projeto Open Banking para tudo aquilo que é comum a todos os bancos. Para as dicas e orientações de instituições específicas, acesse o manual de cada banco.

APIs atendidas por instituição

No quadro abaixo são apresentadas as instituições participantes do escopo do open banking e os serviços disponibilizados pelas mesmas bem como se este serviço já está sendo atendido no CIGAM.

Arquivo:Bancos Disponiveis Atualmente RC 221107.png

* Ainda não disponível no CIGAM

Migrando um cliente do CNAB para a API Open Banking

A migração para o Open Banking de um cliente que hoje está utilizando CNAB deve ocorrer de forma transparente, o que está mudando é a forma de registro e não o registro em si. Pense no CNAB como um envio via carta, e o Open Banking como um e-mail, a mensagem chegará de ambas as formas, porém na primeira você precisa levar a mensagem escrita à mão até o correio, já a segunda você digita e envia de casa.

Essa troca de formato possibilita que quando um cliente tiver o seu CIGAM configurado no open banking ele poderá imediatamente realizar o retorno via API e irá obter as informações dos títulos registrados na instituição independentemente da forma de registro previamente utilizada. Inclusive, o método de registro via CNAB continua valendo simultaneamente ao uso da API. Desta forma, embora alguns bancos disponibilizem ambientes de homologação, não recomendamos a criação de movimentos de teste nestes uma vez que existem restrições de CPF/CNPJ exclusivos para teste.

Configurando APIs Open Banking para clientes novos em período de implementação

Para clientes novos (em projeto), que não tem como registrar títulos oficiais no CIGAM, recomendamos avaliar a sessão “testes em homologação” nos manuais de cada banco para verificar as parametrizações necessárias.

Obtenção de credenciais - Instruções Gerais

A comunicação entre o CIGAM e as APIs Open Banking é iniciada através da validação de credenciais entre as duas partes. Estas credenciais podem variar de códigos de identificação como Client_ID e Client_Secret até o uso conjunto de certificados digitais, de forma semelhante à comunicação entre CIGAM e SEFAZ da Nota Fiscal Eletrônica (NFe).

Invariavelmente, para obter as suas credenciais, você deverá acessar primeiro o seu Gerente Cash ou gerente de conta PJ na instituição em que está buscando as credenciais. Em muitos casos, ele irá abrir um chamado técnico junto à área responsável para iniciar o seu processo de credenciamento seja através de um portal ou e-mail.

NOTA AOS SETORES DE ATENDIMENTO E IMPLEMENTAÇÃO CIGAM: é imprescindível ter os dados de credenciais, certificados digitais, scopes etc. em mãos, a primeira página do assistente open banking irá indicar as informações necessárias para cada banco. Recomendamos que o trabalho de implementação/atendimento só seja iniciado após a confirmação da existência de tais dados, uma vez que não está dentro das nossas possibilidades obter tais informações.

Uso e Gestão dos certificados digitais nas credenciais Open Banking

Itens como “Client_ID” e “Client_secret” tem validade indeterminada e não sofrem alteração a não ser a pedido do próprio cliente. Porém um item que vêm sendo bastante difundido e incorporado ao grupo de credenciais para utilização das APIs Open Banking é o CERTIFICADO DIGITAL, no CIGAM será sempre utilizado o certificado com extensão *.pfx (contendo chave privada) com CN (common name) formado pela sua Razão Social + CNPJ. A grande maioria dos nossos clientes já possui um certificado com estas características sendo utilizado para a assinatura dos arquivos legais (SPED e EFD) e das NFes (Notas Eletrônicas) de modo que deve ser este o certificado a ser utilizado também no Open Banking.

O common name (CN) é obtido dentro da aba detalhes no item “Subject/Requerente” do certificado digital e o dado utilizado pelo CIGAM nos parâmetros de credenciais do Open Banking é sempre o que está após o texto “CN = “, ou seja, apenas a razão social + CNPJ conforme a imagem abaixo:

IMPORTANTE: O cliente deve estar atento ao período de expiração (data de validade) do certificado instalado e compartilhado (chave pública) com a instituição financeira. Um certificado vencido irá implicar diretamente na comunicação com as APIs até que seja realizada a substituição por um certificado válido. O processo de substituição dos certificados irá variar conforme o banco e pode ser revisado neste manual no item correspondente a cada instituição. O CIGAM também possui a função de criar alertas a partir da versão 221107 que irá alertar o usuário indicado no assistente open banking ou a qualquer usuário que utilizar as rotinas open banking durante o período de 30 dias que anteceder o vencimento do certificado.

Instruções para troca/renovação do certificado digital

As instruções para renovação do certificado digital utilizado nas credenciais dos bancos membros do projeto Open Banking variam de uma instituição para a outra para maiores instruções de como proceder, acesse o manual Open Banking de cada banco. Lembre-se de que sempre é possível contatar o seu gerente de Cash (gerente de contas do banco) para maiores informações e caso tenha dificuldade em realizar o processo, a CIGAM dispõe da Certidoc para prestar este auxílio.

Configurando o Open Banking (informações gerais)

Apesar de cada banco possuir o seu jeito de ser parametrizado, o processo de configuração do Open Banking CIGAM se dá através de apenas dois cadastros, sendo: cadastro de configuração de Bancos, onde todas as informações de credenciais e gerais daquela instituição serão concentradas; e o cadastro de portador, onde serão apontadas as informações referentes a cada uma das contas correntes de cada instituição.

IMPORTANTE: Recomendamos que antes de realizar a parametrização de bancos para o open banking CIGAM você revise todos os portadores que serão utilizados no processo, eles precisam existir e estarem prontos para serem utilizados.

Configuração do portador

O cadastro do Portador, como no processo CNAB tem o objetivo de apontar os dados de cobrança/pagamento para uma Conta Corrente. De forma geral, todos os dados já informados funcionam da mesma maneira no Open Banking.

Dados como carteira e variação permanecem no mesmo formato uma vez que estas são informações de domínio do banco. Outro ponto de alerta é que para o Open Banking a opção “Processar retornos pelo número do boleto” deve estar marcada. (a rotina já realiza esta marcação, mas é importante verificar em caso de dúvidas).

Além disso, deve ser observado o campo Espécie do cadastro de Portadores, onde deverá ter o valor informado de acordo com as opções disponíveis listadas na Cigam Wiki no tópico de Open Banking de cada banco na seção Particularidades do cadastro de Portador ou através da documentação técnica atualizada fornecida por cada instituição bancária.

Caso tenha sido realizada movimentação com esta opção desmarcada, não será possível realizar baixas, pois o sistema não consegue localizar títulos devido a não haver Nosso Número gravado nas tabelas envolvidas.

Para solucionar essa questão será necessário:

• Identificar o Nosso Número do registro a ser baixado (Lançamento Financeiro);
• Gravar o Nosso Número nas seguintes tabelas:
  • GFBOLETOS: campo a ser atualizado NOSSO_NRO com a informação do Nosso Número.
  • GFLAUXIL: campo a ser atualizado CODIGO_BARRAS com a informação do Nosso Número.

Outro ponto importante a considerar é o campo “auditoria” do portador, no open banking é mandatório que ele esteja configurado como “Detalhada” para que o log de auditoria seja registrado.

Além disso, a configuração 348 - Sincronismo lançamento precisa estar diferente de “Nenhum”.

IMPORTANTE: Tanto no Banco do Brasil quanto nos demais bancos parametrizados no Open Banking, sugerimos a remoção dos ZEROS à esquerda nos campos de identificação do Portador (Agência, Conta, Convênio e Cedente), embora haja tratamentos no CIGAM, em alguns casos esse é o motivo de erros de comunicação, principalmente na rotina de retorno do Open Banking. Nestes pontos é comum acontecer erro de comunicação, falha de assinatura e derivados.

IMPORTANTE 2: o CIGAM atualmente não utiliza comandos de remessa no Open Banking.

Configuração de bancos

No programa configuração de bancos, existe um tooltip que aponta quais os bancos estão disponíveis na sua versão do CIGAM:

É no programa de configuração de bancos, dentro do botão “Open Banking” que serão informados os dados de credenciais, ambientes e serviços que serão utilizados via API para aquela instituição.

No primeiro acesso ao botão open banking, será chamado o assistente de configurações onde o usuário será acompanhado passo a passo no preenchimento das informações necessárias.

Tela de parâmetros Open Banking

Caso você já possua uma parametrização open banking para o banco que você está entrando, a tela de parâmetros será aberta, aqui será possível visualizar os dados atuais parametrizados para o banco. Abaixo seguem as informações gerais de cada área da tela de parâmetros Open banking.

Botão “Credenciais”

A tela de credenciais apresentada poderá ter entre uma e duas abas. Conforme o banco, poderá existir uma aba para cada ambiente entre homologação e produção com credenciais distintas. Mas também existem bancos apenas com ambiente de produção, sem possibilidade de testes em ambiente de homologação; e ainda, aqueles que utilizam as mesmas credenciais para ambos, homologação e produção tendo o apontamento do ambiente como um combo em tela.

Aqui são visualizadas todas as informações relacionadas às credenciais open banking do banco que se está pesquisando. As informações contidas aqui variam de acordo com a instituição e normalmente contém as credenciais (Client_secret e Client_ID), certificado digital (quando aplicável), versão da API que está sendo utilizada e dados de escopo (que são os serviços atendidos por aquelas credenciais).

As informações mais sensíveis estão protegidas por criptografia (representada pelo cadeado azul à direita) e não possuem nenhuma possibilidade de visualização. A partir do momento em que as informações são inseridas, o CIGAM as criptografa tanto em ambiente runtime quanto no banco de dados. A única forma de validar se as credenciais estão iguais às que você possui fora do CIGAM é através do botão , onde você pode reinseri-las e clicar em “validar”, caso estejam de acordo com os dados previamente gravados, será emitida uma mensagem confirmando.

Caso você queira utilizar um novo dado, basta inseri-lo e clicar em “confirmar”, o CIGAM irá checar novamente se é isso que você deseja fazer e substituir o dado antigo pelo novo.

Ainda é possível remover uma credencial previamente informada através do botão “Excluir”:

Usuário de Alerta (alerta de vencimento de certificado digital)

Algumas instituições utilizam certificados digitais na composição e validação das credenciais das suas APIs open banking. Estes certificados por sua vez são vinculados às credenciais, desta forma, quando do seu vencimento, a sua substituição precisa ser realizada tanto no sistema interno do cliente quanto na instituição financeira. Ao utilizar o campo “usuário para alerta”, o CIGAM irá gerar uma mensagem para o usuário informado para alertá-lo a partir de 30 dias faltantes para o seu vencimento.

OBS: caso nenhum usuário seja informado no momento da parametrização, será criado um alerta para qualquer usuário que utilizar uma funcionalidade open banking no período que anteceder 30 dias do vencimento do certificado.

Botão “Endereços”

Neste botão estão localizados os endereços de comunicação com as APIs bancárias do CIGAM para cada banco. Elas são geridas pela equipe de desenvolvimento CIGAM e não possuem possibilidade de alteração pelo usuário comum.

Abas Cobrança e Pagamento

Atualmente possuímos as abas Cobrança e Pagamento para configuração dos portadores destas APIs em separado, porém ainda não possuímos a função pagamento, desta forma ela ainda não está em uso e todas as informações contidas nesta sessão são relativas ao serviço de Cobrança. Inclusive a aba Pagamento foi removida a partir da versão 221107 e será novamente adicionada quando a funcionalidade for desenvolvida.

Grupo Convênios e Portadores

O grupo “convênios” pode ter N registros conforme o cliente os possuir, é comum que haja um convenio de cobrança e um convenio de pagamento em um cliente, porém pode ocorrer de haver mais de um convenio para um mesmo serviço de cobrança, por exemplo. O conteúdo do convenio é determinado durante a parametrização (no assistente do open banking) onde o usuário pode escolher apontar um convenio (localizado pelo CIGAM dentro do universo de portadores do banco que se está configurando), ou “pular” esta etapa. Se selecionado, será criada uma linha com aquele convenio selecionado, caso pulado, será criada uma linha com a informação “Geral”.

Neste exemplo, foi localizado o convenio 946278214 dentre os portadores cadastrados para o banco SICREDI (746). Caso o usuário clique em “avançar”, os parâmetros Open Banking serão criados em uma linha com este convenio, caso seja selecionado o botão “pular”, a parametrização será criada como “Geral”.

Sempre que o Banco não especificar um convênio, sugerimos que esta etapa seja pulada para que as credenciais sejam criadas como “Geral”.

O grupo “Portadores” está amarrado ao grupo “Convênios”, ou seja, pode existir mais de uma linha de portadores para um mesmo convênio, essa situação é gerada quando o cliente possui mais de uma conta corrente que realiza cobranças.

No campo “Portador” está indicado o portador de registro a ser utilizado no registro dos boletos deste convenio, já o campo “Portador de Retorno” será trazido como sugestão de portador de liquidação na rotina de retorno open banking para os bancos que possuírem este serviço.

Aqui também existem alguns parâmetros relacionados ao comportamento do CIGAM como: “Direto” para que o registro seja feito diretamente na impressão do boleto; e “PIX” que irá indicar que os títulos registrados devem também registrar uma operação PIX e imprimi-la no boleto (atualmente disponível apenas no Banco do Brasil, Itaú e SICOOB). Já o campo “U.N. Ced” funciona como Empresa cedente na API de cobrança do Itaú. Maiores detalhes podem ser encontrados no manual Open Banking de cada banco.

Botão “Validar”

O botão validar permite consistir as credenciais atualmente informadas no convenio em que se está posicionado:

Esta consulta, além de apresentar o resultado da tentativa de conexão em cada ambiente e nos serviços disponíveis para cada banco, também retorna o seu escopo de serviços das credenciais informadas. As informações apresentadas variam por banco.

Os retornos possíveis serão:

• Conexão realizada com sucesso: As credenciais informadas conseguiram conectar no ambiente e serviços para os quais eles foram informados.

• Credenciais não fornecidas: O CIGAM não realizou o teste de conexão para esta API/Ambiente pois não foram informados dados de credencial.

• Erro de Conexão: Existe erro nas credenciais informadas. Confirme se estas credenciais são compatíveis com o escopo (API) ou ambiente (Homologação/Produção) que deseja configurar.

Botão Resposta API

Já o botão “Resposta API” apresenta especificamente a consulta feita pelo CIGAM, este dado é importante para avaliações dos setores de suporte e desenvolvimento da CIGAM.

Como excluir uma parametrização Open Banking

Por fim, cada grupo “Convenio” possui um conjunto de credenciais para si, ou seja, cada linha de convênio parametrizada terá credenciais específicas, desta forma, caso seja desejo EXCLUIR uma parametrização open banking, basta teclar F3 sobre o convênio desejado, com isso serão excluídos todos os registros de credenciais e portador vinculados a ele.

Como criar uma parametrização Open banking adicional para um mesmo Banco

É comum um mesmo banco possuir credenciais diferentes para mais de uma conta, neste caso, haverá mais de uma linha de convenio (A e B) ou até mesmo Geral + convenio específico. Neste caso, após realizar a primeira parametrização através do assistente, você poderá teclar “Ctrl+I” para invocar novamente o assistente e realizar a nova parametrização de dentro da tela “Parâmetros Open Banking”. Abaixo um exemplo:

A primeira linha “Geral” valerá para qualquer convênio, menos para os portadores do convênio “1285184” que usarão suas credenciais específicas.

Como adicionar um novo portador para uma mesma credencial

Caso você precise incluir um novo portador, seja uma nova conta corrente ou uma nova carteira que compartilhe credenciais de uma parametrização de open banking que já exista. Basta em modo modificar na linha de convênio existente e, no bloco “Portadores” criar uma linha nova indicando os portadores adicionais. Não é necessário invocar o assistente.

Assistente de configuração Open Banking

Como mencionado anteriormente, o assistente de parametrização do Open Banking será disparado sempre que se clicar no botão “Open Banking” do cadastro de configuração de bancos que não possuírem parametrização prévia. Para os bancos com alguma parametrização já criada, ele é chamado através do comando criar (Ctrl+I).

NOTA AOS SETORES DE ATENDIMENTO E IMPLEMENTAÇÃO CIGAM: Conforme mencionado no item Obtenção de credenciais deste manual, independentemente do banco que você estiver configurando, antes de iniciar o processo de implementação, é imprescindível ter os dados de credenciais, certificados digitais, scopes etc em mãos, a primeira página do assistente open banking irá indicar as informações necessárias. Caso esteja em dúvida, consulte a sessão correspondente à obtenção de credenciais do banco que você está querendo configurar. Recomendamos que o trabalho de implementação/atendimento só seja iniciado após a confirmação da existência de tais dados uma vez que não está dentro das nossas possibilidades obter tais informações.

Funcionalidades Open Banking

Neste bloco iremos apresentar todos os processos existentes no Open Banking CIGAM. É importante destacar que o Open Banking CIGAM está disponível apenas na versão 11 e a partir das versões 201103.RC.

Registro de cobrança

O registro de cobrança é a funcionalidade principal das APIs bancárias atuais, praticamente todas as instituições iniciam a sua jornada na liberação de APIs através dela. O escopo de funcionalidades varia desde APIs que apenas registram o título até aquelas que registram/alteram/capturam o retorno do título.

Se formos traçar um paralelo com o CNAB, o método de registro da API de Cobrança realiza todos os movimentos que um CNAB de cobrança realiza, ou seja, é o método utilizado para registrar um título e obter o resultado “ENTRADA CONFIRMADA”. Uma vez registrados, ainda temos a função “N comandos” do CNAB, que era utilizada para interagir com os títulos já registrados, em algumas APIs já é possível realizar alterações de vencimento, valor de juros e multa, baixa de títulos etc. Também é comum apenas a API de registro ser liberada sem o método de retorno como é atualmente no SICREDI, nestes casos, o CNAB ainda é utilizado para realizar a consulta e liquidação dos títulos.

Visão Geral

Para realizar o registro de um título, primeiro você precisa ter o seu banco parametrizado com o uso das credenciais conforme descrito no item Obtenção de credenciais deste manual. A partir deste momento você estará apto a registrar títulos nesta instituição.

Sempre que um lançamento for criado utilizando um portador parametrizado para o Open Banking CIGAM, ele apresentará a legenda “Situação Open Banking” no grupo “Dados Bancários”, conforme apresentado na imagem abaixo:

Status Open Banking para o método de cobrança

• Não Registrado: título recém-criado e não enviado para a instituição financeira.

• Registrado: título registrado na instituição financeira via Open Banking.

• Erro: representa um título que teve uma tentativa de registro, porém recebeu retorno com inconsistência da API. Maiores informações na sessão de tratamento de erros.

• Alteração Pendente: título com alteração realizada no CIGAM, mas ainda não registrada no Banco.

• Liquidado: título liquidado via API de retorno.

• Baixado: registrado via API de cobrança e baixado através do comando de baixa da API.

Menu lateral Open Banking

Nos lançamentos pertencentes ao escopo da API de cobrança, está habilitado um novo menu de mesmo nome, abaixo segue um descritivo básico de cada uma das opções:

• Registrar: É o botão responsável por registrar um boleto na instituição financeira. Existem outras formas de realizar o registro, esta é a mais básica, as demais serão descritas mais a frente neste documento. Regras para habilitar o botão:

• Possuir portador de Open Banking;
• Tipo do lançamento igual a 'Receber';
• Boleto impresso;
• Número no Banco preenchido;
• Lançamento diferente de Previsão;
• Tela em modo diferente de 'Criar';
• Boleto Impresso marcado;
• Status Open Banking igual a 'Não Enviado'.

• Reenviar: Habilitado somente para lançamentos com a situação open banking igual a “Erro”, serve para realizar uma nova tentativa de registro em um título que esteja divergente.

• Baixar: Habilitado somente para lançamentos com a situação open banking igual a “Registrado”, serve para enviar o comando de baixa do título, após a sua execução, é possível realizar um novo registro. Maiores detalhes na sessão que descreve este processo.

• Registrar alteração: Habilitado apenas em títulos com o status “alteração pendente”, serve para registrar alterações realizadas em títulos previamente registrados. O tipo de alteração possível depende do escopo da API de cada banco.

• Histórico: Local onde são registradas todas as interações e tentativas de interação do ERP CIGAM com o Banco. A cada ação de comunicação com a API bancária para aquele lançamento, o CIGAM irá criar uma linha de histórico com data, hora e dados de usuário que realizou a ação, o log é incrementado da ação mais nova para a mais antiga.

Abaixo serão descritos os campos “Ação” e “Status Open Banking”, eles representam respectivamente a comunicação CIGAM vs o retorno do Banco instituição financeira.

Ação (CIGAM)	Status Open Banking (banco ou instituição)
Registrar: comunicação do CIGAM no momento da tentativa de registro do título. Em um paralelo com o CNAB, é a ação que representa o upload de um arquivo de remessa.	Registrado: resultado positivo para uma tentativa da ação CIGAM “Registrar”. ERRO: resultado negativo para a ação “Registrar”.
Consultar: comunicação do CIGAM para obter informações daquele título, a rotina de retorno Open Banking sempre irá gerar um registro deste tipo. Dependendo dos filtros da rotina de retorno, a consulta pode resultar em uma liquidação, conforme abaixo. No modelo CNAB, esta seria a representação da importação de um arquivo de retorno.	Consulta: resultado positivo para uma tentativa da ação CIGAM “Consultar”.
Alterar: representa a ação de interação com o título já registrado, as possibilidades de alteração dependem do escopo da API da instituição com que se estiver trabalhando, as alterações mais comuns são de vencimento, juros e multa. Consulte os descritivos de cada banco para verificar as alterações possíveis.	Alterado: resultado positivo para uma tentativa da ação CIGAM “Alterar”. ERRO: resultado negativo para a ação “Alterar”.
Liquidar: Caso a consulta realizada retorne que o título está liquidado e o filtro da rotina de retorno esteja apontando para “Liquidar”, será criada uma linha com esta ação, liquidando o título.	Liquidado: resultado positivo para uma tentativa da ação CIGAM “Liquidar”. ERRO: resultado negativo para a ação “Alterar”.
Baixar: Ação utilizada para registrar a solicitação de baixa de um título.	Baixado: resultado positivo para uma tentativa da ação CIGAM “Baixar”. ERRO: resultado negativo para a ação “Baixar”.

Erro: resultado negativo para qualquer uma das ações CIGAM. Este status Open Banking será apresentado sempre que houver algum problema na ação que se deseja registrar. A solução para cada caso irá variar conforme a situação. O CIGAM possui um cadastro de sugestões para a solução dos erros já mapeados (conforme imagem abaixo) que podem ser utilizadas como guia para a sua resolução.

Para uma nova tentativa após ajuste de uma situação de erro, existem duas possibilidades:

1. Clicar no botão “Reenviar” no grupo “Open Banking” do menu lateral do lançamento financeiro
2. Executar a rotina de remessa open banking utilizando um filtro que contemple o lançamento em questão. Caso a situação seja sanada, o registro acontecerá normalmente.

Maiores informações sobre o processo de mensagens de APIs financeiras podem ser encontradas na sessão específica deste manual no final desta sessão.

Altera Situação: Este campo do tipo “Checkbox” é marcado automaticamente pelo CIGAM sempre que o retorno da API open banking refletir em uma ação que altere o lançamento financeiro do CIGAM, seja uma liquidação ou uma baixa.

Comando: Este campo é uma identificação da API e é representado pelos códigos:

• 00 – Não Registrado

• 01 – Registrado

• 02 – Alterado

• 03 – Baixado

• 04 – Liquidado

• 06 – Consulta

• 07 – Erro

IMPORTANTE: Não confundir este campo comando com os “Comandos de remessa”, do lançamento financeiro e do cadastro de portador, estes serão explicados mais a frente e permanecem conforme as suas funções existentes.

Sequência: representa a sequência deste registro da tabela de log de histórico open banking.

U.N.: representa a Unidade de Negócio utilizada para a criação deste registro.

Usuário: usuário logado no sistema e responsável pela execução da ação.

Dados API: Todas as ações/status open banking possuirão um arquivo de remessa e retorno referentes à comunicação gerada entre CIGAM e Banco, estes arquivos contém os dados de todas as informações trocadas em um formato chamado “JSON”. Traçando um paralelo com o CNAB, este é o substituto do arquivo txt que era enviado e baixado no gerenciador bancário. Os dados de envio do JSON de cada interação estão disponíveis no botão da coluna “Dados API”:

Exemplo de JSON de registro (envio e retorno) de um título no Banco:

Botão “Copiar”

O Botão “Copiar” permite selecionar a totalidade do conteúdo dos arquivos JSON e copiá-los para o clipboard do Windows, desta forma, caso seja necessário enviar este conteúdo para um outro destinatário (suporte/implementação) basta teclar “Ctrl+v” em um editor de texto:

Auditoria: conforme mencionado no item Configuração do portador deste manual, os portadores utilizados no open banking devem possuir a opção “auditoria” selecionada com a opção “detalhado”, isso irá permitir o registro de todas as alterações do título em questão. Isso também permitirá clicar no botão “auditoria” do histórico open banking, o que permitirá identificar todas as informações daquele lançamento, bem como data, hora e usuário que realizou a alteração.

As alterações são registradas da mais atual para a mais antiga.

Pesquisa dinâmica de Lançamentos

A pesquisa dinâmica de lançamentos possui um filtro relativo à situação Open Banking do lançamento:

Mensagens de erro Open Banking

As mensagens open banking possuem um cadastro salvo em gestão financeira>parâmetros>Mensagem de Retorno de APIs financeiras. Este cadastro visa auxiliar o usuário na obtenção de informações acerca da resolução de situações de erro obtidas na comunicação das APIs do módulo financeiro, não somente ao Open Banking, mas também às APIs do PIX.

As mensagens estão distribuídas por banco, código de erro, status de retorno, descrição dada pelo banco, sugestão CIGAM, que é uma dica da equipe CIGAM em como resolver tal problema e por fim uma coluna de sugestão do cliente, que pode ser informada com as próprias interpretações dos usuários para solucionar aqueles casos.

A tabela é periodicamente atualizada pela equipe CIGAM e pode ser atualizada no cliente através do botão . Outra funcionalidade importante é que a tabela de erros do cliente é incrementada conforme as mensagens são recebidas, ou seja, caso o banco retorne uma mensagem que ainda não havia sido recebida ou contida na tabela, ela será inserida automaticamente, o que resulta em uma tabela sempre crescente e sem a possibilidade de apresentar um “erro desconhecido”.

As mensagens da API são apresentadas imediatamente no momento da recepção do erro e podem ser visualizadas novamente sempre que se clicar na palavra “erro” na situação open banking do lançamento ou dentro do botão histórico open banking.

Cadastro de mensagens de erro Open Banking

Qualquer pessoa poderá cadastrar uma mensagem de alerta/erro com texto mais amigável a fim de auxiliar os demais usuários em erros já conhecidos no registro do Open Banking. Para tanto, basta entrar no cadastro de mensagens, localizar a mensagem do banco que deseja inserir a sugestão e informar o texto no campo “Sugestão Cliente”:

Pronto! Na próxima vez que a mensagem de erro aparecer, o usuário logado irá visualizar a dica para a solução da situação.

Registrando títulos

Existem duas formas de realizar o registro de títulos open banking, um é realizado pelo movimento em que se está (lançamento, nota fiscal, contrato etc.), chamado de direto. A outra é pela rotina de remessa específica, chamado de indireto, ambos serão demonstrados abaixo.

IMPORTANTE: para a rotina de registro open banking não há distinção entre bancos, todos seguem o mesmo formato, isso significa que as próximas informações valem para qualquer banco ou instituição que possua API de registro no CIGAM.

Registro do boleto de cobrança nas modalidades Direto ou indireto

A depender da opção “Direto” estar marcada nos parâmetros Open Banking, o CIGAM irá se comportar de formas distintas. Com a opção marcada, o CIGAM irá realizar o registro do título na impressão do boleto. Com esta opção desmarcada, o registro será feito apenas quando da execução da rotina “Remessa de cobranças Open Banking”.

Operação com a opção Registro Direto marcada

Este formato de uso é o mais recorrente em nossos clientes e é o formato de implementação sugerido, onde no momento do envio e confirmação da NFe o boleto já é registrado imediatamente. Esta é a opção ideal para ser usada em conjunto com a opção “PIX”, onde será impresso o QR Code para pagamento PIX.

Um título que que possua a opção “Direto” marcada será registrado nas seguintes situações:

1. No cadastro de lançamento avulso ao clicar em “imprimir boleto”;
2. Na confirmação da NFe/NFSe (caso parametrizada para envio de boleto);
3. Na rotina de impressão de boletos em lote;

Operação com a opção Registro Direto desmarcada

A opção “Registro direto” é utilizada desmarcada apenas em alguns casos específicos, por exemplo, quando o cliente possui um processo de conferência das notas fiscais após a sua geração e onde pode ocorrer alguma alteração de valores ou até mesmo um cancelamento da nota. Ao deixar a opção desmarcada, os boletos não serão registrados imediatamente na confirmação da nota.

Um título que possua a opção “Direto” desmarcada será registrado apenas na execução da rotina “Remessa de Cobrança Open Banking” (executada após a ter ocorrido a impressão do boleto).

Idealmente, neste formato, sugerimos que o boleto não seja parametrizado para envio pela NFe, já que, além de não estar registrado até que o seu registro seja feito pela rotina de “Remessa de cobrança Open Banking”, caso o banco que está sendo utilizado possua a opção de QR Code PIX no boleto, a operação PIX somente é gerada no momento do registro do boleto. Imprimir um boleto sem registro, embora seja possível, irá resultar em um boleto sem QR Code PIX.

QR Code no Boleto

Alguns bancos disponibilizam juntamente com o serviço de registro de cobrança a possibilidade de criar uma Operação PIX de mesmo valor atrelada ao título que se está registrando. Esse registro possibilita mais uma forma de pagamento ao cliente que poderá pagar tanto pelo código de barras do boleto quanto pelo QR Code da operação PIX. Cada banco possui uma forma de lidar com estes registros, seja baixando automaticamente o boleto quando do pagamento do PIX ou cancelando-os. Consulte a área de open banking de cada uma das instituições para entender como cada uma gere estas transações.

No CIGAM a forma de se parametrizar uma operação PIX (QR Code no boleto) é sempre a mesma, deve ser marcada a opção “PIX” ao lado da opção “direto” no assistente de parametrização ou na tela de parâmetros open banking e utilizar um modelo de boleto padrão com QR Code ou adicionar a variável qrcode_pix (<!$MG_qrcode_pix>) ao seu modelo de boleto personalizado.

Chave PIX do QR Code no boleto

A Chave PIX utilizada no boleto varia conforme o Banco, porém atualmente existem duas origens possíveis:

No cadastro do portador de remessa (botão parâmetros PIX):

Ela será enviada no JSON dessa forma:

Ou será utilizada automaticamente a chave PIX da conta vinculada ao convênio do boleto, neste caso não é enviada chave no JSON, apenas a indicação de que há ou não PIX no boleto.

Manuais Referenciados

• Open Banking - Não está imprimindo QR Code no meu boleto

Rotina de Remessa Open Banking (via menu)

O registro de títulos open banking via menu é utilizada principalmente pelos clientes que optarem em não utilizar a opção “Direto” para os seus títulos.

Menu: Gestão Financeira > Rotinas > Operacionais > Open banking > Remessa de cobrança Open Banking

Ao utilizar a rotina de remessa via menu, os filtros a serem utilizados devem ser aqueles que sejam suficientes para localizar a todos os títulos que ainda não tenham sido registrados. Assim como nas remessas CNAB, uma boa ideia de filtro são todos os títulos com data de emissão inicial igual a 00/00/0000 até a data atual.

Condição para um lançamento ser registrado/apresentado na remessa open banking (avulso ou em lote)

Ao executar a rotina, serão registrados todos os títulos a receber com:

1. situação “open banking = Não registrado”;
2. com número no banco;
3. opção “boleto impresso” marcada;
4. opção “remessa enviada” desmarcada;
5. que estiverem contemplados dentro dos filtros informados;
6. Ela também serve para realizar o registro de alterações de títulos com Situação Open Banking = “Alteração Pendente” onde eles também serão enviados para registro da sua alteração.

Ao final, será apresentado o relatório com a situação de cada um dos títulos e seus retornos.

Relatório de remessa bancária

O relatório de remessa bancária será impresso sempre que um registro avulso (direto pela tela de lançamentos) for feito ou como resultado da execução da rotina de Remessa Bancária On Line. As suas variáveis estão contidas no arquivo salvo em:

I:\CIGAM\DOC\Modelos_relatorios\Gestão Financeira\RF00071_remessas.RTF

Este modelo serve tanto para remessa quanto para retorno on line e é apresentado da seguinte forma:

Rotina de Retorno Open Banking

O retorno de cobrança open banking, ao contrário do registro, é específico para cada instituição, eles serão apresentados banco a banco nesta sessão:

O retorno on line pelo Open Banking CIGAM vem para substituir o arquivo CNAB de retorno e é responsável por consultar e atualizar os títulos registrados na instituição bancária. Desta forma, o CIGAM está sempre atualizado com o seu banco. Este bloco do manual estará dividido diretamente por banco, uma vez que cada um possui uma forma de tratamento em seu retorno.

Menu: Gestão Financeira>rotinas>operacionais>open banking>Retorno de cobrança open banking.

A rotina de retorno é única para todos os bancos do escopo open banking e varia os seus parâmetros de filtros (na aba filtros) conforme o banco apontado no portador informado no filtro “portador”, para auxiliar na execução da rotina existe um botão “aqui” no texto “Para mais informações a respeito dos filtros, clique aqui”. Já a aba “parâmetros” segue a mesma regra para todos os bancos e utiliza funções herdadas da rotina de retorno de CNAB de cobrança conforme abaixo:

Tipo de Retorno:

• Listagem: quando selecionado essa opção, ao executar a rotina, apenas listará o status do registro do Boleto Bancário junto ao Banco.

• Retorno: quando selecionado essa opção, ao executar a rotina, o sistema irá executar o retorno dos registros confirmados e já irá realizar a liquidação caso haja registros pagos, sem executar a listagem.

• Ambos: quando selecionado essa opção irá executar tanto a opção de "Listagem" quanto a opção de "Retorno".

Portador para Liquidação: este campo tem como finalidade informar qual será o Portador utilizado para os registros que serão liquidados. Caso não seja informado nenhum Portador neste campo, será utilizado o Portador de Retorno parametrizado para Open Banking.

Portador Carteira de Desconto: este campo é para informar o Portador de Carteira de Desconto, para Contratos Bancários, para os registros que possuem Duplicatas negociadas com o Banco.

Histórico de Liquidação: campo para informar o Histórico que será utilizado para os registros que serão liquidados.

Não contabilizar Juros e Descontos nas liquidações da Carteira Descontada: esta opção tem como finalidade não contabilizar os Juros e Descontos para as liquidações de Carteira Descontada, ou seja, caso possua duplicatas com o Banco negociada e o registro possuir Juros, Desconto, possibilita o usuário não os contabilizar marcando esta opção.

Não gerar lançamentos de tarifa de cobrança: esta opção tem como finalidade quando selecionada não gerar a liquidação do valor da tarifa de cobrança.

Data para Liquidação: quando zerado a Data será habilitado para selecionar as opções. Esta opção tem como finalidade realizar a busca para liquidação de duas formas:

•  Ocorrência: os títulos serão liquidados com a Data de Ocorrência do Título (Data Recebimento do Título - tag "dataRecebimentoTitulo") ao qual foi processado no Banco

• Crédito: os títulos serão liquidados com a Data de Crédito (Data de Crédito Liquidação - tag "dataCreditoLiquidacao") em que foi processado no Banco. Ou seja, se o título foi pago por exemplo na Data 31/08/2020 o banco irá processar esse pagamento e o retorno será creditado na conta no dia 01/09/2020, porém o pagamento foi realizado no dia anterior e creditado no dia posterior.

A Data para Liquidação é trazida por padrão a Data atual como sugestão, sendo possível alterá-la ou quando zerada habilita para buscar automaticamente a Data de Ocorrência ou Crédito.

Gerar acompanhamento das ocorrências bancárias: Esta opção é utilizada para descrever os dados de valores do título advindo do banco no retorno da ação de “liquidar” abertos por Valor, Juros, multa, desconto por tarifa, desconto e outros recebimentos.

Regras de Busca do Sistema para localizar títulos no retorno

O sistema tenta localizar os títulos pelo Número do Lançamento;

Caso os títulos tenham sido gerados pelo CIGAM irá localizar pelo Nosso Número, avaliando então a tabela GFBOLETOS pela coluna NOSSO_NRO;

Caso os títulos tenham sido gerados por outro sistema irá localizar pelo Nosso Número, avaliando então a tabela GFLAUXIL pela coluna CODIGO_BARRAS;

Retorno de cobrança via CNAB (bancos que ainda não possuem método para retorno)

O projeto open banking varia de instituição para instituição, é comum que um banco libere apenas a API de registro no seu projeto open banking. Nestes casos, você pode continuar realizando os retornos via CNAB configurável, nos mesmos moldes já utilizados. Ele é uma forma de consulta válida e que atende os requisitos da funcionalidade, porém fique atendo e em contato com a sua instituição e às atualizações do CIGAM, a qualquer momento o retorno bancário de cobrança poderá ser liberado e você poderá migrar para o Retorno de cobrança On Line.

Alterações de títulos registrados Via Open Banking

As APIs de registro também são responsáveis por realizar alterações nos títulos existentes na instituição. A seguir serão apresentados os serviços de alteração disponíveis no CIGAM de forma geral, todos os bancos possuem o mesmo tratamento para todas as funções apresentadas. Basta avaliar se o banco que você está utilizando possui tal funcionalidade.

Alteração de Juros, Multa e vencimento

Aqui, a maior diferença entre o CNAB e o Open Banking CIGAM é a de que, embora as duas metodologias utilizem o cadastro de comandos para realizar as três alterações mais comuns em títulos (Juros, Multa e Vencimento), o Open Banking irá funcionar mesmo que não haja um comando cadastrado para tanto. Nestes casos, eles serão criados automaticamente.

Regra Sistema para Vencimento, Multa ou Juros

O cadastro do Portador deve possuir Comando de Remessa com as novas opções:

• Tipo de Comando = Alteração de Vencimento (para alteração de Vencimento).
• Tipo de Comando = Alteração de Multa para Multa (para alteração de Multa).
• Tipo de Comando = Alteração de Juros para Juros (para alteração de Juros).

Caso não seja parametrizado neste primeiro momento as opções de Multa, Juros e Vencimento, o sistema cria automaticamente (Somente Juros, Multa e Vencimento).

Ao acessar o Lançamento Financeiro em modo Modificar e alterar o campo Multa, Juros ou vencimento, automaticamente após alteração da Multa, o Sistema irá criar essa parametrização do Comando de Remessa como sugestão (caso não haja um comando do tipo necessário), sendo passível de alteração, no Cadastro do Portador no botão Remessas e depois no botão Comandos.

Comando sugestão para Multa:

• Código Operação = ATM
• Comando = ATM
• Descrição = ALTERAÇÃO DE MULTA PARA OPEN BANKING
• Tipo de Comando = Alteração de Multa

Comando sugestão para Juros:

• Código Operação = ATJ
• Comando = ATJ
• Descrição = ALTERAÇÃO DE JUROS PARA OPEN BANKING
• Tipo de Comando = Alteração de Juros

Comando sugestão para troca de vencimento:

• Código Operação = ATV
• Comando = ATV
• Descrição = ALTERAÇÃO DE VENCIMENTO PARA OPEN BANKING
• Tipo de Comando = Alteração de vencimento

A alteração destes 3 campos é enviada sempre que um título previamente registrado receber alguma alteração. Lembrando que para juros e multa, os campos enviados são sempre em valor, nunca em percentual. Isso auxilia o cálculo de juros/multa ao dia simulado pelo CIGAM em locais como o portal do cliente – área financeira.

Depois de realizar as alterações, elas serão enviadas de forma agrupada para o banco, bastando que seja salva a informação através do comando CTRL+Q ou clicando na opção “Registrar alteração” do menu lateral do grupo open banking do lançamento.

Veja que a situação open banking de um título que ainda não tenha tido a sua alteração registrada no banco fica como “Alteração pendente e o comando de remessa é preenchido. Outro ponto importante é que o comando de remessa para cada um dos tipos de alteração é utilizado conforme a sua existência no botão “comandos” do cadastro de portador. Caso ele não exista previamente, ele é criado de forma automática conforme apresentado na sessão de cadastros de portador deste manual.

Ao confirmar a mensagem acima, a alteração será processada e a situação do título, caso não ocorra nenhum erro, volta a ficar como registrada e tudo é gravado no histórico open banking:

Não escopo dos serviços de alteração

Alguns pontos ainda não estão tratados neste manual, por exemplo, alteração de desconto até o vencimento, endereços, abatimentos etc.

Baixa de títulos

A baixa de títulos serve para retirar o título do registro bancário, ela só está habilitada para um título com a situação “Registrado” e ao final do processo, o título terá todas as informações relativas à sua caracterização prévia (nosso número, número no banco etc) removidas. Isso possibilita realizar o registro do título novamente.

Não escopo do serviço de baixa

Atualmente quando uma nota é cancelada, por exemplo, não é enviado o comando de baixa para o banco, portanto o processo sugerido é que primeiro seja realizado o processo de baixa unitário pela tela do lançamento financeiro e após proceder com o cancelamento.

Sugerimos cautela no uso de rotinas que realizem manutenção de lançamentos em lote como “Pagamentos/Recebimentos” e “Manutenção de Lotes” que realizam a troca de portadores de lançamentos financeiros. O motivo é que caso os portadores de lançamentos registrados via open banking tenham seus dados alterados, a informação do registro no CIGAM irá se perder. Embora haja mensagens de alerta para comunicar o usuário deste risco, ainda é possível realizar a confirmação das alterações.

Proteções no Lançamento

Com o advento do Open Banking, faz-se necessário um maior controle dos lançamentos registrados nos bancos, se um título registrado via API tiver seu portador e/ou vencimento alterados por rotinas do CIGAM, correremos o risco destas alterações não serem refletidas nos bancos.

No contexto atual, onde teremos ainda clientes utilizando serviços mesclados em CNABs para alguns bancos e Open Banking para outros, precisamos ter tratamentos específicos para cada situação. Em algumas delas é utilizado o que já é feito nos CNABs e em outras, foram realizados novos tratamentos visando alertar o usuário em ações executadas no sentido de quebra de integridade entre o banco e o CIGAM, seja nas rotinas em lote ou unitariamente no lançamento financeiro.

Grupo Dados Bancários

A fim de iniciar o processo de proteção dos lançamentos financeiros registrados via Open Banking, os campos que possam descaracterizar um lançamento já registrado não poderão ser alterados, sendo eles:

• Número no Banco: Bloqueado
• Nosso Número: Bloqueado
• Boleto impresso: Bloqueado
• Remessa enviada: Bloqueado
• Código Barras Lido: Removido para lançamentos a receber

Estes bloqueios são válidos apenas para titulos registrados via open banking

Deste modo a única forma de alterar os dados bancários de um lançamento será através da alteração do seu portador. Esta alteração poderá nos levar a duas situações, sendo a primeira aquela em que o novo portador mantém todos os dados do portador atual (ex: troca da carteira simples para a carteira descontada) ou a segunda onde o portador alterado é uma conta/banco diferente, cada caso será apresentado abaixo.

Alteração de Portador

Atualmente os lançamentos registrados por Open Banking trabalham de forma similar ao CNAB, onde caso eles sejam modificados a nível de portador, também perderão seus vínculos com o banco. Porém, como nesta modalidade temos uma integração completa com a instituição, faz mais sentido que as alterações “finalizem” o processo de forma mais organizada, ou seja, se um lançamento for perder o seu vínculo com o banco por conta de uma troca de portador ou cancelamento de nota, por exemplo, que isso seja realizado junto ao banco também.

Validação dos dados de portador

Quando é realizado a troca do primeiro portador para o segundo portador, é avaliado se no segundo todos os campos verificados estão batendo com os do primeiro, sendo eles Banco, Conta, Agência e Convênio.

Se esses campos corresponderem o lançamento terá o seu portador alterado. Para não perder o vínculo com o banco será mantido o histórico Open Banking no antigo portador.

Caso contrário, se os portadores possuírem os campos validados distintos será exibida a seguinte mensagem:

Clicando em "Detalhes" serão exibidos os dados validados dos dois portadores:

Para realizar a troca será necessário definir se o título será baixado ou não, se Baixar Título o título será baixado no banco e estará pronto para atender ao novo portador, caso Continuar sem Baixar o vínculo anterior é quebrado e os dados do lançamento serão sobrescrito com o novo portador.

Documentos Relacionados

• Open Banking para Banco do Brasil
• Open Banking para Banco Itaú
• Open Banking para Banco SICOOB
• Open Banking para Banco Bradesco
• Open Banking para Banco Sicredi
• FAQs - Open Banking