GF - Como Fazer - Open Banking

Introdução ao Open Banking

O Open Banking CIGAM é o projeto que visa implementar as APIs bancárias (interfaces online de comunicação) no 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!

Lista de APIs

Atualmente, cada banco possui um escopo próprio de soluções via API. Nas tabelas abaixo são descritos os serviços disponíveis por instituição bancária e a versão CIGAM em que eles foram liberados.

Um tópico universal dentre todos eles é o de que para utilizar um serviço, são necessárias credenciais e, em alguns casos, até certificados digitais. Na seção Obtenção das Credenciais serão apresentadas dicas de como proceder com a obtenção de credenciais em cada instituição.

Migrando um cliente do CNAB para a API Open Banking

A migração de um cliente que hoje está utilizando CNAB para os seus movimentos ocorre 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. 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 ambientes uma vez que existem restrições de CPF/CNPJ exclusivos para teste, situação que o cliente não possuirá.

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

Para clientes novos, que não tem como registrar títulos oficiais no CIGAM, recomendamos avaliar a seção “testes em homologação” dentro de cada seção do item Assistente de configuração Open Banking deste manual para obter informações de como utilizar o ambiente de homologação de cada banco.

Obtenção das Credenciais

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.

Gestão dos certificados digitais: Ainda no tópico referente aos dados de credenciais, normalmente 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 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.

Abaixo serão disponibilizados os processos de obtenção de credenciais e fluxo de obtenção de certificados de acordo com cada banco. Os fluxos descritos podem sofrer alterações por parte dos bancos, portanto sempre leve em consideração consultar a sua instituição:

• Banco do Brasil
• Itaú
• SICOOB
• Bradesco
• SICREDI

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. O único 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).

Caso tenha sido realizado movimentações com esta opção desmarcada, não será possível realizar a Baixa, pois sistema não consegue localizar devido não possuir o Nosso Número gravado nas tabelas envolvidas.

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

1.Identificar o Nosso Número do registro a ser baixado (Lançamento Financeiro);
2.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 "GE - SI - 348 (Sincronismo lançamento)" precisa estar diferente de "Nenhum".

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. Consulte a seção Assistente de configuração Open Banking para um descritivo completo de cada um dos assistentes.

Telas 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. Caso você ainda não tenha realizado nenhuma parametrização open banking, sugerimos que você avalie primeiro o tópico Assistente de configuração Open Banking para as informações do assistente open banking específico para o banco que quiser configurar. 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. A especificação de cada banco será descrita no item Assistente de configuração Open Banking deste manual.

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.

- 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.

• 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. Caso 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 OB 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). Já o campo “U.N. Ced” funciona como Empresa cedente na API de cobrança do Itaú. Maiores detalhes podem ser encontrados na seção Funcionalidades Open Banking específica de cada banco.

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 convenio, 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 (inserção de credenciais por banco)

Como mencionado no item Configurando o Open Banking, 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 em Obtenção das Credenciais, 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.

Abaixo serão disponibilizados os processos de configuração de acordo com cada banco:

• Configurando Banco do Brasil
• Configurando Itaú
• Configurando SICOOB
• Configurando Bradesco
• Configurando SICREDI

Alerta de Certificado Digital a vencer

A partir do preenchimento do parâmetro “Status do Certificado” na configuração dos bancos Itaú, Bradesco e SICOOB será criado um alerta para o usuário de modo a alertá-lo quando o certificado usado vencerá e deverá ser trocado.

A rotina para criar o alerta de usuário poderá ocorrer de duas formas:

1. No momento da parametrização de Open Banking após o usuário confirmar os dados informados e o mesmo ter adicionado um usuário para alerta no campo "Usuário para Alerta" será criado o alerta com data de aviso para data e hora do vencimento do certificado menos 1 mês. Exemplo: Certificado com vencimento em 16/03/2023 12:07:11, será criado um alerta para a data 16/02/2023 12:07:11. Caso na parametrização não seja informado um usuário para alerta, o mesmo não será criado neste momento, apenas quando o vencimento do certificado estiver a partir dos 30 dias.

