GF - Como Fazer - Open Banking para Banco Itaú

Objetivo

Este manual tem por objetivo instruir alguém que já tenha lido o manual geral do Open Banking CIGAM a realizar todo o processo de parametrização e início do uso das APIs bancárias do Itaú.

Aqui você será orientado desde a busca e obtenção das credenciais, assistente e parametrizações específicas do Itaú para o Open Banking. Para dúvidas gerais referentes a funcionalidades gerais do Open Banking consulte o Manual Open Banking - Geral.

APIs disponíveis e serviços atendidos pelo CIGAM

Funcionalidade	Versão
Registro de Cobrança Simples e vinculada	220404 BETA
Alteração de Vencimento	220404 BETA
Alteração de Juros e multa	220404 BETA
Baixa de título	220404 BETA
Protesto e Negativação	220404 BETA
Retorno de Cobrança	221107.a BETA
Demais alterações (endereço, desconto por antecipação, abatimentos, etc)	Não tratados no CIGAM
QR CODE no Boleto (Bolecode)	221107.a BETA
API de PIX avulso (QR Code dinâmico ECF Lojas)	231002 BETA

Open Banking Itaú

Obtenção de credenciais - Itaú (versão atual V2 + BOLECODE)

As credenciais do Itaú são obtidas através de um processo realizado em conjunto com a equipe de implantação e acessos ao Portal Developers desta instituição e seguir os passos do processo de credenciamento e geração do certificado digital.

IMPORTANTE: O Itaú utiliza credenciais e certificados digitais específicos para a API de cobrança, chamada CASH MANAGEMENT (registro sem QR Code e retorno de cobrança) e para a API BOLECODE (registro de cobrança com QR Code). Desta forma, um cliente que quiser possuir registro com QR Code e retorno via API, precisará das credenciais e certificados para as duas APIs. Tratam-se de certificados próprios, não sendo possível a utilização dos certificados da NFe.

O processo de obtenção de credenciais é totalmente de responsabilidade do cliente e sua equipe de TI juntamente com o Itaú. Para aqueles que desejarem auxílio, dispomos de um parceiro homologado na empresa Certidoc onde cabe ao cliente fazer este contato.

O Itaú a partir de setembro de 2024 possibilita que as credenciais geradas sejam 'unificadas', no sentido de que o scope de BOLECODE passa a poder ser adicionado a credencial de CASH_MANAGEMENT. Porém, para uso dessa modalidade de 'credenciais unificadas', é necessário que identifique a versão do Cigam para saber se a versão do Cigam em uso é a 241007 e posteriores ou 240506 patch 'c' ou posteriores, que são as versões que suportam esta modalidade. Caso sua versão de Cigam seja anterior as versões mencionadas, ao solicitar para o Itaú que sejam criadas as suas credenciais para uso das API's de Open Banking, solicite que sejam geradas credenciais separadas, uma para CASH_MANAGEMENT e outra para BOLECODE, ou então, verifique sobre a atualização do seu Cigam.

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

As instruções para renovação do certificado digital utilizado nas credenciais do Itaú estão disponíveis no Portal Developers e são compostas por ações semelhantes às do primeiro credenciamento. Contate o seu gerente de Cash (Itaú) para maiores informações e caso tenha dificuldade em realizar o processo, a CIGAM dispõe da Certidoc para prestar este auxílo.

Para e troca do certificado no CIGAM (seja Bolecode ou Cash) em cenários onde o novo certificado manter o CN e alterar somente sua validade basta remover o antigo e instalar o atual. Para validar se a configuração Open Banking está utilizando o novo certificado entre nas Credenciais dos Parâmetros Open Banking e verifique se o campo "Status do Certificado" foi atualizado:

Caso o certificado tenha o CN alterado será necessário a atualização no banco e no CIGAM informar o novo Client Id/Client Id BOLECODE. Para validar a atualização verifique se o campo "Status do Certificado" foi atualizado.

Para mais informações de instalação do certificado acesse a FAQ sobre instalação e revisão do certificado digital.

Assistente Open Banking - Itaú

Conforme explicado no tópico anterior, a tela de boas-vindas do assistente do Itaú especifica os dados referentes às credenciais para as APIs do Itaú:

