# Integração Bancária API Sicoob
Este documento detalha as funcionalidades da integração bancária via API Sicoob no Sistema, seu funcionamento e o processo de integração/homologação.

> [!NOTE] Requisitos Importantes
> - **Sistema operacional Debian 10**.
> - Para a homologação de uma carteira API o **indicado** é abrir um novo convênio de conta bancária. Caso deseje utilizar um que já esteja em uso no Sistema e/ou que já tenha boletos emitidos por ele, deve estar ciente de que podem ocorrer divergências nos relatórios provenientes de arquivos de retorno.  
Entre as divergências estão: Informação de Título não encontrado nos processamentos de retorno (quem se referem a títulos da carteira de API), liquidações atreladas a boletos divergentes, etc.
> - **Além disso, após a homologação de sua carteira de API, é crucial evitar a geração de novos boletos pela antiga carteira de remessa/retorno, que utiliza o mesmo convênio**.

## Funcionalidades Principais
A integração da API bancária do banco Sicoob na versão 3 dispõe de uma nova tecnologia, onde é possível gerar um boleto híbrido, e o cliente tem a opção de pagar pelo código de barras (linha digitável) ou via QR Code Pix.

## Funcionamento no Sistema
A integração da API Sicoob no Sistema IXC funciona da seguinte forma:

1. **Autenticação**: 
    * O sistema utiliza as credenciais fornecidas pelo Sicoob para autenticar e acessar a API.
3. **Sincronização de Dados**: 
    - O Sistema envia informações de cobrança para o Sicoob.
    - Recebe atualizações sobre o status dos boletos e pagamentos.
4. **Processamento Automático**: 
    - Baixas de pagamentos são processadas automaticamente.
5. **Interface de Usuário**: 
    - Os usuários podem gerenciar boletos e visualizar informações diretamente no Sistema.

## Processo de Integração e Homologação
Para realizar a integração e homologação da API Sicoob no Sistema, siga estes passos:

### Preparação
- Solicite um atendimento junto ao Suporte Financeiro, para ser realizada a configuração.

> [!TIP] Parceria!
> Agora a **IXC Soft** e o **Sicoob** são oficialmente **parceiros**, com isso não existem mais custos para integrar sua API ao Sistema.

### Homologação
### Passo a passo para obter o Client_ID:
> [!INFO] Informação!
> Para a homologação da carteira de API do Sicoob você também precisa gerar o Client_ID, que se trata da aplicação da API no site Developers do Sicoob:

