Central de Ajuda

Aparência

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:

  1. Verifique a conexão de internet.
  2. Confira as configurações de firewall.
  3. 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í.
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

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% e 2%
    • 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/boletos resulted in a 401 Unauthorized response: "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.

Leia Também ​

Disponibilizado por IXC S.A.

© 2025