Central de Ajuda

Leitura de 9 min

Integração bancária API Sicoob

Este documento apresenta as funcionalidades da integração bancária via API Sicoob no sistema, explicando seu funcionamento e o processo de integração e homologação.

Requisitos importantes

  • Sistema operacional Debian 10.
  • Para homologar uma carteira API, é recomendado abrir um novo convênio de conta bancária. Se optar por utilizar um convênio já em uso no sistema e/ou com boletos emitidos, é importante estar ciente de que podem surgir divergências nos relatórios gerados pelos arquivos de retorno. Essas divergências podem incluir mensagens de título não encontradas nos processamentos de retorno (relativas a títulos da carteira de API) e liquidações associadas a boletos incorretos, dentre outras situações.

Após a homologação da nova carteira API, é fundamental não gerar novos boletos pela antiga carteira de remessa/retorno que utilize o mesmo convênio.

Parceria!

Agora a IXC Soft e o Sicoob são oficialmente parceiros, e não há mais custos para integrar sua API ao sistema.

Funcionalidades principais

A integração com a API bancária do banco Sicoob, na versão API Sicoob V3, utiliza uma tecnologia atualizada que permite gerar boletos híbridos. Dessa forma, o cliente pode escolher entre fazer o pagamento utilizando o código de barras (linha digitável) ou o QR Code Pix.

Melhorias!

Master abril 2025
  1. Implementada a comunicação via Webhook para a API Sicoob V3.
  • Foram realizadas melhorias que possibilitam a comunicação por meio de webhook entre o sistema e o banco, a partir da versão V3 da API Sicoob. Com o webhook, sempre que o banco disponibilizar uma instrução de cobrança (liquidação), automaticamente será enviado o registro de comunicação para o seu sistema. Desta maneira, os pagamentos via Pix ou Boleto serão recebidos no sistema, seguindo o prazo de compensação determinado pelo Banco Central e pelo Sicoob.
  • Mesmo com a utilização do webhook, é essencial manter um horário configurado para a Tarefa - Consulta Pagamento Sicoob API, para garantir que, no dia seguinte, ela seja executada e traga ao sistema quaisquer liquidações que possam ter ficado pendentes.

Consulte Integração Webhook da API Sicoob para mais informações.

Atenção!

A Modificação do método de inserção de logs de liquidação da API Banco Sicoob está presente na versão Beta do sistema. A disponibilidade desta melhoria na versão Estável será a partir de julho de 2025.

Beta - Melhoria na inserção dos logs API Banco Sicoob!

  1. Modificado o método de inserção dos logs de liquidação em Sistema.
  • Na integração com a API do Sicoob, as consultas de pagamento executadas pela tarefa 130 - Consulta de pagamentos Sicoob API anteriormente traziam todas as movimentações de liquidação em um único log gateway, gerando um único registro com múltiplos recebimentos. Agora, a consulta insere logs unitários para cada liquidação disponibilizada pelo banco, facilitando a análise de registros no sistema.

Funcionamento no Sistema

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

  1. Autenticação:
    • O sistema utiliza 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 para o Sicoob.
    • Recebe atualizações sobre o status dos boletos e pagamentos.
  3. Processamento automático:
    • As baixas dos pagamentos são processadas automaticamente.
  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 um atendimento junto ao Suporte Financeiro para que a configuração seja realizada.

Homologação

Passo a passo para obter o Client_ID

Informação!

Para homologar a carteira da API do Sicoob, é necessário gerar o Client_ID, que corresponde à criação de uma aplicação no site Developers do Sicoob:

  1. Acesse o Developers Sicoob e faça login na sua conta.
  2. Acesse o menu Meus Aplicativos, clique em Novo Aplicativo, insira um nome (a descrição é opcional), e clique em Prosseguir.
  3. Em A integração será por uma empresa parceira, marque como Sim.
  4. Em Empresa parceira, selecione IXC Soft SA e clique em Prosseguir.
  5. Na tela de APIs, selecione a opção:
    • Cobrança Bancária V3.
    • Se desejar utilizar o webhook, ao selecionar Cobrança Bancária V3, certifique-se de que todos os escopos de webhook também estejam ativos.
  6. Clique em Prosseguir.
  7. O aplicativo será criado com status Pendente. Para alterá-lo para Ativo, será necessário aprovar a criação no seu Internet banking.
  8. Após ativar, volte ao ambiente developer, acesse seu aplicativo e copie o Client ID.
  9. Fim.

Aviso!

Por segurança, se a criação não for concluída em menos de 3 minutos, será necessário reiniciar o processo.

Ativando a aplicação

Após criar a credencial da API, o aplicativo estará no menu Meus Aplicativos com status Pendente.

Para ativar, os responsáveis pela conta devem autorizar através do Sicoobnet Empresarial:

  • Acesse o ícone de pesquisa, localize Transações Pendentes / Detalhamento e selecione Autorização para Uso de APIs. Em seguida, digite sua senha e confirme.

O aplicativo será atualizado para Ativo, e suas credenciais poderão ser utilizadas.

Credenciais API Finalizadas!

Com isso, junto aos seus outros dados bancários, a equipe de atendimento da IXC Soft poderá dar andamento à homologação da carteira de cobrança com API.

Migração API Sicoob V2 para V3!

Caso você já utilize uma carteira com a versão V2 da API Sicoob, será necessário atualizar para a versão V3 devido à descontinuação.

Para migrar, você deve:

  • Acessar o portal Developers do Sicoob.
  • Excluir a aplicação da versão V2.
  • Criar uma nova aplicação com a versão V3 conforme os passos anteriores (marque o escopo “webhook” se desejar utilizá-lo).
  • Vincular a nova credencial da V3 à carteira existente.

