Integração bancária API Sicredi
Este documento apresenta as funcionalidades da integração bancária via API Sicredi no sistema, 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 carteira com API, é essencial evitar a geração de novos boletos pela antiga carteira baseada em remessa/retorno que utilize o mesmo convênio.
Funcionalidades principais
A integração bancária com a API Sicredi, na versão V2, possui uma tecnologia que permite a geração de boletos híbridos. Com isso, o cliente pode optar pelo pagamento via código de barras (linha digitável) ou por meio do QR code Pix.
Melhorias!
Master abril 2025
- Implementa a comunicação via Webhook para a API Sicredi.
- Foi implementada uma melhoria que permite a comunicação via webhook entre o sistema e o banco.
- Com o webhook, sempre que o banco disponibilizar uma instrução de cobrança (liquidação, cancelamento, etc.), ele enviará automaticamente o log de comunicação para o seu sistema.
- Dessa forma, pagamentos via Pix terão seu recebimento imediato no sistema, enquanto pagamentos via boleto continuarão sendo processados no próximo dia útil, assim que o banco confirmar a liquidação.
- Mesmo com o uso do webhook, é importante manter um horário configurado para a Tarefa - Consulta Pagamento Sicredi API, que servirá como garantia de que no dia seguinte ela execute e traga ao sistema quaisquer liquidações que eventualmente fiquem pendentes.
Consulte Integração Webhook da API Sicredi para mais informações.
- Inserção unitária para logs gateway de liquidação da API Sicredi.
- Foi modificado o método de inserção de logs do gateway de liquidação da API Sicredi; anteriormente, a inserção era em lote, agora é feita unitariamente.
- Anteriormente, a tarefa de consulta de pagamentos da API Sicredi executava e registrava um único log no Sistema, contendo todas as liquidações do período consultado.
- Atualmente, a tarefa de consulta executará e registrará um log individual para cada liquidação disponível no período consultado.
- Esse novo método otimiza o processo de baixa e facilita a identificação de logs com problemas.
Funcionamento no sistema
A integração da API Sicredi no sistema funciona da seguinte maneira:
- Autenticação:
- O sistema utiliza as credenciais fornecidas pelo Sicredi para autenticar e acessar a API.
- Sincronização de dados:
- O sistema envia as informações de cobrança para o Sicredi.
- Recebe atualizações sobre o status dos boletos e pagamentos.
- Processamento automático:
- As baixas de pagamentos são processadas automaticamente.
- 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 executar a integração e homologação da API Sicredi no sistema, siga os passos abaixo:
Preparação
- Com o auxílio do Suporte Financeiro, contrate o módulo de API no seu sistema. Isso permitirá seguir com a criação da sua carteira.
Homologação
Para realizar a integração, abra um atendimento com o setor Suporte Financeiro da IXC Soft. Será necessário fornecer os seguintes dados bancários:
Dados bancários necessários para a integração:
748 - Banco Sicredi (API)
- Número da agência com dígito
- Número da conta com dígito
- Número do convênio / beneficiário ou cedente
- Número do posto
- Token/Código de acesso (chave master)
- Credencial X-API-KEY
- Indicar se o convênio bancário é novo ou já foi utilizado para emissão de boletos
Dica!
Em caso de dúvidas sobre os dados bancários, consulte o(a) gerente da sua conta.
Como gerar o Token / Código de acesso na conta Sicredi
Para a homologação da carteira de API do Sicredi, será necessário gerar o código Token (Chave Master) da conta.
- Acesse o Internet Banking Sicredi e faça login.
- No menu Cobrança, vá até o final da página.
- No menu lateral, clique em Código de acesso → Gerar.
- Marque a caixa do termo de adesão e clique em Avançar.
- No aplicativo do Sicredi, na seção Segurança, faça a leitura do QR code gerado.
- O código será exibido. Copie-o e envie para o seu atendente da IXC Soft.
Dica!
Nem todas as contas possuem permissão automática para gerar o código.
- Essa liberação depende da versão do sistema da sua conta.
- Caso não veja a opção, entre em contato com o gerente da conta.
- Solicite a contratação do produto Cobrança Online Ecom via sistema SIAT.
- Assim, a opção de gerar o código será habilitada no Internet Banking.
Passo a passo para obter o Client_ID
Para a homologação da carteira de API do Sicredi, também será necessário obter o código X-API-KEY, criado através do site Developers do Sicredi:
- Acesse o Developers Sicredi.
- Faça login na sua conta.
- No menu Minha Conta, acesse Minhas Apps.
- Clique em Criar nova aplicação.
- Informe o nome e descrição da aplicação. Pode usar o mesmo valor para ambos como, por exemplo:
- Api Cobranca (nº agência) (nº cedente)
- Vá até o fim da página e selecione os escopos:
- OPEN API - OUATH - PARCEIROS 1.0.0
- OPEN API - COBRANCA - PARCEIROS 1.0.0
- Clique em Registrar.
- Você será redirecionado novamente para Minhas Apps, onde poderá visualizar os dados da aplicação. Copie o Client ID (parte antes da barra).
- Acesse o menu Suporte e clique em Abra um chamado.
- Preencha o formulário com as seguintes informações:
- Assunto: API Cobrança Boletos
- Motivo do contato: Solicitar Access Token
- Assunto do chamado: Solicitar Access Token Produção
- Ambiente: Produção
- Client ID ou Nome da App: Informe o valor copiado anteriormente
- Clique em Enviar.
Aviso!
Ativação da aplicação:
- Após enviar o chamado, aguarde a liberação da sua credencial. Esse processo leva de 5 a 60 minutos.
Se você abriu o chamado no ambiente de Sandbox, o código gerado não será válido. Será necessário criar uma nova aplicação no ambiente correto (Produção).
- Quando o status do chamado for alterado para Resolvido, volte em Minhas Apps no Developers Sicredi.
- A aplicação estará com status Aprovada.
- Clique em Ver Detalhes da aplicação.
- Copie o código X-API-KEY exibido.
Credenciais API Finalizadas!
Com o código da chave master e o X-API-KEY em mãos, mais os dados bancários, o atendente da IXC Soft poderá dar sequência à homologação da carteira de cobrança com API.
Migração API Sicredi para Webhook
Se você já utiliza uma carteira bancária com base em tarefas, é possível migrar para comunicação via webhook.
O webhook permite comunicação imediata com a API do banco, garantindo que os eventos de pagamento sejam registrados assim que ocorrerem.
Para fazer a migração:
- Acesse e edite a carteira Sicredi no sistema.
- Na aba Configurações gateway, marque Usar webhook como Sim.
- Preencha os campos Código beneficiário e Código da cooperativa.
- Clique em Salvar.
Criando a carteira
- Acesse o menu Sistema.
- Acesse a pasta Financeiro.
- Clique em Carteira de cobrança.
- Clique em Novo.
- Na aba Carteira de cobrança, configure os seguintes campos:
- Descrição: Nome da carteira.
- Conta: Conta que armazenará os dados bancários.
- Tipo de recebimento: Selecione Gateway.
- Enviar e-mail para cliente ao gerar: Marque como Não (envia a fatura e a registra automaticamente no banco).
- Validar filial na venda: Marque como Sim.
- Planejamento analítico: Utilize 240 ou cadastre um novo código.
Criando a conta
- Conta: Insira o nome da conta.
- Tipo da Conta: Escolha Banco.
- Data de abertura: Coloque a data da configuração.
- Planejamento analítico: Para mais detalhes, acesse: Contas Contábeis Analíticas.
- Filial: Vincule o ID da filial à Conta e à Carteira.
Na aba Banco:
- Banco: Selecione:
- 748 - Banco Cooperativo Sicredi S.A. - BANSICR
- Agência: Insira o número da agência.
- Dígito verificador da agência: Digite o dígito correspondente.
- Número da conta: Insira sua conta bancária.
- Dígito verificador da conta: Informe o dígito da conta.
Configurações gateway
- Gateway: Selecione Sicredi API.
- Versão da API: Escolha V2.
- Ambiente gateway: Selecione Produção.
- Código do beneficiário + Código da cooperativa: Informe os dois códigos juntos, lado a lado.
- Código de acesso: Insira o Token (Chave Master).
- X-api-key: Informe o código gerado no site Developers.
- Data de crédito Pix: Defina o número de dias úteis após o pagamento (Ex.: 0 considera a mesma data).
- Data de crédito boleto: Funciona da mesma forma acima.
- Envia e-mail Gateways: Marque Não.
- Gera pix: Marque Sim.
- Tarifas Gateway: Configure manualmente, pois o banco não faz esse lançamento automático. Veja mais em: Tarifas Bancárias - Gateway, API e Pix
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: Siga as instruções do manual: Contador do Nosso Número
- Número do convênio: Informe o código do beneficiário/cedente
- Posto: Insira o número do posto da conta
- Títulos com recebimento via pix: Marque Sim
Aviso!
- Caso o convênio seja novo, inicie a numeração do nosso número a partir de 200001.
- Se for um convênio já usado, consulte o último número com o banco para configurar corretamente no sistema.
Juros/Multas/Desconto
- Juros %: Configure 0.033%.
- Multa %: Configure 2%.
- Desconto até o vencimento R$: Defina um valor fixo.
- Desconto até o vencimento %: Informe o percentual aplicado.
- Desconto parcela proporcional: Marque para aplicar desconto nas parcelas proporcionais.
Para mais informações, acesse: Juros, Multas e Desconto.
Aviso!
A API do Sicredi 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!
- Máximo de 5 linhas de instrução.
- Cada linha com até 80 caracteres.
Se adicionar mais linhas de instrução, lembre-se de configurar a leitura das variáveis no parâmetro Imprimir instruções quando…
Impressão
- Layout de impressão: Selecione o modelo 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:
- Vá até o menu Ferramentas.
- Clique em Ferramentas.
- Acesse Agenda de tarefas.
- Clique em Novo.
- Em Tarefa, selecione Consulta pagamento Sicredi API.
- Minuto (0-59): Defina o valor, por exemplo, 50.
- Hora (0-23): Insira o(s) horário(s), como 6,12,18,23.
Para mais informações, acesse: Tarefa - Consulta de Pagamento Sicredi 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 Sicredi no sistema permite uma gestão mais ágil das cobranças bancárias. É fundamental seguir corretamente todos os procedimentos e manter suas credenciais seguras para garantir o bom funcionamento da integração.
Etiquetas
IntegracaoBancaria ApiBancaria Sicredi