# Integração Bancária Iugu  

Este documento apresenta instruções detalhadas sobre a integração e o uso do Gateway Iugu. O **Gateway** melhora o fluxo de cobranças e permite a utilização do boleto híbrido (boleto com Pix), além de possibilitar o registro direto pelo Sistema e o recebimento automático, sem necessidade de gerar ou processar arquivos bancários de remessa e retorno.  

> [!NOTE] Requisitos Importantes  
> - **Sistema operacional Debian 10**.  
> - Para homologar uma carteira Gateway, o **recomendado** é abrir um novo convênio de conta bancária. Caso deseje usar uma conta já cadastrada no IXC e que já possui boletos emitidos, é importante estar ciente de que pode haver divergências nos relatórios gerados a partir dos arquivos de retorno.  
Entre essas divergências, podem ocorrer: falha na identificação de títulos no processamento de retorno (relacionados à carteira de Gateway), baixas vinculadas a boletos divergentes, entre outros casos.  

## Objetivos da Integração  
- Ampliar as opções de integração do Sistema.  
- Atender aos clientes que buscam compatibilidade da Iugu com o Sistema.  
- Permitir a emissão automática de boletos híbridos e o processamento integrado da baixa de pagamentos.  
- Oferecer mais uma alternativa de integração para os clientes, aumentando a flexibilidade na escolha de soluções financeiras.  

## Benefícios da Integração  
Além de permitir o recebimento imediato de cobranças no Sistema através do pagamento via Pix, a integração oferece outras vantagens:  

**1. Automação de Processos**  
- **Emissão e registro automático:** os boletos híbridos serão gerados e registrados automaticamente pelo Gateway, reduzindo a necessidade de ações manuais.  
- **Baixa automática de pagamentos:** os pagamentos serão baixados diretamente no Sistema, garantindo mais precisão e economia de tempo.  

**2. Economia e Eficiência**  
- **Redução de custos:** com tarifas competitivas da Iugu, os clientes economizam em transações financeiras usando uma solução integrada.  
- **Centralização de operações:** permite gerenciar boletos e pagamentos em uma única plataforma, evitando o uso de múltiplos sistemas e fornecedores.  

**3. Melhor Experiência para o Cliente**  
- **Atendimento à demanda:** a integração atende a clientes que já possuem contas na Iugu e desejam continuar utilizando seus serviços dentro do Sistema.  
- **Facilidade de implementação:** foi projetada para ser intuitiva e de rápida adoção, permitindo seu uso imediato.  

**4. Vantagem Competitiva**  
- **Mais atratividade para o Sistema:** com essa integração, a plataforma se torna mais interessante para novos clientes que já utilizam ou desejam utilizar a Iugu.  
- **Maior retenção de clientes:** ao oferecer soluções solicitadas pelos usuários, o Sistema melhora suas taxas de retenção e satisfação.

> [!WARNING] Aviso!
> A Iugu determina internamente a expiração de boletos para 30 dias após o vencimento. Uma fatura com status Expirado indica que o prazo após o vencimento foi excedido, tornando o pagamento impossível, semelhante a uma fatura 'cancelada'. <br>
> Se tiver dúvidas sobre essa configuração, entre em contato com o Suporte Iugu para assistência.

## Processo de Integração e Homologação
Para realizar a integração e homologação do Gateway Iugu no sistema, siga estes passos:

### Homologação
> [!EXAMPLE] Dados bancários necessários para a integração:
>
> **Iugu (Gateway)**
>
> * 1 - Número da agência com dígito?
> * 2 - Número da conta com dígito?
> * 3 - Token?

> [!TIP] Dica!
> Caso tenha dúvida sobre algum dos dados bancários, consulte o(a) Gerente de sua Conta Bancária.

