# Erros Comuns na Comunicação para Registro de Boletos de Cobrança Efí Bank

## Introdução
O registro de boletos de cobrança é fundamental para muitas empresas, especialmente quando utilizam o serviço Efí Bank. No entanto, vários erros podem surgir durante o processo de comunicação para registro desses boletos, causando transtornos e atrasos. Este artigo tem como objetivo explorar os erros mais comuns nesse processo, suas causas e possíveis soluções, fornecendo aos usuários do sistema as ferramentas necessárias para identificar, compreender e resolver esses problemas de forma eficiente.

### TIPOS DE ERROS COMUNS

#### Erro de Conexão
Um dos erros mais frequentes é a falha na conexão com o servidor do Efí Bank. Isso pode ocorrer devido a problemas de rede, configurações incorretas ou indisponibilidade temporária do serviço.

**Causas possíveis:**
- Instabilidade na conexão de internet.
- Firewall bloqueando a comunicação.
- Servidor do Efí Bank 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**.

## Descobrindo o Erro
Para corrigir o erro, é importante saber como identificá-lo. Para isso, siga os passos abaixo:

1. Acesse o internet banking da Efí: [https://login.sejaefi.com.br/](https://login.sejaefi.com.br/)
2. Faça login na sua conta.
3. Na conta, localize a barra lateral esquerda e clique no menu **API**.
4. No menu API, clique no botão **Minhas Aplicações**.
5. No menu de **Aplicações**, localize sua aplicação de API e clique no botão com "três pontos" à direita da descrição da aplicação.
6. Nas opções que abrirem, clique em **Detalhar**.
7. Role a página para baixo até encontrar a seção **Histórico de requisições**.
8. Aqui, haverá uma grade com os dados das requisições de registro de cobranças.
9. Localize a cobrança que tentou registrar; ela estará com o Status de **Falha**.
10. À direita, clique no botão com o desenho de uma cobrança, na aba **Ações**, para ver os detalhes da requisição.
11. Na seção **Dados de saída**, no campo **"message"**, haverá uma descrição do motivo que impediu o registro da cobrança.
12. Fim.

Analisando esta mensagem, você saberá como prosseguir para corrigir o problema.

### Fluxo de Processo

```mermaid
graph TD
    A[Início] --> B[Acesse o internet banking da Efí]
    B --> C[Faça login na sua conta]
    C --> D[Clique no menu API na barra lateral esquerda]
    D --> E[Clique no botão Minhas Aplicações]
    E --> F[Localize sua aplicação de API]
    F --> G[Clique no botão com três pontos]
    G --> H[Clique em Detalhar]
    H --> I[Role até a seção Histórico de requisições]
    I --> J[Localize a cobrança com Status de Falha]
    J --> K[Clique no botão de ações à direita]
    K --> L[Veja os detalhes da requisição]
    L --> M[Verifique o campo message na seção Dados de saída]
    M --> N[Fim]

```

## Erros Comuns

### 1.
```
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.
- **Ação**: No Sistema, acessar a aba **Contato** no cadastro do cliente e corrigir o formato do telefone em seus respectivos campos.

### 2.
```
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.
- **Ação**: 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.

### 3.
```
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.
- **Ação**: 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|Juros, Multas e Desconto]].

### 4.
```
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.
- **Ação**: 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.

### 5.
```
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. Por exemplo:
	 - 13 emissões diárias para o mesmo CPF, Telefone ou E-mail
	 - 30 emissões ao mês para o mesmo CPF, Telefone ou E-mail
- **Ação**: 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.

### 6.
```
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$). Ocorrendo esse conflito, não será possível registrar títulos de cobrança.
- **Ação**: 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$.

### 7.
```
Erro
Falha ao cadastrar Webhook. Bad request
Entre em contato com o suporte!
```
- **Motivo**: Este erro ocorre quando a carteira de cobrança é Pix e há um problema de configuração no servidor. Pode ser necessário ajustar o NGINX para corrigir o problema.
- **Ação**: Solicite à equipe de Suporte Instalação da IXC Soft que ajuste o NGINX. Se, após o ajuste, o erro persistir, verifique se não foram realizadas alterações na chave Pix. Caso a chave esteja intacta e o problema continue, entre em contato com o Suporte Efí para assistência adicional.