1. Acesse o [Developers Sicoob](https://developers.sicoob.com.br/) e faça o login em sua conta.
2. Acesse o menu **Meus Aplicativos**, clique em **Novo Aplicativo** digite um nome para a sua aplicação (a Descrição é opcional), em seguida clique em **Prosseguir**.
3. No parâmetro **A integração será por uma empresa parceira**, marque como **Sim**.
4. Agora em **Empresa parceira**, localize na lista e selecione **IXC Soft SA**, e clique em **Prosseguir**.
5. Agora na tela de APIs, selecione a seguinte opção:
```
Cobrança Bancária V3
```
6. Clique em **Prosseguir**.
7. Feito isso, o aplicativo estará criado e com o Status **Pendente**, então é necessário aprovar a sua criação em seu **internet banking** para que ele adote o Status **Ativo**.
8. Após ativação do aplicativo, novamente no ambiente developers do banco, acesse seu aplicativo e copie a informação **Client ID**.
9. Fim.

Por motivos de segurança, caso a criação da aplicação de **API Sicoob** não seja concluída em menos de 3 minutos ela será invalidada, necessitando que o processo de criação seja reiniciado.

### Ativando a Aplicação
Após a conclusão do processo de criação da Credencial de API, o aplicativo estará disponível no menu **Meus Aplicativos** com o status de **Pendente**.  

Para ativar os aplicativos PJ, será necessário que os responsáveis pela conta **autorizem no Sicoobnet Empresarial**. Basta acessar o ícone de pesquisa, procure por **Transações Pendentes / Detalhamento** e, em seguida, por **Autorização para Uso de APIs** Insira sua senha e autorize.  

O aplicativo será atualizado para o status **Ativo**, e as credenciais estarão prontas para uso.

> [!SUCCESS] Credenciais API Finalizadas!
> Feito isso, junto com os seus outros dados bancários, o atendente da IXC Soft poderá prosseguir com a homologação da sua carteira de cobrança de API.

> [!CAUTION] Migração API Sicoob V2 para V3!
> Caso já utilize uma carteira de cobrança em seu Sistema com a versão V2 da API Sicoob, é necessário que seja atualizada para a V3, por motivo de descontinuamento.<hr>
>
> **Para o processo de migração, você deve:**
> - Acessar o Portal Developers do Sicoob.
> - Deletar a antiga aplicação V2.
> - Criar uma nova aplicação V3 conforme os passos acima (importante NÃO marcar o escopo "webhook").
> - Vincular a nova credencial da V3 gerada em sua carteira de cobrança.

### Criando a Carteira
1. Acesse o menu **Sistema**.
2. Pasta **Financeiro**.
3. E clique em **Carteira de cobrança**.
4. Clique em **Novo**.
5. Na primeira aba chamada **Carteira de cobrança**, você fará as seguintes configurações:
- **Descrição:** Aqui você irá definir a nomeação da carteira.
- **Conta:** Aqui você irá criar a conta, responsável por armazenar seus dados bancários.  
- **Tipo de recebimento:** Neste campo você deve selecionar a opção **Gateway.**
- **Enviar e-mail para cliente ao gerar:** Marcar como **Não**, pois torna obrigatório o e-mail de cadastro do cliente e envia automaticamente a fatura do cliente, fazendo assim o registro da mesma no banco (sendo assim, não é recomendado o uso).
- **Validar filial na venda:** Marcar como **Sim.**
- **Planejamento analítico:** utilize o padrão **240**, ou cadastre um novo.

### Criando a Conta
- **Conta:** Defina o nome para a conta.
- **Tipo da Conta:** Marque a opção **Banco.**
- **Data de abertura:** Informe o dia 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 será criada esta **Conta** e a **Carteira.** 

Na aba seguinte **Banco:**
- **Banco:** Selecione o ID da instituição, conforme o cadastro nacional de Bancos, neste caso é o: 
    - **756 - Banco Cooperativo do Brasil S.A.- BANCO**
- **Agência:** Número da sua agência bancária.
- **Dígito verificador da agência:** Insira o dígito verificador que fica após o número da agência.
- **Número da conta:** Número da sua conta bancária.
- **Dígito verificador da conta:** Informe o dígito verificador de sua conta bancária.

### Configurações Gateway
- **Gateway:** Selecione o **Sicoob API**.
- **Versão da API:** Selecionar a **V3**.
- **Importado gateway:** Selecione **Não.**
- **Client_Id:** informe o código que você gerou no Developers Sicoob.
- **Limite de pagamento após o vencimento (dias)**: O campo deve ser preenchido com a quantidade de dias em que é possível pagar o título após o vencimento (esta é uma configuração de sua conta bancária, e pode ser consultada com o seu Gerente de Conta do Banco).
- **Envia e-mail Gateways:** Marque como **Não.**
- **Gera pix:** Marque como **Sim**, caso opte pelo boleto híbrido.
- **Tarifas Gateway:** aqui você define o lançamento das tarifas gateway, pois o banco não faz isso de forma automática. 

### Configurações Bancárias
- **"Contador do nosso número:**" Acesse o manual para criação do [[contador do nosso numero|Contador do Nosso Número]].
- **"Número do convênio:**" Informe o número do Convênio, Beneficiário ou Cedente de sua conta bancária.
- **"Títulos com recebimento via Pix:**" Marque como **"Sim".**
- **Contador do nosso número:** Acesse o manual para criação do [[contador do nosso numero|Contador do Nosso Número]].
- **Número do convênio:** Informe o número do Convênio, Beneficiário ou Cedente de sua conta bancária.
- **Títulos com recebimento via pix:** Marque como **Sim.**

### Juros/Multas/Desconto
> [!WARNING] Aviso!
> Sicoob API Não aceita os Juros em Reais (R$).

- **Juros pagamento via boleto:** Valor padrão (máximo permitido por lei, acima é caracterizado juros abusivo), configure **1,00.**
- **Juros %:** Valor padrão (máximo permitido por lei, acima é caracterizado juros abusivo), configure 0.033%.
- **Multa %:** Valor padrão (máximo permitido por lei, acima é caracterizado multa abusiva), configure 2%.
- **Desconto até o vencimento R$:** Insira um valor em **Reais** para conceder desconto na fatura, se paga até a data do vencimento.
- **Desconto até o vencimento %:** Insira um valor em **Porcentagem** para conceder desconto na fatura, se paga até a data do vencimento.
- **Desconto parcela proporcional:** Habilite, caso queira conceder o desconto para parcelas proporcionais também.

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

### Instruções
> [!INFO] Informação:
> * Sicoob API permite o uso de no máximo **5 linhas de instrução**.
> * Com no máximo **40 caracteres por linha**.

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] Aviso!
> 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]].

