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.
- 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.
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 log 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:
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
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.
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.
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.
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.
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: Informe a data em que o crédito das transações via Pix será considerado.
- Data de crédito boleto: Informe a data em que o crédito das transações por boleto (código de barras) será considerado.
- Valor 0: considera a data de crédito igual à data de pagamento.
- Valor 1: considera a data de crédito com um dia adicional à data de pagamento.
Envia e-mail Gateways: Marque Não.
Habilitar Pix no boleto: Marque Sim.
Enviar cobrança Pix pelo WhatsApp: Ativa a funcionalidade de envio do Template Cobrança Pix, exclusivo da integração com o Opa! Suite. Habilitando este parâmetro, um novo campo ficará visível e obrigatório:
- Tipo da chave PIX do gateway: Selecione na lista a opção que corresponde ao Tipo da chave PIX do gateway que será utilizada (CPF/CNPJ, E-mail, Telefone ou Chave Aleatória).
- Chave PIX do gateway: Insira a chave Pix principal que está configurada e é utilizada pela sua conta na instituição financeira correspondente a esta carteira de cobrança.
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
- 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).
Enviar Template Cobrança Pix via WhatsApp com o Opa! Suite
A integração do sistema com a plataforma de mensagens WhatsApp, em parceria com a Meta e OPA! Suite, abre novas possibilidades para a comunicação com seus clientes. Uma dessas funcionalidades é o envio detalhado de informações de cobrança Pix diretamente pelo aplicativo de mensagens WhatsApp. A funcionalidade está disponível em Sistema para carteiras de cobrança do tipo Gateway e Pix.
Quando configurado, seu Sistema estará habilitado para enviar um template otimizado de cobranças Pix ao seu cliente por meio da integração com o Opa! Suite.
Para mais detalhes da funcionalidade e configuração, verifique em Enviar Template Cobrança Pix via WhatsApp com o Opa! Suite.
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
Implementada nova lógica no Contador do Nosso Número para carteiras de cobrança do tipo Sicredi API, garantindo que clientes com alto volume de boletos não tenham interrupção na emissão. Quando o byte atinge 9 e o sequencial 99999, o sistema incrementa automaticamente o prefixo de ano nos dois primeiros dígitos do NN (campo Prefixo do Nosso Número) e reinicia a sequência para 200001, evitando atingir o limite máximo do Nosso Número dentro do mesmo ano.
Caso de uso
Um provedor com alto volume de emissões está utilizando uma carteira Sicredi API. O último "Nosso Número" gerado foi 25999999.
Ação do Sistema:
- Na próxima geração de boleto, o sistema identifica que o contador 25999999 é o último possível para o prefixo "25".
- Automaticamente, o sistema incrementa o prefixo para "26".
- A sequência é reiniciada para "200001".
- O novo "Nosso Número" gerado para o boleto é 26200001.
- O processo de faturamento do cliente continua sem interrupções.
- 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.
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.
- 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.
Logs carteira de cobrança
Aba destinada ao armazenamento dos logs de criação e alteração dos Gateways e APIs.
É importante ressaltar que, mesmo que a autenticação falhe, a carteira de cobrança será salva, e o log detalhado será registrado para posterior investigação.
Para mais informações sobre a aba Logs carteira de cobrança, consulte em:
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.
- 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.
- 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.
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.
Alteração de domínio (URL) com o Webhook
Se a carteira de cobrança configurada estiver utilizando o recurso de Webhook e houver uma alteração no domínio da base (URL de acesso), será necessário atualizar essa informação na carteira de cobrança.
- Já com a nova URL aplicada, acesse sua base do Sistema.
- Vá até a carteira de cobrança e acesse a aba Configurações gateway.
- Clique em Salvar. Nesse momento, a carteira se comunicará com a API e atualizará o endereço para a nova URL do Webhook.
- Verifique se a nova URL aparece corretamente no campo Webhook.
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.