Olá, seja bem-vindo!

Este manual tem como objetivo orientar a configuração e utilização da Integração bancária via API, uma funcionalidade que permite a comunicação direta, segura e automatizada entre o EMSys e a instituição financeira. Através dessa integração, é possível realizar o registro automático de boletos, consultar transações, acompanhar o status de cobranças e efetuar baixas bancárias, tudo em tempo real e com maior controle operacional.

Ao configurar os parâmetros fornecidos, o sistema é autenticado junto à instituição, permitindo o envio e recebimento de dados financeiros de forma eficiente e confiável.

Entre os principais benefícios da integração, destacam-se:

  • Redução de processos manuais;

  • Maior agilidade no controle de títulos a receber;

  • Acompanhamento automatizado de status: Pendente, Registrado, Liquidado e Protestado;

  • Mais segurança nas operações.

Atualmente, a integração está disponível exclusivamente para o Banco Itaú, com previsão de suporte a outras instituições em futuras atualizações.

Aproveite a leitura e compreenda cada etapa, desde os pré-requisitos e configurações iniciais até a utilização completa das funcionalidades.

SUMARIO

Premissas

      Antes de iniciar a configuração da Integração Bancária via API, é essencial estar com todos os dados e arquivos necessários disponíveis. Estes são fundamentais para que o processo funcione corretamente e sem interrupções.

  • Certificado Digital (contendo chave pública e chave privada);

  • Número do Convênio (não é necessário informar o número de convênio do Itaú);

  • ClientID (fornecido pelo banco);

  • ClientSecret (gerado na criação dos certificados).

Importante

      1. Geração dos arquivos .KEY e .CSR

      Para iniciar o processo de geração dos certificados, siga os passos abaixo:

      2. Instale o Git Bash:

      3. Acesse o link https://git-scm.com/download/win e baixe o instalador para o seu sistema operacional.

    • Conclua a instalação normalmente.

       4. Crie uma pasta de trabalho:

    • Crie uma pasta chamada Itaú na sua área de trabalho ou em outro local de sua preferência.

       5. Abra o Git Bash na pasta criada:

    • Acesse a pasta Itaú.

    • Clique com o botão direito do mouse dentro da pasta e selecione a opção para abrir o terminal já no diretório correto.

  • Comando para Windows:

openssl req -new -subj"//CN=CLIENT_ID\OU=SITE OU APP DO

PARCEIRO\L=CIDADE\ST=ESTADO\C=BR" -out ARQUIVO_REQUEST_CERTIFICADO.csr -nodes

-sha512 -newkey rsa:2048 -keyout ARQUIVO_CHAVE_PRIVADA.key

  • Comando para Linux:

openssl req -new -subj "/CN=CLIENT_ID/OU=/L=/ST=/C=BR" -out

ARQUIVO_REQUEST_CERTIFICADO.csr -nodes -sha512 -newkey rsa:2048 -keyout

ARQUIVO_CHAVE_PRIVADA.key


Importante

Explicação dos Campos Acima

  • Client ID: Informado no primeiro e-mail enviado.
  • Site ou App do Parceiro: Preencha com o nome da empresa ou do aplicativo que utilizará a integração.
  • Cidade: Digite sem acentuação (exemplo: Sao Paulo).
  • Estado: Informe a sigla do estado (exemplo: SP).
  • Arquivo de Requisição do Certificado (.csr): Você pode renomear o arquivo, mas deve manter a extensão .csr.
  • Arquivo da Chave Privada (.key): O nome do arquivo pode ser alterado, desde que a extensão .key seja mantida.

Após preencher os campos corretamente, clique em Enter e o sistema criará os arquivos csr e key.