Migração API Sicoob para Webhook

Se você já utiliza uma carteira com comunicação por tarefas, é possível atualizá-la para comunicação via webhook.
O webhook proporciona liquidação imediata com a API bancária, com envio automático das atualizações.

Para atualizar:

  • Edite sua carteira de cobrança no sistema.
  • Na aba “Configurações gateway”, marque “Usar webhook” como Sim e clique em Salvar.
  • Preencha os campos Código beneficiário e Código da cooperativa.
  • Finalize clicando em Salvar.

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. Na aba Carteira de cobrança, configure:
    • Descrição: Defina o nome para a 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 (torna obrigatório o e-mail e envia automaticamente, registrando a fatura no banco).
    • Validar filial na venda: Marque como Sim.
    • Planejamento analítico: Use o padrão 240, ou crie um novo.

Criando a conta

  • Conta: Defina o nome da conta.
  • Tipo da Conta: Escolha Banco.
  • Data de abertura: Use a data atual da configuração.
  • Planejamento analítico: Para mais informações, acesse: Contas Contábeis Analíticas.
  • Filial: Escolha o ID da filial para criar a Conta e a Carteira.

Na aba Banco:

  • Banco: Selecione o código da instituição:
    • 756 - Banco Cooperativo do Brasil S.A.- BANCO
  • Agência: Preencha o número da sua agência.
  • Dígito verificador da agência: Insira o dígito da agência.
  • Número da conta: Informe o número da conta.
  • Dígito verificador da conta: Insira o dígito final da conta.

Configurações gateway

  • Gateway: Escolha Sicoob API.
  • Versão da API: Selecione V3.
  • Importado gateway: Marque como Não.
  • Client_Id: Insira o código gerado no Developers Sicoob.
  • Limite de pagamento após o vencimento (dias): Informe a quantidade de dias permitida pelo banco (verifique com seu gerente).
  • Envia e-mail Gateways: Marque Não.
  • Gera pix: Marque Sim, caso opte pelo boleto híbrido.
  • Tarifas Gateway: Defina o lançamento das tarifas, pois o banco não gera automaticamente.

Webhook!

  • Usar webhook: Marque como Sim se quiser habilitar a comunicação imediata via webhook.
    Após marcar, os seguintes campos serão habilitados:
  • Código do beneficiário: Insira o número do convênio (ou cedente).
  • Código da cooperativa: Informe o número da cooperativa (agência).

Configurações bancárias

  • Contador do nosso número: Acesse o manual: Contador do Nosso Número.
  • Número do convênio: Informe o número do convênio, beneficiário ou cedente.
  • Títulos com recebimento via pix: Marque como Sim.

Juros/Multas/Desconto

  • Juros pagamento via boleto: Configure 1,00.
  • Juros %: Configure 0.033%.
  • Multa %: Configure 2%.
  • Desconto até o vencimento R$: Informe um valor fixo.
  • Desconto até o vencimento %: Informe um percentual.
  • Desconto parcela proporcional: Marque se desejar aplicar o proporcional.

Para mais informações, acesse: Juros, Multas e Desconto.

Aviso!

A API do Sicoob não aceita juros em Reais (R$).

Instruções

  • Instrução 1:
Após vencimento juros R$ #juro# ao dia.
  • Instrução 2:
Após vencimento multa R$ #multa#.

Para mais informações, acesse: Instruções da Carteira de Cobrança.

Aviso!

  • Permitido no máximo 5 linhas de instrução.
  • Com até 40 caracteres por linha.

Se adicionar mais linhas, insira também as variáveis de leitura nos parâmetros Imprimir instruções quando…

Impressão

  • Layout de impressão: Utilize o padrão 3 por página.

Para mais informações, acesse: Layouts de Impressão.

Agenda de tarefas

Agora que a carteira está configurada, é necessário criar as tarefas de consulta automática. Recomenda-se até 4 tarefas diárias, distribuídas ao longo do dia.

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

Tarefa consulta de pagamentos

Configurando:

  1. Vá até o menu Ferramentas.
  2. Clique em Ferramentas.
  3. Acesse Agenda de tarefas.
  4. Clique em Novo.
  5. Em Tarefa, selecione Consulta pagamento Sicoob API.
  6. Minuto (0-59): Defina o valor, por exemplo, 50.
  7. Hora (0-23): Insira o(s) horário(s), como 6,12,18,23.

Para mais informações, acesse: Tarefa - Consulta de Pagamento Sicoob API.

Aviso!

  • Essa configuração só deve ser feita caso não esteja utilizando o webhook.

Caso esteja utilizando o webhook, a tarefa deve ser executada uma vez ao dia, de preferência às 01:00. Assim, ela funcionará como uma confirmação de baixa de pagamentos, atualizando as liquidações no Sistema para garantir que todas as pendências do dia anterior sejam resolvidas.

Finalizado!

Após configurar a carteira e as tarefas, é possível gerar um boleto de teste, efetuar o pagamento e verificar se a baixa é feita automaticamente no sistema.
Com a baixa automática confirmada, a homologação estará concluída.

Considerações finais

A integração da API Sicoob com o sistema IXC é uma solução prática e eficiente para controle de cobranças bancárias. Seguir todas as etapas corretamente e manter as credenciais seguras é essencial para garantir o bom funcionamento da integração.

Etiquetas

ApiSicoob IXCSystem BancoSicoob ApiBancoSicoob IntegracaoBancaria ApiBancaria Sicoob

Leia Também

Visão de gráfico

Páginas relacionadas