Codificação da integração: Utilização do Charset UTF-8

Por que é recomendamos esta codificação

Dentro do padrão de comunicação bancário, algo ainda muito comum é o tráfego de arquivos entre correntista e banco para efetuar o registro dos boletos, alterações e baixas.

Trata-se de uma das formas de comunicação mais utilizadas, e que envolve um amplo e frequente fluxo de troca de arquivos “.txt” entre as partes envolvidas no processo.

Neste processo é comum identificarmos falhas na recepção destes arquivos pelos bancos, onde, devido a presença de caracteres indevidos, especiais ou ocultos, as linhas do arquivo de remessa podem ficar desconfiguradas. Como no tráfego de informações por arquivo cada linha e cada posição é determinante para seu correto processamento, caracteres desconhecidos podem fazer com que linhas do arquivo de remessa fiquem fora do padrão esperado, resultando em falhas na recepção e processamento destes arquivos.

O que a Tecnospeed já possui

Em nossa aplicação existem métodos que recepcionam e validam as informações obtidas, e nosso sistema possui métodos que substituem caracteres especiais conhecidos e não permitem que os mesmos sejam inseridos nos arquivos de remessa.

Esta é uma medida eficiente que reduz drasticamente a incidência de problemas nos arquivos, porém, como há um número muito grande de formatos de texto (codificações) e de fontes de origem destes dados, o tratamento de tais caracteres acaba sendo reativo. Ou seja, precisamos mapear o problema após identificarmos as falhas.

Por isso, após termos construído uma ampla estrutura de substituição de caracteres, avaliamos que é o momento de validar as informações que chegam até nossa API de forma mais completa.

O que a Software House precisa implementar

Antes de mais nada é importante ressaltar que a codificação UTF-8 é a codificação padrão da maioria das linguagens de programação, e mesmo as que não possuem este formato como padrão, possuem métodos nativos para a conversão de strings.

Então, neste contexto recomenda-se que:

• Nas definições de headers das requisições HTTP enviadas para nossa API, enviar o “Content-type” com os parâmetros “application/json; charset=utf-8”;
• Caso utilize a integração via OCX, a alimentação dos métodos que recebem texto como parâmetro (como por exemplo o método “FBoletoX.Incluir”) seja convertida para UTF-8 antes de alimentar o método;
• Caso utilize a integração via API e alimente campos a partir do banco de dados, que as informações que compõem o JSON sejam convertidas para UTF-8 na montagem do arquivo ou antes de alimentar o body da requisição com a string (JSON) gerada.

Caracteres aceitos e não aceitos:

Continuarão sendo aceitos os caracteres presentes na cododificação UTF-8, tal qual:

• Ç, À, Á, Ã e demais

Já caracteres que ao serem convertidos para o padrão UTF-8 geram uma quebra/falha na conversão passarão a ser validados, por exemplo:

No exemplo acima, os caracteres "á", "ã" e "é" forma enviados para nossa aplicação em um formato de arquivos desconhecido, e ao serem convertidos não foram lidos de forma adequada. 

Como se trata de um padrão de texto não definido no envio, há uma inviabilidade no uso do "regex" para substituir tais caracteres. 

Por conta disso, recomendamos a conversão do body da requisição (JSON) para UTF-8 antes do envio, para que as requisições cheguem aqui no padrão correto.

O que ocorrerá caso a Tecnospeed identifique caracteres não-aceitos?

A partir de 14/03/2023 as requisições com tais caracteres serão rejeitadas na inclusão. Ou seja, seu ERP receberá uma mensagem de rejeição.

Para dar sequência no processo de emissão basta efetuar a remoção dos caracteres inválidos do JSON (caso não seja convertido) e reenviá-lo para a API.

Formato da mensagem de falha:

Caso se identifique caracteres inválidos no texto a API irá identificar o campo cujo caractere foi identificado.

O padrão da resposta da rota POST de envio será:

{
   "_status": "erro",
   "_mensagem": "Erro de validação.",
   "_dados": [
      {
         "_campo": "SacadoEnderecoLogradouro",
         "_erro": "Campo contêm caracteres inválidos"
      },
      {
         "_campo": "SacadoEnderecoCidade",
         "_erro": "Campo contêm caracteres inválidos"
      }
   ]
}

Reforçamos que esta mudança tem como principal objetivo a redução de casos onde falhas no registro de títulos geram impacto financeiro ao cliente final.

Estamos também a total disposição para apoiar nossos parceiros nesta manutenção, e se houver qualquer dúvida fique a vontade para nos acionar!

Atenciosamente,