2. Configurar o Postman e Enviar o Arquivo .CSR

  1. Abra o programa Postman. Caso ainda não o tenha instalado, acesse o site oficial:

       🔗 https://www.postman.com/downloads

       2. Faça o download e conclua a instalação normalmente.

       3. Com o Postman aberto, clique em "Import" (no canto superior esquerdo da tela). Essa opção permite carregar a collection (coleção de requisições) fornecida pelo banco, que será utilizada para envio do arquivo .csr.


      4. Selecione o arquivo da Collection fornecido pelo banco (geralmente disponível no Portal do Desenvolvedor) e conclua a importação.


     5. Duplique o POST e renomeie com o nome OBTER CERTIFICADO.

    6. No post insira a URL: https://sts.itau.com.br/seguranca/v1/certificado/solicitacao. Clique na aba Autorization → Type altere para Bearer token e insira o token que está contido no e-mail.



   7. Acesse a aba Headers, localize o campo Content-Type e substitua o valor application/x-www-form-urlencoded por text/plain.



   8. Na aba Body do Postman, selecione a opção raw. Em seguida, cole o conteúdo do arquivo .csr que você gerou anteriormente no Git Bash. Esse conteúdo deve conter 17 linhas.


   9. Na aba Tests, apague o conteúdo que apresentar caso tenha.

  10. Na aba Settings, desmarque a opção Enable SSL e clique em SEND.


  11. Após o envio do arquivo .csr, a resposta será exibida na aba Body → Raw do Postman. Nela, você receberá dois dados importantes: o Certificado Digital (em formato .crt) e o Client Secret.

  É muito importante que você salve ambos imediatamente. Copie o conteúdo do certificado e salve em um arquivo .crt, utilizando o Bloco de Notas. Em seguida, salve o Client    Secret em outro arquivo separado, também no Bloco de Notas.

   Esses dados serão necessários para configurar o EMSys.

  Se desejar, é possível validar o conteúdo do certificado .crt acessando o site:

  https://www.sslshopper.com/certificate-decoder.html


   Observação: Caso queira o certificado em formato PFX, colar no GIT BASH o comando a baixo, o sistema pegará o KEY e o crt e fará uma unificação. Lembre-se de anotar a senha inserida no GIT BASH, caso não queira senha basta teclar Enter 3 vezes no GIT e será gerado o pfx sem senha.

  Comando:

  Winpty openssl pkcs12 -export -out domain.name.pfx -inkey domain.name.key -indomain.name.crt

  •   No campo domain.name.key: Informar o nome do arquivo Key gerado na 1° etapa desse e-mail:

   Ex: ARQUIVO_CHAVE_PRIVADA.key

  •   No campo domain.name.crt: colocar o mesmo nome que usou para salvar o crt no bloco de notas.

  

 Caso a implantação da API seja realizada via Postman, insira o certificado e a chave .key na rota abaixo. Se for utilizar em programação própria, basta seguir conforme as   instruções disponíveis no Devportal.

 No Postman, clique em Settings  → Certificates, digite no campo Host¹: api.itau.com.br (para emissão da API de Cobrança). Para realizar consultas do tipo GET, inclua a   URL: secure.api.cloud.itau.com.br e anexe o arquivo .crt e a chave .key.

 Repita o mesmo procedimento para a URL: sts.itau.com.br (utilizada para obter o access token). Para emissões de PIX, utilize a URL: secure.api.itau.

 Observação: Não copie e cole os hosts, é recomendável digitá-los manualmente.


Configuração

      1. Acessar o Módulo Financeiro

      Acesse: Financeiro → Banco → Conta Bancária.

       2. Selecionar a conta

       Pesquise pela conta bancária que será integrada via API.


     3. Informações Iniciais

     Marque a opção API Bancária, perceba que a aba API Bancária será habilitada.



   4. Configuração da API Bancária 

   Acesse a aba API Bancária e informe os dados fornecidos pelo banco:

  • ClientID

  • ClientSecret

   5. Importação do Certificado Digital

    Clique no botão Importar Certificado.


  • Informe a chave pública e a chave privada.

  • Utilize o ícone de lupa para localizar os arquivos, se necessário.

  • Preencha a validade do certificado digital.



  • Clique em Salvar para gravar as informações.


Classificação de Status dos Títulos

Título PENDENTE: Título a receber com status ABERTO, que ainda não foi registrado na API bancária.
Título REGISTRADO: Título a receber com status ABERTO, que foi registrado na API bancária e está aguardando pagamento ou baixa manual.
Título BAIXADO: Título a receber com status ABERTO, que foi registrado na API bancária, mas foi baixado manualmente por um usuário do sistema, mesmo sem o pagamento efetivo (por exemplo, em casos de acordos, cancelamentos ou ajustes).
Título LIQUIDADO: Título a receber registrado na API bancária e que teve pagamento parcial ou total confirmado (conforme acordado com o cliente). Na consulta do título, este estará com status LIQUIDADO.
Título PROTESTADO: Título a receber registrado na API bancária que não foi pago dentro do prazo estipulado e foi encaminhado para protesto. Na consulta do título, este estará com status EM PROTESTO.
 