### Passo a Passo para Obter as Credenciais do Gateway  
1. Acesse sua conta Iugu: https://auth.iugu.com/login.  
2. Faça login com sua conta.  
3. No menu lateral, clique em **Configurações** (ícone de engrenagem).  
4. Role a tela até as configurações de Desenvolvedor e selecione **Integração via API**.  
5. Nesta tela, será configurado o **Token** de comunicação da aplicação. Para gerar um novo Token, clique em **Novo**.  
6. Escolha o tipo Produção e insira uma descrição, como "IXC Soft". Em seguida, clique em **Salvar**.  
7. Retornando à tela de **Tokens de API**, será possível visualizar suas aplicações e copiar o Token de produção criado. Cole o código do Token gerado no campo **Token** da carteira criada no IXC.  

> [!WARNING] Aviso!  
> O **Token** poderá ser copiado apenas durante 1 hora após sua criação.  

8. Agora, é necessário configurar a URL para o envio das notificações de pagamento. No menu lateral esquerdo, abaixo da opção **Integração via API**, clique em **Comunicação via Gatilhos**. Em seguida, no canto superior direito, clique no botão **Novo**.  
9. Insira a URL gerada na Carteira de Cobrança no campo **URL** (recomenda-se utilizar um domínio com SSL) e, no campo **Evento**, marque a opção “Todos”. Depois, clique em **Salvar** para concluir a configuração.  
10. Para utilizar o boleto híbrido, que inclui a linha digitável com a opção de Pix QR Code, é necessário ativar na conta o parâmetro de Pix.  

> [!SUCCESS] Credenciais Gateway Finalizadas!  
> Com isso, juntamente com seus demais dados bancários, a equipe de atendimento da IXC Soft poderá prosseguir com a homologação da sua carteira de cobrança de Gateway.  

### Criando a Carteira  
1. Acesse o menu **Sistema**.  
2. Entre na pasta **Financeiro**.  
3. Clique em **Carteira de cobrança**.  
4. Clique em **Novo**.  
5. Na primeira aba, chamada **Carteira de cobrança**, configure os seguintes campos:  
   - **Descrição:** Defina um nome para a carteira.  
   - **Conta:** Crie a conta responsável por armazenar os dados bancários.  
   - **Tipo de recebimento:** Escolha a opção **Gateway**.  
   - **Enviar e-mail para cliente ao gerar:** Selecione **Não**, pois essa opção exige que o cliente tenha e-mail cadastrado e envia automaticamente a fatura ao banco, não sendo recomendada.  
   - **Validar filial na venda:** Selecione **Sim**.  
   - **Planejamento analítico:** Utilize o padrão **240** ou cadastre um novo.  

### Criando a Conta  
- **Conta:** Defina um nome para a conta.  
- **Tipo da Conta:** Marque **Banco**.  
- **Data de abertura:** Informe a data em que está configurando a conta para esta carteira.  
- **Planejamento analítico:** Para mais informações, acesse: [[formulario planejamento analitico|Formulário Planejamento Analítico]].  
- **Filial:** Selecione o ID da filial para a qual a **Conta** e a **Carteira** serão criadas.  

Na aba **Banco**:  
- **Banco:** Selecione "401 - Iugu Instituição de Pagamentos S. A.".  
- **Agência:** Digite o número da agência bancária.  
- **Dígito verificador da agência:** Insira o dígito verificador localizado após o número da agência.  
- **Número da conta:** Informe o número da conta bancária.  
- **Dígito verificador da conta:** Digite o dígito verificador da conta bancária.  

### Configurações Gateway  
- **Gateway:** Selecione **Iugu**.  
- **Ambiente gateway:** Escolha **Produção**.  
- **Token:** Insira o Token gerado na sua conta **Iugu**.  
- **Envia e-mail Gateways:** Selecione **Não**.  
- **Gera Pix:** Escolha **Sim** caso vá utilizar Pix no boleto.  
- **Tarifas Gateway:** Defina o lançamento das tarifas, pois o banco não faz isso automaticamente. Para mais informações, acesse [[tarifas bancarias - gateway, api e pix|Tarifas Bancárias - Gateway, API e Pix]].  