Passo 1: Aqui serão solicitados todos os dados relativos a credenciais e serão explicados um a um. O Itaú a partir a versão 2 (atual) da sua API, deixou de disponibilizar ambientes de teste, desta forma, preencha apenas os dados da guia “Produção”, caso você tenha a necessidade de cadastrar alguns títulos de teste, utilize o campo “etapa processo do boleto = validação” conforme as instruções abaixo.

a. API Cobrança: 02 – API cash_management ou 03 – BOLECODE. Conforme explicado acima, utilize a opção 02 para registro e retorno de cobrança sem QR Code no boleto, para esta opção são necessárias apenas as informações com sufixo “CASH”. Já para utilizar a opção 03 que possui registro de cobrança com QR Code, é necessário utilizar as credenciais com sufixo “BOLECODE” e também as de sufixo “CASH” pois a API de retorno permanece nesta segunda API.
b. Client_id Remessa/Retorno Cobrança CASH: id da API cash Management para registro sem QR Code e retorno de cobrança;
c. Client_secret Remessa/Retorno Cobrança CASH: secret da API cash Management para registro sem QR Code e retorno de cobrança;
d. Chave Itaú: campo desabilitado, era utilizado na V1 já descontinuada;
e. Etapa Processo do Boleto: Aqui é onde existe a possibilidade de realizar registros de testes no Itaú, a opção “etapa processo” permite realizar registros em ambiente não produtivo conforme abaixo:

01 – Efetivação: este é o formato oficial onde os títulos serão registrados em ambiente de produção.
02 – Validação: mantendo este parâmetro, os títulos serão enviados para um ambiente de testes restritos (apenas registro, sem possibilidade de alteração uma vez que o título não fica registrado, apenas é feita uma validação inicial).

f. Status Certificado Cobrança CASH: campo preenchido automaticamente pelo CIGAM ao localizar um certificado nomeado com o seu CN=Client_id da API de CASH. Exemplo:

Client_ID Remessa/Retorno CASH: 1234567891011121314
Nome do Certificado: “1234567891011121314”

g. Identificador (CNPJ/CPF): campo desabilitado, era utilizado na V1 já descontinuada;
h. Versão da API: campo preenchido automaticamente pelo CIGAM;
i. Client_id BOLECODE: id da API BOLECODE para registro de cobrança com QR Code;
j. Client_Secret BOLECODE: secret da API BOLECODE para registro de cobrança com QR Code;
k. Status Certificado BOLECODE: campo preenchido automaticamente pelo CIGAM ao localizar um certificado nomeado com o seu CN=Client_id da API BOLECODE. Exemplo:

Client_ID BOLECODE: 1234567891011121314
Nome do Certificado: “1234567891011121314”

l. x-apigw-api-id: campo desabilitado, era utilizado na V1 já descontinuada;
m. Scope: campo desabilitado, era utilizado na V1 já descontinuada;
n. URL Autorização: campo preenchido automaticamente pelo CIGAM;
o. URL API: campo preenchido automaticamente pelo CIGAM;
p. URL BOLECODE: campo preenchido automaticamente pelo CIGAM;
q. Usuário para Alerta: informe aqui o usuário que receberá os alertas de vencimento do certificado digital utilizado na parametrização. Esta informação é muito importante pois o processo de renovação junto ao Itaú pode levar alguns dias e não será possível registrar títulos com um certificado vencido.

Passo 2: Este passo diz respeito à seleção de convênios, ela é uma característica do Itaú e serve para que possa ser apontado o convênio para o qual as credenciais geradas serão válidas. O CIGAM irá apresentar todos os códigos de convênios localizados dentre os portadores cujo código de banco é “341”. Porém aqui cabe uma ressalva: a não ser que esteja discriminado nas suas credenciais, sugerimos que você clique em “pular” nesta tela, assim as suas credenciais valerão para qualquer convênio que a empresa possua.

O resultado de clicar em “pular” neste passo resultará em uma parametrização de convênio “Geral” na tela de parâmetros open banking. Depois disso, caso você deseje adicionar uma parametrização adicional, será obrigatório informar um convênio para as credenciais que se deseja adicionar (o botão pular estará desabilitado). Caso a parametrização atual possua um convênio especificado, será possível tanto configurar um novo convênio quanto pular a seleção, desta forma, as novas credenciais utilizarão um convênio “Geral”.