Consultar Títulos a Receber com status Pendente

  • A Conta Bancária deve estar previamente configurada com a API Bancária ativa e funcional;

  • Os Títulos a Receber devem estar vinculados a um Tipo de Cobrança que, por sua vez, esteja associado à mesma Conta Bancária.

           Passo a passo

Acesse Financeiro → Banco →  Integração Bancária.

  1. Clique em Pesquisar Mnemônico (Lupa) e selecione a Conta Bancária;

  2. No campo Cobrança informe o Tipo Cobrança que deseja pesquisar;

  3. Marque a caixa status PENDENTE;

  4. Informe o Período (neste filtro é possível selecionar por VENCIMENTO do Título ou EMISSÃO do Título);

  5.  Clique em Pesquisar.

Registrando Título a Receber na API Bancária


  1. Após a pesquisa dos títulos pendentes e/ou baixados (passos anteriores).       
  2. Selecione o Título que deseja registrar e clique no botão Registrar. 

       Observação: Apenas os Títulos com status PENDENTE e BAIXADO podem ser registrados na API Bancária.




       3. Caso o cliente opte pode salvar o boleto gerado em PDF, basta marcar a caixa Gerar PDF ao registrar Boleto antes de realizar o registro dos títulos PENDENTES ou BAIXADOS.



       4. O sistema enviará as informações para a API e, ao receber a confirmação de que o boleto foi registrado com sucesso, exibirá uma mensagem de confirmação. A coluna Status será atualizada de Pendente para Registrado.



      5. Os arquivos em PDF gerados ao marcar a opção Gerar PDF ao registrar Boleto, serão salvos automaticamente na pasta C:\Rezende\IntegracaoBancaria do seu computador.



        Observação: Os boletos gerados serão nomeados seguindo a padronização de NOME DO SACADO, DATA do vencimento e HORA do registro deste boleto na API Bancária.


Envio de Alteração de Boleto Registrado

  • Boletos com status REGISTRADO na tela Integração Bancária.

         Passo a passo

        Acesse Financeiro → Banco → Integração Bancária.

  1. Clique em Pesquisar Mnemônico (Lupa) e selecione a Conta Bancária;

  2. No campo Cobrança informe o Tipo Cobrança que deseja pesquisar;

  3. Marque a caixa status REGISTRADO;

  4. Informe o Período (neste filtro é possível selecionar por VENCIMENTO do Título ou EMISSÃO do Título);

  5.  Clique em Pesquisar.



      6. Selecione o boleto que será realizado a baixa, e clique em Enviar Alteração.



      7. Será aberto a tela de Seleção de Instrução.


   

    8. Selecione qual alteração será enviada informe no campo abaixo qual valor será alterado e clique em OK.



     Observação: Só é permitido enviar as seguintes alterações: data, multa, juros e desconto (a multa pode ser configurada tanto em valor fixo (ex.: R$ 10,00) quanto em percentual, exemplo.: 10%).


Como Consultar se um Título Registrado Foi Liquidado

  • Boletos com status REGISTRADO na tela Integração Bancária.

           Acesse Financeiro → Banco → Integração Bancária.

  1. Clique em Pesquisar Mnemônico (Lupa) e selecione a Conta Bancária;

  2. No campo Cobrança informe o Tipo Cobrança que deseja pesquisar;

  3. Marque a caixa status REGISTRADO;

  4. Informe o Período (neste filtro é possível selecionar por VENCIMENTO do Título ou EMISSÃO do Título);

  5.  Clique em Pesquisar.



     

     6.  Selecione o boleto que deseja consultar e clique em Consultar. O sistema realizará a verificação do boleto e, ao final do processo, exibirá a mensagem: "Boletos consultados com sucesso!". Caso o boleto esteja liquidado, o status será automaticamente atualizado.