### Agenda de Tarefas
> [!INFO] Informação!
> Agora, após a configuração da carteira de cobrança, é necessário configurar as tarefas que irão executar as baixas das faturas de forma automática em seu sistema.

Costumamos cadastrar até 4 tarefas de consulta divididas entre as 24h do dia para as carteiras de APIs bancárias, devendo a última rodar o mais próximo da meia-noite.

- Exemplo: 06h50, 12h50, 18h50, 23h50.

Para configurar, acesse:
1. Menu **Ferramentas**.
2. Clique em **Ferramentas**.
3. **Agenda de tarefas**.
4. Botão **Novo**.
5. **Tarefa:** Selecione **Consulta pagamento Sicoob API**.
6. **Minuto (0-59):** Coloque o valor dos minutos, entre 0 e 59 min.
7. **Hora (0-23):** Coloque o valor da hora, entre 0 e 23. Podendo incluir mais horários utilizando a vírgula, exemplo:
8. Horas (0-23): **6,12,18,23**.

> [!DANGER] Perigo!
> Caso desejar um intervalo de consulta reduzido, por exemplo, executar a tarefa a cada 30 minutos, é possível. Porém, sempre é válido ressaltar que corre o **risco de gerar lentidão e possíveis travamentos em seu servidor.**
> Então busque horários em que não vá conflitar com demais tarefas em seu servidor. E busque o seu setor de TI para analisar o impacto em seu servidor.
> Dito isto, para o exemplo de configurar a tarefa a cada 30 minutos, você pode inserir os valores nos campos:
> - **Minuto (0-59):** */30
> - **Hora (0-23):** */1
> - Desta forma, o seu servidor irá executar a tarefa **a cada hora do dia**, com um **intervalo de 30 minutos**.

### Ativação
> [!SUCCESS] Finalizado!
> Concluídos todos os passos anteriores, a carteira e as tarefas de consulta estão finalizadas. Com isso, já pode gerar o boleto de teste para efetuar o pagamento e validar a baixa da fatura no IXC Provedor.
Após efetuada a baixa da fatura de forma automática, a homologação estará finalizada.

## Considerações Finais
> [!TIP] Dica!
> A integração da API Sicoob no sistema IXC oferece uma solução robusta para gerenciamento de cobranças bancárias. É essencial seguir cuidadosamente o processo de integração e manter as credenciais seguras.

Para suporte adicional ou dúvidas, entre em contato com a equipe de suporte da IXC Soft.

## Etiquetas
#ApiSicoob #IXCSystem #BancoSicoob #ApiBancoSicoob #IntegracaoBancaria #ApiBancaria #Sicoob 

## 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 - api|Integrações Bancárias - API]]
* [[public/conceitos/gerais/api banco sicoob|API Banco Sicoob]]
* [[converter o certificado digital|Converter o Certificado Digital]]
* [[como solicitar o pix na central do assinante|Como Solicitar o Pix na Central do Assinante]]
* **Manual Sicoob API V2**: https://drive.google.com/file/d/1bVmsqqWLiRRuvc9TQQjJ53u1dATZNqr7/view
* **Manual Sicoob API V3**: https://documenter.getpostman.com/view/20565799/2sA3QqfsDi#406b25ed-dddd-45f8-a0f8-509b6f969352