Erros Comuns na Comunicação e Impressão de Cobranças Gateway - Boleto híbrido e Pix
Introdução
O processo de registrar e imprimir cobranças é muito importante para o bom funcionamento do setor financeiro da empresa. No entanto, às vezes podem acontecer erros que geram problemas e atrasos na hora de receber os valores. Este documento reúne os principais erros que normalmente acontecem e que impedem o registro e a impressão das cobranças, levando em conta as várias formas de integração financeira que o sistema oferece.
Tipos de Erros Comuns
Erro de Conexão
Uma das falhas mais comuns consiste na interrupção da comunicação com o servidor da instituição responsável pela integração financeira, decorrente de eventuais problemas de conectividade de rede, configurações inadequadas ou indisponibilidade temporária do serviço.
Causas possíveis:
- Instabilidade na conexão de internet.
- Firewall bloqueando a comunicação.
- Servidor da instituição em manutenção.
Soluções:
- Verifique a conexão de internet.
- Confira as configurações de firewall.
- Tente novamente mais tarde se o problema persistir, ou contate o SAC - Suporte Financeiro.
Erros de Comunicação e Impressão por Integração Financeira
A seguir, encontram-se os principais erros detectados na comunicação e impressão de boletos de cobrança, tanto para carteiras em fase de homologação quanto em ambiente de produção.
Gateway Efí Bank
Erros Conhecidos
A string não corresponde ao modelo:
^[1-9]{2}9?[0-9]{8}$
- Motivo: Telefone de contato do cadastro do cliente não corresponde ao padrão nacional: (xx) 9xxxx-xxxx.
- No Sistema, acessar a aba Contato no cadastro do cliente e corrigir o formato do telefone em seus respectivos campos.
- Atenção
- No gateway Efí, o número de telefone celular não é mais obrigatório no registro de cobranças. Caso informado, o formato deve ser validado e precisa estar no padrão nacional para o sucesso da comunicação.
cURL error6: Could not resolve host: api.gerencianet.com.br (see
http://curl.haxx.se/libcurl-erros.html)
- Motivo: se refere a porta de acesso que pode estar vencida.
- Contatar o Suporte de Manutenção de Redes e Servidores da IXC Soft, para que o técnico reabilite a porta e os títulos voltem a comunicar.
O Valor XXX é maior que o máximo 330
- Motivo: Ocorre quando nas configurações da Carteira de cobrança da Efí está definido um valor de Juros maior do que o permitido pelo banco.
- Acessar as configurações de Juros de sua carteira de cobrança e corrigir o percentual de juros, não ultrapassando 0.033%, que é o máximo permitido pela legislação. Para saber como, acesse Juros, Multas e Desconto.
A propriedade (
expire_at) informada é inválida.
- Motivo: Ocorre devido ao título de cobrança ter passado do vencimento sem ter sido previamente registrado. Não é possível registrar um boleto já vencido ou emitido com data de vencimento retroativa.
- Cancelar este título no Sistema (ou renegociar), gerando um novo título de cobrança em substituição, com data de vencimento igual ou maior que a atual.
Limite de emissões diárias excedido. Por favor, solicite que o recebedor entre em contato com o suporte Gerencianet.
- Motivo: Ocorre quando o limite de emissões diárias é ultrapassado.
- Valide em seu Sistema se não há mais de um cadastro de cliente com CPF, Telefone ou E-mail repetido. Caso não encontre, entre em contato com o Suporte Efí para ajustar o limite de emissões diárias.
Tipo inválido: number (esperado integer).
- Motivo: Ocorre quando as configurações de Juros e Multa da carteira de cobrança estão ambas preenchidas (% e R$).
- Acesse a configuração de Juros e Multa de sua carteira de cobrança e corrija as informações, deixando apenas uma das opções: juros em % ou em R$.
Falha ao cadastrar Webhook. Bad request
- Motivo: Este erro ocorre quando a carteira de cobrança é Pix e há um problema de configuração no servidor.
- Solicite à equipe de Suporte Instalação da IXC Soft que ajuste o NGINX. Verifique também se houve alteração na chave Pix. Persistindo o problema, contate o Suporte Efí.
Falha ao cadastrar Webhook. Endpoint request timed out
- Motivo: Ocorre quando o certificado Pix está desativado na conta Efí.
- Gere um novo certificado PIX na conta do Gerencianet e substitua o antigo. Veja como gerar um novo certificado no tópico Criar Certificado Digital API Pix Efí Bank.
Tipo inválido: null (esperado array).
- Motivo: Este erro ocorre devido à falta de informações obrigatórias em uma operação.
- Revise os dados enviados e assegure-se de que todas as informações estejam presentes. Persistindo, contate o suporte.
A data do desconto condicional deve ser maior do que a data de emissão, e menor ou igual ao vencimento.
- Motivo: A data configurada para o desconto condicional está fora dos limites permitidos.
- Altere a data de vencimento do boleto para uma data futura e ajuste a data do desconto condicional conforme os critérios.
Erro ao mudar o status do boleto para Cancelado no GerenciaNet: cURL error 6: Could not resolve host:
api.gerencianet.com.br
- Motivo: Este erro ocorre quando não é possível resolver o nome do host, possivelmente por instabilidade na Efí ou problemas de DNS no servidor do cliente.
- Verifique com a Efí sobre instabilidades. Se não houver, investigue possíveis problemas de DNS no servidor. Contate o suporte se necessário.
Transação não processada por conter incoerência nos dados cadastrais.
- Motivo: Erro por divergências entre CPF e razão social cadastrada.
- Verifique se o CPF corresponde à razão social e corrija discrepâncias. Se persistir, contate o suporte.
Não foi possível finalizar sua solicitação. Por favor, entre em contato com o suporte Gerencianet.
- Motivo: Necessidade de atualização cadastral da empresa junto ao banco.
- Oriente o cliente a entrar em contato com o suporte Efí para atualização cadastral.
Falha ao gerar cobrança PIX. O documento desta conta tem bloqueios que impedem essa operação.
- Motivo: Documento da conta bloqueado por pendência cadastral junto ao banco.
- Contate o suporte Efí para regularizar a situação e permitir a geração de cobranças Pix.
Falha ao gerar cobrança PIX. json_encode error:
Malformed UTF-8 characters, possibly incorrectly encoded
- Motivo: Caracteres malformados ou observação do boleto muito longa.
- Revise os dados e remova caracteres especiais ou reduza a observação do boleto. Tente novamente.
A string não corresponde ao modelo:
^https?://.+
- Motivo: A URL de call-back fornecida está fora do padrão esperado.
- Corrija a URL para começar com http:// ou https:// e tente novamente. Se necessário, contate o suporte.
Falha ao gerar cobrança PIX. Valores ou tipos de campo inválidos
- Motivo: Dados obrigatórios incompletos ou inconsistentes, como CPF ou CNPJ inválidos.
- Revise os dados cadastrais do cliente, especialmente CPF, CNPJ e campos obrigatórios. Se persistir, contate o suporte.
Falha ao gerar cobrança PIX. Authentication certificate expired on
AAAA-MM-DD HH:MM:SS
- Motivo: Certificado de autenticação PIX expirado.
- Gere novo certificado PIX na conta Efí e substitua o antigo. Veja como no tópico Criar Certificado Digital API Pix Efí Bank.
Necessário configuração de webhook. Entre em contato com o suporte.
- Motivo: Ausência do arquivo webhook_pix.p.php no servidor do cliente.
- Solicite ao Suporte Instalação da IXC Soft que verifique e configure corretamente esse arquivo.
A string não corresponde ao modelo:
^[^<>]+$
- Motivo: Nome de itens de cobrança contém caracteres proibidos (< ou >).
- Remova os símbolos < e > dos nomes dos produtos e tente novamente. Se persistir, contate o suporte.
Boleto id: 0000 Propriedade:
"/payment/banking_billet/configurations/fine". Tipo inválido: number (esperado integer)
- Motivo: Valores de juros e multa na carteira de cobrança diferentes de
0.033%e2%
- Acesse as configurações da carteira de cobrança e corrija os valores de Juros/Multa.
Boleto id: 0000 Propriedade:
"/metadata/notification_url". A string não corresponde ao modelo:^https?://.+.
- Motivo: Problemas na URL call-back da carteira de cobrança, geralmente por ela não ter sido gerada.
- Acesse a carteira de cobrança e gere uma nova URL call-back.
a:3:{s:4:"code";i:0;s:7:"message";s:7057:"<!DOCTYPE html><html lang="en-US">
- Motivo: Rotas de comunicação à API da Efí atingiram o limite de consumo.
- Contate o suporte da Efí Banik para validação e correção.
API Banco do Brasil
Erros conhecidos
Boleto id: 0000 Application key is not allowed to call this resource method
- Motivo: Possível alteração nas credenciais de API da sua instituição financeira.
- Validar e corrigir as informações de credencial na conta financeira.
API Banco Santander
Erros conhecidos
Boleto id: 0000 Erro ao comunicar cobrança, Bad Request Chave enderecamento dict nao localizada no diretorio de identificadores de conta transacional
- Motivo: Erro ao comunicar por conta de alteração na chave Pix da conta bancária de emissão da cobrança.
- Validar a nova chave Pix vinculada à conta, e inseri-la nas configurações da carteira de cobrança para ser possível comunicar novamente.
Erro ao comunicar cobrança, Bad Request O campo payer.adress permite somente valores alfa numéricos e
.,-ºª
- Motivo: Endereço inserido fora dos padrões de formatação para seu campo, nas informações de contato no cadastro do cliente.
- Acesse o cadastro do cliente e corrija as informações de endereço na aba Contato, atente-se a espaços indevidos ou inserção de caracteres especiais.
API Banco Sicoob
Erros conhecidos
A api retornou o seguinte erro: invalid client credentials. Sicoob retornou: invalid_client - invalid client credentials
- Motivo: Erro nas credenciais da API Banco Sicoob, quando o número do convênio não está habilitado para a utilização da API de cobrança híbrida.
- Acessar as configurações da aplicação de API no portal developers Sicoob e se certificar de habilitar os escopos corretos da API, além disso, validar com o gerente de contas do banco para habilitar o convênio a este tipo de emissão.
Boleto id: 0000 Sicoob retornou: O número do contrato deve ser o mesmo número do cliente. (Code) 5002
- Motivo: Instabilidade ocorrendo com o servidor de API do Banco no momento em que a comunicação ou impressão está sendo realizada.
- Aguardar até que os serviços de comunicação do Banco voltem à normalidade e refazer o procedimento.
Boleto id: 0000 Sicoob retornou: O payload da requisição é inválido. (Code) 0004
- Motivo: Ocorre devido à inserção de espaços indevidos ou caracteres especiais nos campos de instrução, nas configurações da carteira de cobrança.
- Acesse as configurações da carteira de cobrança, vá até a aba Instruções e remova caracteres especiais e espaços indevidos, seja entre palavras ou entre linhas de instrução.
Nosso número já existe
- Motivo: Em determinadas circunstâncias, instabilidades na comunicação entre o sistema e a API ou gateway do banco podem comprometer o processo de registro de boletos. O procedimento padrão consiste na emissão de uma solicitação de registro do boleto pelo IXC ao banco parceiro. Após a realização do registro, o banco envia de volta ao sistema os dados de cobrança. Em situações de interrupção ou instabilidade na comunicação, esse retorno pode não ser recebido corretamente pelo sistema, mesmo que o banco tenha processado o registro com sucesso. Nessas condições, ao tentar registrar os boletos posteriormente, o sistema insere o boleto com problema na fila de processamento. No entanto, devido ao fato de o banco já ter efetuado o registro prévio, o reprocessamento resulta em uma falha (Nosso número já existe), impedindo a conclusão do procedimento.
- Para resolver essa situação, é necessário que o boleto com falha seja renegociado ou cancelado, possibilitando a geração de uma nova cobrança no sistema. Com isso, será possível realizar um novo envio para registro ao banco.
Could not open PKCS12 file
- Motivo: Erro retornado devido a validade do Certificado A1 ter expirado.
- Para corrigir, renove a licença de seu Certificado digital A1. Caso não renove o mesmo certificado e um novo seja adquirido, é necessário inserir o novo arquivo tanto nas configurações do Sistema, como na aplicação de API acessada pelo site Developers Sicoob.
Erro: A api retornou o seguinte erro: error reading PKCS12 file ‘/var/www/’**
- Motivo: Erro apresentado quando o arquivo do Certificado Digital A1 inserido na aplicação da API não corresponde ao mesmo que está inserido em seu Sistema.
- Corrija inserindo o mesmo arquivo de Certificado Digital A1 tanto em seu Sistema como na aplicação da API, no ambiente Developers Sicoob. O certificado em ambos os locais devem ser iguais para que o Sistema comunique corretamente com a API bancária.
Sicoob retornou: Client error:
POST https://api.sicoob.com.br/cobranca-bancaria/v3/boletosresulted in a401 Unauthorizedresponse: "httpCode":"401","httpMessage":"Unauthorized","moreInformation":"Cannot pass the security checks that are required by t (truncated...)
- Motivo: API bancária retorna que a ação solicitada não é autorizada
- Validar aplicação de API no ambiente Developers Sicoob, de modo a garantir que os escopos corretos estejam selecionados e a comunicação de novos boletos ocorra normalmente.
API Banco Sicredi
Erros conhecidos
Erro de Requisição Inválida
- Motivo: Ocorre quando há inconsistência nos dados cadastrais do cliente em sistema (nome, e-mail, telefone, endereço, etc).
- Vá ao cadastro do cliente no Sistema, e valide os dados cadastrais inseridos na aba principal e na aba de Contato.
API retornou: Negócio: Hibrido não contratado. Favor solicitar a contratação
- Motivo: Erro geralmente retornado na homologação de novas carteiras de cobrança. Ocorre quando o convênio utilizado para a emissão de cobranças não está habilitado para a emissão do boleto híbrido.
- Para ajustar, contate o gerente de contas do banco e solicite para ser habilitado a emissão da cobrança híbrida em seu convênio.
Considerações Finais
Entender e saber lidar com os erros mais comuns na comunicação e impressão de cobranças é fundamental para que as operações financeiras da empresa funcionem de forma eficiente e confiável. Seguindo as dicas e orientações deste texto, as pessoas que trabalham com essas tarefas ficarão mais preparadas para identificar, evitar e resolver problemas, evitando prejuízos e tornando o processo de emissão de boletos mais tranquilo.
Vale lembrar que a tecnologia e as regras dos bancos mudam sempre. Por isso, é importante manter-se atualizado e fazer treinamentos com a equipe de tempos em tempos. Assim, o trabalho fica mais fácil, sem muitos erros, e tudo funciona melhor.
Etiquetas
CarteiraDeCobranca Financeiro ContasAReceber LogsGateway Pix Api Efi PixAvulso Bolix