### 8.
```
Erro
Falha ao cadastrar Webhook. Endpoint request timed out
Entre em contato com o suporte!
```
- **Motivo**: Ocorre quando o certificado Pix está desativado na conta Efí. Isso impede a comunicação adequada com os endpoints necessários para registrar webhooks.
- **Ação**: Gere um novo certificado PIX na conta do Gerencianet e substitua o certificado antigo na configuração da carteira. Veja como gerar um novo certificado no tópico [[criar certificado digital api pix efi bank|Criar Certificado Digital API Pix Efí Bank]].

### 9.
```
Tipo inválido: null (esperado array).
```
- **Motivo**: Este erro ocorre devido à falta de informações necessárias em uma operação, como ao tentar realizar uma venda sem incluir o produto correspondente. A aplicação espera um array com os dados requisitados, mas recebe um valor nulo em vez disso.
- **Ação**: Revise os dados enviados para a operação, assegurando-se de que todas as informações obrigatórias estejam presentes e corretamente organizadas, especialmente aqueles relacionados a produtos em vendas ou transações. Se o problema persistir após a verificação, contate o suporte para assistência adicional.

### 10.
```
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 deve ser maior que a data de emissão e menor ou igual à data de vencimento do boleto. Além disso, ao configurar um desconto para pagamento até a data de vencimento, não é possível registrar um boleto com a data de vencimento igual à data de emissão.
- **Ação**: Altere a data de vencimento do boleto para uma data futura e verifique se a data do desconto condicional atende os critérios mencionados. Após os ajustes, registre e imprima o boleto novamente. Se o problema persistir, entre em contato com o suporte para assistência.

### 11.
```
Erro
Erro ao mudar o status do boleto para Cancelado no GerenciaNet: cURL error 6: Could not resolve host:
api.gerencianet.com.br (see https://curl.haxx.se/libcurl/c/libcurl-errors.html)
```
- **Motivo**: Este erro ocorre quando não é possível resolver o nome do host, possivelmente por instabilidade na Efí ou por problemas relacionados ao DNS no servidor do cliente.
- **Ação**: Primeiro, verifique com a Efí se há alguma instabilidade conhecida nos serviços. Caso não haja, investigue possíveis problemas de configuração no servidor do Sistema, especificamente no DNS. Se necessário, entre em contato com o suporte para assistência adicional.

### 12.
```
Transação não processada por conter incoerência nos dados cadastrais.
```
- **Motivo**: Este erro surge quando há discrepâncias nos dados cadastrais, como divergências entre o CPF e a razão social cadastrada.
- **Ação**: Verifique se o CPF associado à transação corresponde à razão social registrada e confirme que não houve alterações recentes nos dados que possam ter causado a inconsistência. Corrija quaisquer discrepâncias e tente processar a transação novamente. Se o problema continuar, entre em contato com o suporte para mais orientação.

### 13.
```
Não foi possível finalizar sua solicitação. Por favor, entre em contato com o suporte Gerencianet.
```
- **Motivo**: O erro está relacionado à necessidade de atualização cadastral da empresa (provedor) junto ao banco.
- **Ação**: Oriente o cliente a entrar em contato diretamente com o suporte da Efí para resolver questões relacionadas à atualização cadastral. Este procedimento é necessário para garantir que todas as informações estejam atualizadas e corretas junto ao banco, permitindo a finalização da solicitação. Caso o problema persista, o suporte Efí fornecerá as orientações necessárias.

### 14.
```
Erro
Falha ao gerar cobrança PIX. O documento desta conta tem bloqueios que impedem essa operação.
```
- **Motivo**: Este erro ocorre quando o documento da conta está bloqueado, possivelmente devido à necessidade de atualização cadastral da empresa junto ao banco.
- **Ação**: Oriente o cliente a entrar em contato com o suporte da Efí para resolver a questão do bloqueio. A atualização cadastral junto ao banco é necessária para desbloquear o documento e permitir a geração de cobranças Pix. O suporte da Efí fornecerá as instruções e o suporte necessários para regularizar a situação.

### 15.
```
Erro
Falha ao gerar cobrança PIX. json_encode error:
Malformed UTF-8 characters, possibly incorrectly encoded
```
- **Motivo**: Este erro acontece quando há caracteres especiais malformados nos dados, ou quando a observação do boleto é excessivamente longa, causando problemas de codificação UTF-8.
- **Ação**: Revise o cadastro do cliente e remova ou corrija quaisquer caracteres especiais inconsistentes. Também verifique a observação do boleto e reduza seu comprimento, se necessário, para evitar problemas de codificação. Uma vez feitos os ajustes, tente novamente a operação. Se o erro persistir, entre em contato com o suporte para assistência adicional.

### 16.
```
A string não corresponde ao modelo: ^https?://.+.
```
- **Motivo**: Este erro indica que a URL de call-back fornecida não está no formato esperado, o qual deve começar com "http://" ou "https://".
- **Ação**: Revise a URL de call-back para garantir que ela está corretamente formatada seguindo o modelo ^https?://.+. Gere uma nova URL de call-back que atenda ao padrão esperado. Após garantir que a URL está correta, tente novamente a operação. Se o problema continuar, entre em contato com o suporte para assistência adicional.

### 17.
```
Erro
Falha ao gerar cobrança PIX. Valores ou tipos de camp inválidos: Valores ou tipos de campo inválidos
```
- **Motivo**: Este erro ocorre devido à falta de dados ou inconsistências nos dados cadastrais do cliente, como CPF, CNPJ ou outros campos obrigatórios.
- **Ação**: Revise os dados cadastrais do cliente para garantir que todas as informações obrigatórias estejam preenchidas corretamente e sem inconsistências. Verifique especificamente a precisão do CPF, CNPJ e demais campos relevantes. Após corrigir qualquer erro, tente novamente a operação. Se o problema persistir, contate o suporte para assistência adicional.

### 18.
```
Erro
Falha ao gerar cobrança PIX. Authentication certificate expired on AAAA-MM-DD HH:MM:SS
```
- **Motivo**: O erro indica que o certificado de autenticação PIX utilizado expirou na data e hora especificadas.
- **Ação**: Acesse sua conta Efí e gere um novo certificado PIX. Substitua o certificado expirado pelo novo na configuração necessária para restabelecer a funcionalidade de geração de cobranças PIX. Após a substituição, tente novamente a operação. Veja como gerar um novo certificado no tópico [[criar certificado digital api pix efi bank|Criar Certificado Digital API Pix Efí Bank]]. Caso o problema continue, entre em contato com o suporte para assistência.

### 19.
```
Erro
Necessário configuração de webhook. Entre em contato com o suporte.
```
- **Motivo**: Este erro acontece devido à ausência de um arquivo no servidor do cliente, especificamente o arquivo nomeado como webhook_pix.p.php, essencial para a configuração correta do webhook.
- **Ação**: Entrar em contato com o Suporte Instalação e Manutenção de Servidores da IXC Soft para verificar no servidor se o arquivo webhook_pix.p.php está presente e corretamente configurado. Caso o arquivo esteja faltando, coordene com a equipe de instalação para adicionar e configurar o arquivo necessário. Após a verificação e configuração apropriada, tente novamente a operação.

### 20.
```
A string não corresponde ao modelo: ^[^<>]+$.
```
- **Motivo**: Este erro indica que o nome dos itens de cobrança, como no cadastro do produto, contém caracteres proibidos, especificamente os símbolos de menor (<) e maior (>).
- **Ação**: Revise os nomes dos itens de cobrança e remova quaisquer símbolos de menor (<) ou maior (>). Certifique-se de que os nomes dos produtos estejam de acordo com o modelo especificado, sem incluir esses caracteres. Após realizar os ajustes necessários, tente novamente a operação. Se o erro persistir, entre em contato com o suporte para assistência adicional.

## Considerações Finais
Compreender e saber lidar com os erros comuns na comunicação para registro de boletos de cobrança do Efí Bank é essencial para garantir a eficiência e a confiabilidade das operações financeiras de uma empresa. Ao seguir as orientações e práticas apresentadas neste artigo, os usuários estarão mais bem preparados para identificar, prevenir e resolver problemas, minimizando impactos negativos e otimizando o processo de registro de boletos.

É importante lembrar que a tecnologia e os requisitos bancários estão em constante evolução. Portanto, manter-se atualizado com as últimas diretrizes do Efí Bank e realizar treinamentos periódicos para a equipe são estratégias valiosas para garantir um fluxo de trabalho suave e livre de erros.

## Etiquetas
#CarteiraDeCobranca #Financeiro #ContasAReceber #LogsGateway #Pix #Api #Efi #PixAvulso #Bolix

## Leia Também
- [[carteira de cobranca|Carteira de Cobrança]]
- [[integracoes bancarias - carteira de cobranca|Integrações Bancárias - Carteira de Cobrança]]
- [[gateway efi|Gateway Efí]]
- [[efi - pix avulso|Efí - Pix Avulso]]
- [[reenvio de notificacoes gateway efi bank|Reenvio de Notificações Gateway Efí Bank]]
- [[tarifas bancarias - gateway, api e pix|Tarifas Bancárias - Gateway, API e Pix]]
- [[comunicacao com gateway|Comunicação com Gateway]]