2. O alerta também será criado caso a parametrização de Open Banking tenha ocorrido antes desta evolução ou se o aviso foi exibido em tela e cancelado/concluído pelo usuário. Toda vez que uma rotina Open Baking for executada, o programa verificará o vencimento do certificado e criará o alerta com a data atual e dez minutos a mais da hora atual.

Exemplos:
Certificado com vencimento em 15/02/2023 e data atual 25/01/2023 12:00:00, será criado um alerta com data para 25/01/2023 12:10:00.
Caso Vencimento do certificado seja em 28/02/2023 e data atual 25/01/2023 12:00:00, o alerta não será criado pois o vencimento não está dentro dos 30 dias de contagem.

Observações

• A rotina verifica automaticamente quando o certificado foi atualizado e interrompe a criação de alerta, sem a necessidade de o usuário parametrizar novamente os parâmetros Open Banking. Portanto os alertas só irão cessar quando o certificado for atualizado ou quando o usuário adiar o alerta para uma data menor que o vencimento do certificado.
• Em situações em que o usuário adiar o alerta para uma próxima data que seja menor do que o vencimento do certificado o alerta continuará valido até que o certificado seja renovado. Caso o usuário cancele ou conclua o alerta e não atualize o certificado o alerta será criado novamente quando o usuário acessar alguma rotina de Open Banking
• Se não for informado um usuário para alerta nas parametrizações Open Banking, o alerta será criado para cada usuário que acessar a rotinas relacionadas ao serviço, caso contrário será criado sempre apenas para o usuário informado.

Funcionalidades Open Banking

Neste bloco iremos apresentar todos os processos existentes no Open Banking CIGAM. Sempre teremos a apresentação macro da funcionalidade e depois uma visão específica das particularidades de cada banco. É importante destacar que o Open Banking CIGAM está disponível apenas na versão 11 e a partir das versões 201103.RC, também será necessário a utilização da versão Magic 3.3 ou superior

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 BRADESCO, 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 Assistente de configuração Open Banking 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:

Os status Open Banking para o método de cobrança, são os seguintes:

• 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: Habilitado somente para lançamentos que já possuem boleto impresso, número no banco preenchidos e com situação open banking igual a “Não registrado”. É 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.
• 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.

750px500px

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 ou
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 item Mensagens de erro Open Banking.

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:

Para uma explicação detalhada de cada um dos campos apresentados no JSON de cada banco, acesse a área Registro via rotina de remessa open banking deste mesmo manual.

Auditoria: conforme mencionado no item Configurando o Open Banking, 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.

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 Arquivo:Botao Refresh.png. 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.

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 direto e 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.

Consulte na sessão específica de cada banco o tempo médio para o título estar passível de liquidação após o seu registro e qual banco suporta a opção de QR Code PIX.

Registro via rotina de remessa open banking

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

Particularidades do Registro

• Banco do Brasil: O registro do Banco do Brasil é, de maneira geral realizado como todos os outros bancos, abaixo seguem algumas explicações exclusivas.
• Itaú
• SICOOB
• Bradesco
• SICREDI

Layout

• Banco do Brasil
• Itaú
• SICOOB
• Bradesco
• SICREDI

Particularidades do Cadastro do Portador

• Banco do Brasil
• Itaú
• SICOOB
• Bradesco
• SICREDI

Impressão de QR Code no boleto

• Banco do Brasil
• Itaú
• SICOOB
• Bradesco
• SICREDI

Erros comuns

• Banco do Brasil
• Itaú
• SICOOB
• Bradesco
• SICREDI

Condições avaliadas para registrar um Lançamento

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;

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

Retorno de cobrança on line

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) 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) 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 os títulos:

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 Online Banco do Brasil

O Banco do Brasil separa a execução da rotina de retorno em dois blocos, conforme a explicação contida no seu botão informativo:

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.

• SICOOB

Alterações de títulos registrados

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 OB 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:

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 e Juros o sistema cria automaticamente (Somente Juros e Multa).

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 tenha 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 deste serviç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.