Passo 3: Neste passo você irá informar os portadores de remessa e retorno que serão utilizados para esta parametrização do Open Banking, aqui você pode informar mais de um portador, por exemplo, o de carteira SIMPLES e o de carteira DESCONTADA e ambos utilizarão a mesma instância de credenciais. A informação do portador de retorno é para auxiliar na sugestão da rotina de retorno.

Importante: mesmo com a utilização da opção de convênio “Geral”, os portadores de remessa e retorno devem obrigatoriamente possuir o mesmo convênio, isso é importante para que a rotina de retorno funcione corretamente.

Importante 2: O Itaú possui as opções de envio direto e registro PIX no boleto disponíveis, esta última só está disponível caso tenha sido selecionada a opção 03 – BOLECODE no passo 1 do assistente, bem como está condicionada à existência de credenciais válidas para esta API.

Passo 4: o passo 4 serve para realizar o apontamento do relatório de remessa que servirá como padrão tanto para a rotina de registro quanto para retorno do Open Banking. O CIGAM irá sugerir o caminho padrão para o modelo de relatório (RF00071), mas caso os seus modelos sejam salvos em algum outro local, basta alterá-lo neste momento, após, clique em “avançar”.

Pronto! Caso tenha dado tudo certo com as suas credenciais, o CIGAM irá emitir uma mensagem de sucesso para cada um dos ambientes para o qual você informou as credenciais.

Após clicar em “concluir” você será apresentado à tela “Parâmetros” Open Banking (conforme abaixo), você encontrará o descritivo de cada área dela no item Tela parâmetros Open Banking do manual Open Banking Geral.

A partir daqui o seu CIGAM já está parametrizado para utilizar o Open Banking do Banco Itaú, os serviços disponíveis para ele estão na tabela apresentada no início deste manual. Nas sessões a seguir estarão descritas apenas as características específicas do Itaú. Demais instruções de uso do open banking estão no Manual Open Banking - Geral.

Ambiente de testes - Itaú

A partir da V2 (01/01/2022) não está mais disponível o ambiente de testes do Itaú, para registrar títulos nesta modalidade é necessário utilizar a opção “validação” disponível nos parâmetros open banking (campo “etapa processo do boleto”), neste formato os títulos são enviados para um ambiente de testes onde é possível realizar o registro, mas não o retorno de títulos.

Registro de cobrança - Itaú

O registro do Itaú é, de maneira geral realizado como todos os outros bancos, abaixo seguem algumas explicações exclusivas.

Particularidades do cadastro de Portador - Itaú

- Agência e Conta: O portador do Itaú precisa de 12 caracteres entre Agência + Conta (completar com zeros a esquerda), do contrário, o erro abaixo será apresentado:

- Recebimentos divergentes da cobrança: Para portadores do Itaú (341) disponibilizamos o campo "Aceita recebimento divergente da cobrança". Se o checkbox for marcado, a tag "codigo_tipo_autorizacao" do envio para registro no banco será enviada com o dado "01", permitindo que o título aceite recebimentos divergentes, caso contrário, a tag será enviada como "03" e o título não permitirá este tipo de recebimento.

- Espécie: Para portadores do Itaú (341) no campo Espécie na guia CNAB do cadastro de Portadores, utilize uma das opções da coluna Código listadas abaixo a partir da documentação técnica fornecida pelo banco.

Protesto e Negativação

Protesto e negativação: O Itaú possui os serviços de protesto e negativação e apenas um destes serviços pode ficar ativo.

Conforme Manual BoleCode via API, disponibilizado pelo Itaú, os códigos das instruções para Protesto e Negativação são:

Código	Instrução
1	Protestar
2	Negativar
4	Não protestar
5	Não negativar
7	Não receber após o vencimento
8	Baixar após vencimento

No mesmo manual, não está prevista instrução para envio dos dias de protesto ou negativação, como úteis ou corridos, sendo assim consulte seu gerente de cash ou o suporte de API do Banco.

Fonte: Manual BoleCode Itaú via API