Visualizar Título Liquidado

  • Boletos com status LIQUIDADO na tela Integração Bancária.
  • Os títulos já consultados no tópico anterior, podem ser visualizados pelo filtro de status LIQUIDADO.

        Passo a passo

        Acesse Financeiro → Banco → Integração Bancária.

  1. Clique em Pesquisar Mnemônico (Lupa) e selecione a Conta Bancária;

  2. No campo Cobrança informe o Tipo Cobrança que deseja pesquisar;

  3. Marque a caixa status LIQUIDADO;

  4. Informe o Período (neste filtro é possível selecionar por data de VENCIMENTO do Título, data de LIQUIDAÇÃO do Título ou data EMISSÃO do Título);

  5.  Clique em Pesquisar.


      

Realizar a baixa dos boletos via API Bancária

  • Boletos com status REGISTRADO na tela Integração Bancária.

          Passo a passo

          Acesse Financeiro → Banco → Integração Bancária.

  1. Clique em Pesquisar Mnemônico (Lupa) e selecione a Conta Bancária;

  2. No campo Cobrança informe o Tipo Cobrança que deseja pesquisar;

  3. Marque a caixa status REGISTRADO;

  4. Informe o Período (neste filtro é possível selecionar por VENCIMENTO do Título ou EMISSÃO do Título);

  5.  Clique em Pesquisar.



     

      6. Selecione o boleto que será realizado a baixa e clique em Baixar.


       

     7. O sistema exibirá uma mensagem solicitando a confirmação do usuário. Ao clicar em Não, a mensagem será fechada e nenhuma alteração será realizada. Ao clicar em Sim, o sistema prosseguirá com o processo de baixa do boleto.


     

      8. Clicando em Yes é exiba uma nova mensagem, onde é perguntado ao usuário se "Deseja consultar o boleto referente ao título XXX antes de realizar a baixa?".



      9. Clicando em Yes a API é consultada e caso o retorno seja LIQUIDADO o boleto não poderá ser baixado.



      10. Caso a consulta realizada na API retorne como REGISTRADO a realização da baixa segue normalmente. Clicando em No não é realizado a consulta deste boleto.

      11. Após o passo anterior e a baixa for realizada o sistema exibirá a mensagem de sucesso, o status do boleto será atualizado para BAIXADO.



Realizar Protesto de Título Registrado


  • Boletos com status REGISTRADO na tela Integração Bancária.

          Passo a passo

          Acesse Financeiro → Banco → Integração Bancária.

  1. Clique em Pesquisar Mnemônico (Lupa) e selecione a Conta Bancária;

  2. No campo Cobrança informe o Tipo Cobrança que deseja pesquisar;

  3. No menu lateral clique no “+” ao lado da palavra Cobrança, será aberto a aba PROTESTO;

  4. Selecione o status REGISTRADO;
  5. Informe o Período;
  6. Clique em Pesquisar.



        7.Selecione o Título e clique em Protestar.


 

  

      8. Será exibida uma mensagem de confirmação do protesto clicando em No a mensagem é fechada e nenhuma alteração é realizada, clicando em Yes o sistema segue com o processo para realizar o protesto do boleto.



    9. Informe a data do protesto, Escritório de Cobrança e  clique em Salvar.


   


     10. Será exibida a mensagem “Boleto alterados com sucesso!” e o status será atualizado para PROTESTADO.



Consulta Título Protestado e Cancelamento de Protesto


  • Boletos com status PROTESTADO na tela Integração Bancária;

           Passo a passo

           Acesse Financeiro → Banco → Integração Bancária.

  1. Clique em Pesquisar Mnemônico (Lupa) e selecione a Conta Bancária;

  2. No campo Cobrança informe o Tipo Cobrança que deseja pesquisar;

  3. No menu lateral clique no “+” ao lado da palavra “Cobrança”, será aberto a aba PROTESTO;

  4. Selecione o status PROTESTADO;

  5. Informe o Período;

  6. Clique em Pesquisar.



        7. Caso queira realizar o cancelamento do Protesto, selecione o boleto e em seguida clique em Cancelar Protesto.


        8. Será exibida uma mensagem de confirmação do protesto clicando em No a mensagem é fechada e nenhuma alteração é realizada, clicando em Yes o sistema segue com o processo para realizar o cancelamento do protesto do boleto.



         9. Informe a data e o motivo do cancelamento do protesto e em seguida clique em Salvar.



          10. Será exibida a mensagem “Boleto alterados com sucesso!” e o status será atualizado para CANCELAMENTO ENVIADO.



  • Sem rótulos