# 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, utiliza uma nova tecnologia que permite gerar boletos híbridos. Assim, o cliente pode escolher pagar por código de barras (linha digitável) ou pelo QR Code Pix.

## Funcionamento no sistema

A integração da API Sicoob no sistema IXC funciona da seguinte forma:

1. **Autenticação:**  
    * O sistema usa as credenciais fornecidas pelo Sicoob para autenticar e acessar a API.  
2. **Sincronização de dados:**  
    - O sistema envia as informações de cobrança ao Sicoob.  
    - Recebe atualizações sobre o status dos boletos e pagamentos.  
3. **Processamento automático:**  
    - Os pagamentos são baixados automaticamente no sistema.  
4. **Interface de usuário:**  
    - Os usuários podem gerenciar boletos e visualizar as 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 os passos abaixo:

### Preparação

- Solicite atendimento ao Suporte Financeiro para realizar a configuração.

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

### Homologação

### Passo a passo para obter o Client_ID

> [!INFO] Informação!  
> Para homologar a carteira da API Sicoob, será necessário gerar o Client_ID por meio da criação da aplicação da API no site Developers do Sicoob:

1. Acesse o [Developers Sicoob](https://developers.sicoob.com.br/) e faça login na sua conta.  
2. Vá ao menu **Meus Aplicativos**, clique em **Novo Aplicativo**, dê um nome para a aplicação (a descrição é opcional) e clique em **Prosseguir**.  
3. Em **A integração será por uma empresa parceira**, selecione **Sim**.  
4. Em **Empresa parceira**, escolha **IXC Soft SA** e clique em **Prosseguir**.  
5. Na tela de APIs, selecione:
```
Cobrança Bancária V3
```
6. Clique em **Prosseguir**.  
7. A aplicação será criada com o status **Pendente**. Acesse seu **internet banking** para aprová-la e alterar o status para **Ativo**.  
8. Após a ativação, acesse o ambiente developers novamente e copie o **Client ID** da sua aplicação.  
9. Fim.

Por questões de segurança, se a criação da aplicação não for concluída em até 3 minutos, ela será invalidada, sendo necessário reiniciar o processo.

### Ativando a aplicação

Depois de criar a credencial da API, o aplicativo estará em **Meus Aplicativos** com status **Pendente**.

Para ativar a aplicação PJ, é necessário que os responsáveis pela conta autorizem no **Sicoobnet Empresarial**. Vá até a opção de pesquisa, procure por **Transações Pendentes / Detalhamento** e selecione **Autorização para Uso de APIs**. Em seguida, insira a senha e aprove.

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

> [!SUCCESS] Credenciais API Finalizadas!  
> Após isso, com os demais dados bancários, o atendente da IXC Soft poderá dar continuidade à homologação da carteira de cobrança com API.

> [!CAUTION] Migração API Sicoob V2 para V3!  
> Caso tenha uma carteira com a versão V2 da API Sicoob, ela deve ser atualizada para a V3 devido à descontinuação.  
>
> **Para migrar, siga os passos abaixo:**  
> - Acesse o portal Developers do Sicoob.  
> - Exclua a aplicação da versão V2.  
> - Crie uma nova aplicação V3 conforme os passos descritos (não marque o escopo "webhook").  
> - Vincule a nova credencial V3 à sua carteira de cobrança.

### Criando a carteira

1. Acesse o menu **Sistema**.  
2. Vá até a pasta **Financeiro**.  
3. Clique em **Carteira de cobrança**.  
4. Clique em **Novo**.  
5. Configure os campos na aba **Carteira de cobrança**:  
- **Descrição:** Defina o nome da carteira.  
- **Conta:** Crie a conta que armazenará os dados bancários.  
- **Tipo de recebimento:** Selecione **Gateway.**  
- **Enviar e-mail para cliente ao gerar:** Marque como **Não**, pois esse campo torna obrigatório o e-mail do cliente e envia a fatura automaticamente, registrando-a no banco (não recomendado).  
- **Validar filial na venda:** Marque como **Sim.**  
- **Planejamento analítico:** Utilize o código **240**, ou crie um novo.

### Criando a conta

- **Conta:** Dê um nome à conta.  
- **Tipo da Conta:** Selecione **Banco.**  
- **Data de abertura:** Informe a data atual da configuração.  
- **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:** Escolha o ID:  
   - **756 - Banco Cooperativo do Brasil S.A.- BANCO**  
- **Agência:** Informe o número da sua agência.  
- **Dígito verificador da agência:** Preencha com o dígito após o número da agência.  
- **Número da conta:** Preencha com o número da conta bancária.  
- **Dígito verificador da conta:** Informe o dígito da conta.

### Configurações gateway

- **Gateway:** Selecione o **Sicoob API**.  
- **Versão da API:** Selecione **V3**.  
- **Importado gateway:** Marque **Não.**  
- **Client_Id:** Informe o código gerado no portal Developers Sicoob.  
- **Limite de pagamento após o vencimento (dias):** Configure conforme a definição da sua conta bancária (verifique com seu gerente).  
- **Envia e-mail Gateways:** Marque **Não.**  
- **Gera pix:** Marque **Sim**, se desejar gerar boletos híbridos.  
- **Tarifas Gateway:** Defina o lançamento das tarifas manualmente, pois o banco não faz isso automaticamente.

### Configurações bancárias

- **Contador do nosso número:** Acesse o manual de [[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 da sua conta.  
- **Títulos com recebimento via pix:** Marque como **Sim.**

### Juros/Multas/Desconto

> [!WARNING] Aviso!  
> A API do Sicoob não aceita valores de juros em **Reais (R$).**

- **Juros pagamento via boleto:** Configure o valor padrão como **1,00.**  
- **Juros %:** Use o valor padrão de 0.033%.  
- **Multa %:** Defina o valor padrão de 2%.  
- **Desconto até o vencimento R$:** Informe o valor do desconto em **Reais**.  
- **Desconto até o vencimento %:** Informe o valor do desconto em **Porcentagem**.  
- **Desconto parcela proporcional:** Ative se quiser aplicar o desconto proporcional.

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

### Instruções

> [!INFO] Informação:  
> * A API do Sicoob permite até **5 linhas de instrução**.  
> * Cada linha pode ter até **40 caracteres**.

Remova as aspas das hashtags nas instruções a seguir:

- **Instrução 1:**  
```
Após vencimento juros R$ #juro# ao dia.
```

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

> [!WARNING] Aviso!  
> Se adicionar mais linhas, insira também as variáveis de leitura das instruções no campo **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 modelo padrão **3 por página.**

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

### Agenda de tarefas

> [!INFO] Informação!  
> Após configurar a carteira de cobrança, é necessário agendar tarefas que farão a baixa automática das faturas.

Recomenda-se cadastrar até quatro tarefas por dia, sendo a última próxima à meia-noite.  
- Exemplo: 06h50, 12h50, 18h50 e 23h50.

Para configurar:

1. Acesse o menu **Ferramentas**.  
2. Clique em **Ferramentas**.  
3. Acesse **Agenda de tarefas**.  
4. Clique no botão **Novo**.  
5. Em **Tarefa**, escolha **Consulta pagamento Sicoob API**.  
6. **Minuto (0-59):** Insira o minuto (ex: 50).  
7. **Hora (0-23):** Insira a hora ou múltiplas horas separadas por vírgula.  
8. Exemplo: **6,12,18,23**.

> [!WARNING] Aviso!  
> Caso utilize o Webhook da API Sicoob, cadastrar apenas 1 horário de tarefa para executar diariamente, como uma tarefa para a confirmação de recebimento.
> 
> Para mais informações, verifique em [[tarefa - consulta de pagamento sicoob api|Tarefa - Consulta de Pagamento Sicoob API]].

### Ativação

> [!SUCCESS] Finalizado!  
> Após concluir todos os passos, a carteira e as tarefas de consulta estarão ativas. Agora, você pode gerar um boleto de teste, realizar o pagamento e verificar se a fatura será baixada automaticamente no IXC Provedor.  
Uma vez confirmada a baixa automática, a homologação estará finalizada.

## Considerações finais

A integração da API Sicoob com o sistema IXC oferece uma solução eficiente para o gerenciamento de cobranças bancárias. É fundamental seguir corretamente as etapas de configuração e manter suas credenciais seguras para garantir o funcionamento da integração.

## 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/guias tutoriais/carteira de cobranca/integracoes carteira de cobranca/integracoes bancarias - api/integracoes/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