Impressão de QR Code no Boleto - Itaú (Bolecode)

Conforme já demonstrado na área de parametrização do assistente open banking do Itaú, uma empresa que queira emitir QR Codes em seus boletos deve possuir credenciais e certificado digital para a API - 03 BOLECODE. Adicionalmente, ela precisa:

• Marcar a opção “PIX” dos parâmetros open banking;
• Informar a sua chave PIX (tipo e dado) no cadastro do portador de remessa;
• Possuir a TAG qrcode_pix no seu modelo de boleto caminho para modelo padrão salvo em: I:\CIGAM\DOC\Modelos_relatorios\Gestão Financeira\Bloquetos Merge\0098 - Itau_pix.rtf

Chave obtida no cadastro do portador de remessa:
Necessário direito de Menu GF Configurações e configuração 3099 - GF - GE Permitir acesso aos Parâmetros PIX marcada para o usuário para acesso ao botão Parâmetros PIX.

Identificação no arquivo JSON de remessa:

Impressão do boleto com QR Code (Bolecode):

Particularidades de baixa - Itaú

O Itaú só permite a baixa de títulos após passado pelo menos um dia do registro.

Descrição do Erro (Banco):

"Erro na validação de Campos.
Atualização não permitida na mesma data de emissão do título."

Observação: o registro de títulos do itaú é instantâneo, mas as alterações serão processadas somente no dia seguinte.

Alterações de títulos registrados Via Open Banking - Alteração de Multa

De acordo com as orientações do Portal Developers do Itaú, a tag obrigatória codigo_tipo_multa, poderá ser:

• 01 - Quando se deseja cobrar um valor fixo de multa após o vencimento

• 02 - Quando se deseja cobrar um percentual do valor do título de multa após o vencimento

• 03 - Quando não se deseja cobrar multa caso o pagamento seja feito após o vencimento (isento)

Origem das tags

Tag	Origem no Cigam
texto_seu_numero	Número da NF + desdobramento da duplicata, do lançamento financeiro

Retorno de cobrança - Itaú

A rotina de retorno do Itaú funciona da forma padrão com exceção da explicação contida no botão de alerta disponível na rotina:

Guia Filtros

Unidade de Negócio: Filtro para a unidade de negócio do lançamento financeiro.

Empresa: Filtro para a empresa do lançamento financeiro.

Lançamento: Filtro para o número do lançamento financeiro.

Vencimento: Filtro para o vencimento do lançamento financeiro.

Data: Filtro para a data do lançamento financeiro. É possível executar com filtro inicial de data zerado e data final como a data que está executando a rotina.

Situação do Boleto: Neste filtro teremos duas opções.

• Todos: retornará todos lançamentos registrados independente da situação (entrada, baixado ou liquidado).
• Somente Abertos: retornará somente lançamentos registrados com situação em aberto (entrada). Observação: Nessa opção também serão retornados os títulos pagos via QRCode que ainda não foram liquidados manualmente no CIGAM. Feita a liquidação, o título não será mais apresentado no relatório, somente se o filtro for alterado para "Todos".

Lembrando que o retorno de títulos do Itaú é realizado pela API “CASH MANAGEMENT” que possui credenciais próprias, dessa forma, mesmo um cliente que use a forma de consumo 03 – BOLECODE, irá precisar de credenciais da V2 para realizar os seus retornos. Além disso, o banco não retorna os títulos pagos via QR CODE com status de liquidado. Desta forma, a rotina de retorno apenas indica que o título foi pago via QR Code, mas não o liquida, mesmo utilizando a opção “Retorno”. Os títulos recebidos via QR Code no Itaú devem ser liquidados manualmente dentro do CIGAM ou via retorno CNAB.

Documentos Relacionados

• Manual Open Banking - Geral
• FAQs - Open Banking
• Open Banking - Em qual tabela fica gravado o registro do campo "Situação Open Banking" do lançamento financeiro
• OpenBanking - Como fazer/revisar a instalação, para que o certificado digital, apareça nas configurações de banco em Parâmetros em seguida Status do certificado?

Documentação Itaú

• Portal Developers Itaú
• Solicitar Contato - Portal Developers Itaú
• Atendimento Itaú