> [!TIP] Dica!  
> Após clicar em **Salvar** a carteira, os campos Webhook ID e Webhook serão preenchidos automaticamente pelo sistema.  

### Juros/Multas/Desconto  
- **Juros %:** Configure 0.033%, respeitando o limite legal.  
- **Multa %:** Configure 2%, limite máximo permitido por lei.  
- **Desconto até o vencimento R$:** Informe um valor fixo em **Reais** para desconto em pagamentos até a data do vencimento.  
- **Desconto até o vencimento %:** Insira um percentual de desconto para pagamentos realizados até o vencimento.  

Para mais informações, acesse: [[juros, multas e desconto|Juros, Multas e Desconto]].

### Instruções
> [!INFO] Informação:
> * Iugu Gateway permite o uso de no máximo **255 caracteres** totais para serem inseridos como linha de instrução na impressão do boleto.  
> * Não tem limite de linhas.

Remova as aspas antes e depois das hashtags abaixo:
- **Instrução 1:** 
```
Após vencimento juros R$ #juro# ao dia.
```

- **Instrução 2:**
```
Após vencimento multa R$ #multa#.
```

> [!WARNING] Atenção!
> Caso adicione mais linhas, também deve inserir a variável de leitura da linha de instrução, nos parâmetros **Imprimir instruções quando..**

Para mais informações, acesse: [[instrucoes da carteira de cobranca|Instruções da Carteira de Cobrança]].

### Impressão
- **Layout de impressão:** Utilize o padrão **3 por página**

Para mais informações, acesse: [[layouts de impressao|Layouts de Impressão]].

## Fluxo de Funcionamento
```mermaid
sequenceDiagram
    participant S as Sistema
    participant Gateway as Gateway Iugu
    participant W as Webhook

    S->>Gateway: Envia requisição (ex: gerar boleto)
    Gateway->>S: Responde com dados do boleto
    Note over Gateway,W: Evento ocorre (ex: pagamento)
    W->>S: Notifica sobre o evento
    S->>Gateway: Confirma recebimento da notificação
```

### Ativação  
> [!SUCCESS] Finalizado!  
> Depois de concluir todos os passos anteriores, a carteira estará pronta. Com isso, já é possível gerar um boleto de teste para realizar o pagamento e verificar a baixa da fatura no Sistema.  
Quando a baixa da fatura for processada automaticamente, a homologação estará concluída.  

## Considerações Finais  
A integração entre a Iugu e o IXC Provedor representa um avanço importante para melhorar o funcionamento dos negócios dos provedores de serviço. Com processos automatizados, redução de custos e suporte às necessidades dos clientes, essa parceria contribui para um gerenciamento financeiro mais eficiente e simples.

## Etiquetas
#IntegracaoBancaria #GatewayBancario #Iugu #GatewayDePagamento #BoletoHibrido #BoletoPix #Pix

## Leia Também
* [[carteira de cobranca|Carteira de Cobrança]]
* [[integracoes bancarias - carteira de cobranca|Integrações Bancárias - Carteira de Cobrança]]
* [[integracoes bancarias - gateway|Integrações Bancárias - Gateway]]
* [[como solicitar o pix na central do assinante|Como Solicitar o Pix na Central do Assinante]]
* [[logs gateway|Logs Gateway]]
* [[como reprocessar logs gateway|Como Reprocessar Logs Gateway]]
* [[localizar pagamentos - logs gateway|Localizar Pagamentos - Logs Gateway]]
* [[logs de rotinas de cobranca gateway|Logs de Rotinas de Cobrança Gateway]]
* [[como imprimir boleto registrado de gateway importado|Como Imprimir Boleto Registrado de Gateway Importado]]
- [[reenvio gatilhos de comunicacao iugu - notificacoes de pagamento|Reenvio Gatilhos de Comunicação Iugu - Notificações de Pagamento]]
* **Manual Gateway Iugu**: https://dev.iugu.com/reference/
* **Status API Iugu**: https://status.iugu.com/