- Visão Geral
- Fluxograma completo de utilização
-
Como obter credenciais junto ao banco
- Como configurar as credenciais no PlugBoleto
- Instruções e codigos aceitos no registro via API
-
Recursos disponíveis API Itau
Visão Geral
O recurso de transmissão instantânea foi desenvolvido para facilitar a integração de sistemas de cobrança com as APIs bancárias, oferecendo uma solução prática e eficiente para desenvolvedores.
Esse método permite a consulta direta dos dados dos boletos nos servidores bancários, retornando imediatamente após sua criação o status REGISTRADO como nos boletos de cobranças de grandes marketplaces.
Ao utilizar a transmissão instantânea, desenvolvedores conseguem implementar um fluxo de emissão de boletos mais ágil e seguro, permitindo que clientes finais possam realizar o pagamento dos títulos logo após a criação. Isso elimina o tempo de espera que existe no tradicional método de transmissão de remessas e obtenção de retorno que é D+1, já que cada boleto emitido pelo sistema é validado instantaneamente, integrando-se com o servidor bancário em tempo real.
Essa solução simplifica a comunicação com instituições financeiras, reduzindo o esforço de implementação e manutenção de sistemas de cobrança, enquanto melhora a experiência do usuário final. Com a transmissão instantânea, é possível construir aplicações financeiras robustas que garantem precisão nos dados de pagamento, ao mesmo tempo em que agilizam o processo de verificação e registro de boletos.
Atenção: Apesar de a captura do status de REGISTRO ou REJEIÇÃO via API ser imediato as LIQUIDAÇÕES(pagamentos) não seguem a mesma dinâmica, dependendo dos procedimentos internos do banco. Isso significa que o status de liquidação não está disponível instantaneamente e depende dos prazos internos de atualização de suas bases. Esse tempo pode variar de acordo com o banco e o serviço de API.
Fluxograma completo de utilização
Como obter credenciais junto ao banco
Pré-requisitos para realizar o procedimento completo de liberação de credenciais bancárias.
Postman ou Insomnia: Ou qualquer outra ferramenta de sua preferencia para realizar o disparos de requisições HTTPS.
OpenSSL: Tenha o OpenSSL instalado em sua maquina pois será a ferramenta utilizada para executar os comandos necessários durante o processo.
Importante: Por padrão o OpenSSL vem por default para quem tem o Git Bash instalado na máquina.
Após ter obtido as ferramentas necessárias passaremos para o primeiro passo do processo de obtenção de credencias que é a geração do par de chaves.
Geração do par de chaves
Para que o banco realize a geração das credenciais, será solicitado ao titular da conta dois arquivos
- private.pem
- public.pem
Estes arquivos podem ser gerados a partir do open SSL utilizando o seguinte comando:
openssl genpkey -out private.pem -algorithm RSA -pkeyopt rsa_keygen_bits:2048 && openssl rsa -in private.pem -pubout -out public.pem
Separe uma pasta para armazenar os arquivos referentes ao processo de liberação de credenciais, abra o terminal dentro da mesma e execute comando a cima, caso tenha ocorrido tudo certo os arquivos serão criados na pasta.
Após estar com a chave publica e privada em mãos deve-se ser solicitado ao ponto focal do cedente no banco(gerente de conta) o token temporário. Você receberá um token por e-mail com validade de 7 dias corridos com o único objetivo de emitir suas credenciais e o certificado, após este período esse token será invalidado. É fundamental seguir o procedimento de recebimento das credenciais de acesso e emissão do certificado dentro desse prazo a contar da data de emissão do token.
Após feito o contato com o gerente de conta o será recebido um e-mail com o client id e o token temporário.
Geração do certificado .CSR e KEY com o OpenSSL.
Se chegou até aqui, provavelmente possui as credenciais disponibilizadas pelo banco, agora precisamos gerar um certificado para que possamos ter acesso a outros dados que o banco estará disponibilizando, para isso temos que gerar o arquivo .CSR e KEY.
Copie o comando que está lista abaixo altere as informações em um editor de texto conforme o descritivo também listado abaixo e então volte a pasta onde foi criado o par de chaves abra novamente o terminal e execute o comando com os dados do cedente.
Para Windows:
openssl req -new -subj "//CN=CLIENTID\OU=tecnospeed\L=CIDADE\ST=ESTADO\C=BR" -out ARQUIVO_REQUEST_CERTIFICADO.csr -nodes -sha512 -newkey rsa:2048 -keyout ARQUIVO_CHAVE_PRIVADA.key
Para Ubuntu:
openssl req -new -subj "/CN=ClientID/OU=tecnospeed/L=CIDADE/ST=ESTADO/C=BR" -out ARQUIVO_REQUEST_CERTIFICADO.csr -nodes -sha512 -newkey rsa:2048 -keyout ARQUIVO_CHAVE_PRIVADA.key
.
Atenção: Explicação dos campos listados no comando e orientações dos que devem ser substituidos com os dados do cedente.
- CN = ClientID disponibilizado via e-mail
- OU = Deixe preenchido como tecnospeed
- L = Cidade onde se localiza a Agência do cliente
- ESTADO = onde se localiza a Agência do cliente
- C = País onde se localiza a Agência do cliente
- ARQUIVO_REQUEST_CERTIFICADO.csr = Dê um nome ao seu certificado csr que será gerado
- ARQUIVO_CHAVE_PRIVADA = Dê um nome a chave Key vinculada ao certificado
Ao executar o comando em seu terminal, temos os seguintes arquivos gerados em sua pasta
Estes arquivos serão utilizados no próximo passo.
Envio do arquivo .CSR via request
Neste passo utilizaremos o Insomnia ou Postman para realizar o envio do arquivo.csr ao banco.
Abra o arquivo .csr criado anteriormente em um editor de texto copie o conteúdo do arquivo e adicione ao body da requisição, devendo ficar conforme exemplo abaixo
Na mesma requisição, adicione também o token temporário retornado pelo banco neste passo
Após adicionar o conteúdo em texto do arquivo certificado.csr e o token temporário dispare a requisição e então será recebido como resposta da requisição o certificado final em texto e também o Secret conforme a imagem abaixo:
Copie o conteúdo do certificado que vai de -----BEGIN CERTIFICATE---- até -----END CERTIFICATE---- e então salve o arquivo com a extensão .crt, após realizado esse processo copie também a primeira linha da resposta que refere-se ao secret e salve também como .txt.
Conversão do arquivo .CRT em .PFX
Caso tenha passado por todos os passos a cima sem problemas você ja tem credenciais validas para utilizar a api do banco ITAU basta agora transformar o arquivo .crt em .pfx para criar uma senha.
Novamente dentro da pasta onde esta utilizando para armazenar os arquivos de credenciais abra o terminal e execute o comando abaixo substituindo caso queira o nome do arquivo .pfx que será criado e colocando o nome do arquivo .key criado neste passo.
openssl pkcs12 -export -out certificado_convertido.pfx -inkey Chave.key -in Certificado.crt
Digite e repita uma senha
Pronto! Certificado convertido. Basta acessar a pasta e verificar que foi criado o arquivo certificado_convertido.pfx e este será o certificado utilizado para a emissão de cobrança nos próximos 365 dias.
Caso queira utilizar nossa ferramenta de conversão para a execução do ultimo passo acesse o link https://mkt.casadodesenvolvedor.com.br/casadodev-conversor-de-certificado e faça o download da pasta compactada "CONVERTPLUGBANK.zip", extraia os arquivos na pasta onde deseja armazenar a ferramenta e então execute o arquivo "conversor_tecnospeed.exe".
Como configurar as credenciais no PlugBoleto
Para melhor visualização e entendimento do processo vamos utilizar nossa GUI WEB para explicar o preenchimento de campos mas esse processo também poderá ser realizado via API conforme a documentação de integração com a API PlugBoletos.
Após realizar o cadastro da conta, acesse a na página de convênios e caso não tenha sido ainda criado o convenio referente a conta deve ser criado conforme a documentação de cadastro de convênios.
Com o convenio criado ative a opção "Registro instantâneo", esse campo é onde você habilita o uso desse recurso no seu convênio.
Quando o campo Registro instantâneo for ativado deve aparecer logo abaixo novos campos o primeiro é "Versão web service" que deve ser preenchido com V2, o segundo é o campo "API - ID" onde deve ser informado o client_id informado pelo Itaú neste passo, em seguida vem o campo "Segredo" onde deve ser informado o secret recebido neste passo.
Como ultimo requisito para registro de boletos temos o campo para ser feito o upload do certificado.pfx obtido neste passo juntamente com a senha que foi definida na conversão de .crt para .pfx.
Observação importante:
O Itaú possui algumas particularidades quanto à data de vencimento do certificado. Se o certificado vencer, ao realizar a atualização no sistema do Itaú é preciso trocar o certificado e gerar novos clientID e Secret, e consequentemente, atualizá-los no PlugBoleto junto ao novo certificado para que as novas emissões ocorram com sucesso.
Já se o certificado estiver prestes a vencer, e seja feita a atualização no sistema do Itaú antes do vencimento, é necessário apenas fazer a atualização do certificado, sem atualizar o clientID e Secret. Sendo assim, é necessário apenas atualizar o certificado no PlugBoleto.
Exemplo do cadastro das credenciais no portal do Plugboleto:
Existem mais alguns campos que irão ser disponibilizados para utilização como "Alteração via WS", "Utilizar Bolecode" e "Consulta Francesa" que abordaremos mais a frente no material, neste momento focaremos apenas nos campos necessários para REGISTRO de boletos.
Instruções e códigos aceitos no registro via API
Como informar Juros
| Campo | Valores aceitos | Tamanho mínimo | Tamanho máximo |
| TituloCodigoJuros |
1 - Valor por dia. 2 - Valor em percentual mensal. |
||
| TituloDataJuros | DD/MM/AAAA | ||
| TituloValorJuros | 15 |
Como informar Multa
| Campo | Valores aceitos | Tamanho mínimo | Tamanho máximo |
| TituloCodigoMulta |
0 - Não registra multa (isento). 1 - Valor em Reais (Fixo). 2 - Valor em percentual com duas casas decimais.. Clique aqui para ter a descrição dos códigos |
||
| TituloDataMulta | DD/MM/AAAA | ||
| TituloValorMultaTaxa | 15 |
Como informar Desconto
| Campo | Valores aceitos | Tamanho mínimo | Tamanho máximo |
| TituloCodDesconto |
0 - Sem instrução de desconto. 2 - Valor em percentual até a Data informada |
||
| TituloDataDesconto | DD/MM/AAAA | ||
| TituloValorDescontoTaxa | 15 | ||
| TituloCodDesconto2 |
0 - Sem instrução de desconto. 2 - Valor em percentual até a Data informada |
||
| TituloDataDesconto2 | DD/MM/AAAA | ||
| TituloValorDescontoTaxa2 | 15 |
Como informar Protesto
| Campo | Valores aceitos | Tamanho mínimo | Tamanho máximo |
| TituloCodProtesto | boolean: true ou false reveeer | ||
| TituloPrazoProtesto | Quantidade de dias | 02 |
Outros campos que possuem validação
| Campo | valores aceitos | Tamanho mínimo | Tamanho máximo |
| ContaAgencia | 4 | ||
| ContaNumero | 5 | ||
| CodigoCarteira | 3 | ||
| TituloNossoNumero | 8 | ||
| TituloNumeroDocumento | 10 | ||
| TituloValor | 13 | ||
| TituloDocEspecie | ['01', '02', '03', '04', '05', '06', '07', '08', '09', '13', '15', '16', '17', '18', '99'] Clique aqui para a ter descrição dos códigos, |
||
| TituloAceite | S - Aceito; N - Não Aceito | ||
| TituloCodProtesto | [1, 2, 3, 7] Clique aqui para ter a descrição dos códigos | ||
| TituloCodBaixaDevolucao | 1 - Baixar/Devolver | ||
| SacadoEnderecoCep | 8 |
Informações disponíveis para consulta via API bancária
Com a atualização via API o banco Itau reduz a quantidade de informações disponibilizadas sobre o pagamento limitando se as principais informações de LIQUIDAÇÃO:
- Situação
- PagamentoData
- PagamentoValorPago
- PagamentoValorAcrescimos
Vale apenas ressaltar que todas as outras informações da cobrança já foram capturadas e estamos focando apenas em campos atualizados após o pagamento do titulo.
Recursos disponíveis API Itau
Boleto Hibrido Itau
O boleto híbrido ou Bolecode como é conhecido no Itau é uma combinação entre boleto e Pix referente a mesma cobrança, em outra palavras, é possível fornecer aos clientes um tipo de cobrança que pode ser quitada através do código de barras de um boleto ou via QRCode do PIX.
O que é necessario para utilizar o Boleto Hibrido com o banco Itau?
Para realizar a utilização do boleto híbrido é necessário que tenha sido finalizado o processo de obtenção de credenciais de COBRANÇA e PIX e feito o upload das mesmas no Plugboleto.
Emitindo o boleto híbrido VIA API
Para comandar que um boleto seja registrado no modelo HIBRIDO basta adicionar ao JSON de envio anteriormente implementado o campo chamado "hibrido": true, caso tenha duvidas sobre a implementação da rota de inclusão de boletos basta acessar nossa documentação.
Abaixo um exemplo do campo a ser adicionado:
{
...
...
"TituloNossoNumero":"123",
"TituloValor":"100,00",
"hibrido": true
}
Consultando o boleto híbrido
A consulta do boleto hibrido segue a mesma implementação da consulta de boletos tradicionais conforme a documentação de consulta de boletos, sendo necessário apenas a leitura dos dois novos campos referentes ao boleto hibrido.
{
"hibrido": true,
"UrlPix": "http://plugboleto.com.br/api/v1/boletos/impressao/HRKCVJXVV/pix",
}
Impressão do boleto híbrido
Para saber mais sobre os tipos de impressão, acesse a documentação referente aos exemplos de impressão.
Exemplo de boleto híbrido:
Consulta de Boletos
Consulta individual
As requisições que forem disparadas para o endpoint de consulta do Plugboleto serão imediatamente processadas e apresentará os dados atuais do titulo em nosso banco de dados, em seguida replicaremos a consulta diretamente no servidor bancário a fim de buscar uma possível atualização de dados, caso seja identificado uma atualização de status automaticamente será disparado um webhook de notificação para a Software House, caso não tenha webhook configurado é possível obter as atualizações realizando uma nova consulta em seguida.
Um boleto pode ter 7 situações diferentes, que podem ser verificadas neste link.
Para verificar quais campos são retornados nesta consulta, clique aqui.
Consulta Automática
O PlugBoletos conta com rotinas de consultas automáticas que tem como intuito dar mais confiabilidade e celeridade as conciliações de boletos, no momento para o banco ITAU adotamos uma abordagem de consulta mista com as seguintes etapas:
-
Consulta Francesa
Diariamente, por volta das 7 horas da manhã, o PlugBoleto realiza a consulta francesa para obter atualizações de status de boletos diretamente do servidor bancário. Esse processo envolve uma solicitação única enviada ao ITAU, que lista as identificações de todos os boletos que tiveram atualização de status até aquele momento.
Após receber essa listagem, o PlugBoleto realiza consultas pontuais, garantindo a atualização de informações de forma mais efetiva. Com as consultas concluídas, webhooks de notificação são disparados para a Software House, informando o status atualizado de cada boleto. Esse fluxo diário mantém a base de dados dos clientes sincronizada com o banco, promovendo eficiência e precisão nas informações de cobrança.
Para ser possível a utilização da consulta francesa é necessário que o parâmetro seja ativado no cadastro de convênio.
-
Consulta geral em boletos REGISTRADOS
Considerando que a consulta francesa não esta ativa em todos os convênios existe uma consulta secundaria que é realizada em todos os títulos com status de REGISTRADO em nossa base, ela se inicia após a finalização da francesa então não possui um horário fixo para início, pois depende da conclusão da consulta francesa, cujo tempo de execução pode variar.
Essa consulta complementar assegura a integridade dos dados de cobrança, criando uma redundância no processo com o intuito de aumentar ao máximo a confiabilidade no processo de captura de atualizações.
Alteração Individual de Boletos via API
A alteração de boletos é útil em situações onde informações previamente registradas, como data de vencimento, valor ou valor de abatimento precisam ser modificadas após o titulo ja estar registrado. Abaixo está uma visão geral de como funciona o processo de alteração de boletos via API bancária no PlugBoletos.
Requisitos para a Alteração de Boletos
Antes de comandar uma alteração, é importante garantir que o boleto se enquadra em alguns requisitos:
- O boleto precisa estar REGISTRADO no Itaú.
- Apenas determinados campos podem ser modificados, como data de vencimento, valor de cobrança, multa, juros e descontos aplicáveis.
- É necessário possuir as credenciais de autenticação bancárias descritas em Como obter credenciais junto ao banco para acessar a API ITAU V2.
Como ativar a Alteração via API
Para ativar a funcionalidade de alteração após ter configurado as credenciais no convenio basta ativar a opção "Alteração via WS" no cadastro de convenio.
Como disparar a requisição para realizar a alteração individual via API BANCÁRIA.
POST
Homologação:
Produção:
Headers
| Nome | Descrição | Exemplo |
|---|---|---|
| Content-Type | Indica o tipo de arquivo | application/json |
| cnpj-cedente | CNPJ do Cedente | 01001001000113 |
| cnpj-sh | CNPJ da Software House | 01001001000113 |
| token-sh | Token da Software House | f22b97c0c9a3d41ac0a3875aba69e5aa |
Headers (Opcional)
Utilizar esses headers em caso de autenticação direto com as credenciais do cedente:
| Nome | Descrição | Exemplo |
|---|---|---|
| Content-Type | Indica o tipo de arquivo | application/json |
| cnpj-cedente | CNPJ do Cedente | 01001001000113 |
| token-cedente | Token do Cedente | f22b97c0c9a3d41ac0a3875aba69e5aa1 |
Campos disponíveis para alteração
| Campo | Descrição | Exemplo |
| TituloValor |
Altera o valor do título
Boletos aptos a alteração de valor de acordo com as regras especificas do Itau API V2.
|
15,00 |
| TituloDataVencimento | Alterar a data de vencimento | 15/03/2023 |
| TituloValorDescontoTaxa | Alterar o valor do desconto | 100 |
| TituloValorAbatimento | Alterar o valor do abatimento ou redução do valor do boleto | 5 |
| TituloCodProtesto | Alterar o código de protesto | 8 |
| TituloPrazoProtesto | Alterar a data do protesto | 20/02/2023 |
Baixa de Boletos
Para boletos que alcançaram o status de REGISTRADO, o cancelamento só pode ser realizado através de uma solicitação formal de BAIXA. Esse processo, para o Itaú, pode ser automatizado diretamente por meio da API bancária, facilitando o cancelamento e integração com sistemas de cobrança.
Requisitos para a Baixa de Boletos
- Status de REGISTRADO: Assim que um boleto é registrado no banco, ele fica disponível para pagamento e segue sob controle do sistema bancário.
- Solicitação de Baixa: Caso o boleto precise ser cancelado (por exemplo, devido a duplicidades, erros ou desistência de cobrança), uma requisição de baixa deve ser enviada ao banco.
- É necessário possuir as credenciais de autenticação bancárias descritas em Como obter credenciais junto ao banco para acessar a API ITAU V2.
Como solicitar a Baixa
Para realizar a solicitação de baixa basta realizar a integração com o endpoint de baixa do Plugboletos.
Possíveis problemas e como soluciona-los
- Credenciais geradas pelo ITAU sem os escopos necessários
Em alguns casos o banco chega a gerar as credenciais aparentemente corretas com client id secret porém as credencias são disponibilizadas sem os escopos necessários para as funcionalidades que o cedente necessita, nesses casos vem com o "scope": "escopo_default".
Quando confirmado essa situação deve se ser enviado um e-mail para a equipe de implantação do ITAU informando que o escopo liberado foi apenas o "escopo_default" e solicitando a liberação dos seguintes escopos:
"escopo_default boletoscash-boletos-consulta_titulo appid-c5943a48-b387-43a9-8929-efd3062ff332 cash_management/instrucaocobranca.write cash_management/emissaocobranca.write boletoscash-notificacoesboletos-webhook.read boletoscash-notificacoesboletos-webhook.write"
Comentários
0 comentário
Por favor, entre para comentar.