Integração API Banco Sicoob

APIs de Recebimento Sicoob

Documentação para utilização das APIs de Cobrança do Sicoob para permitir realizar envio e retorno de remessas bancárias sem utilizar a troca de arquivos, além da emissão de Bolecode e QRCode.

Bolecode

O bolecode é o meio de cobrança que utiliza as funcionalidades do recebimento por PIX e por Boleto no mesmo documento de pagamento.

O pagamento por QRCode é identificado de forma imediata pelo Sicoob, porém, o movimento na conta respeita as regras do boleto (Ex: D+1).

Quando ocorre o pagamento por código de barras, o QRCode ficará indisponível, porém, o pagamento segue as regras de recebimento dos boletos(Ex: D+1).

Pix

O pagamento do QRCode é identificado de forma imediata pelo Sicoob. A movimentação da conta ocorrerá no mesmo momento.

Credenciais

Será necessário solicitar ao gerente da conta do Sicoob as credenciais para configuração no sistema Tek-System.

Sandobox

• Client Id
• Token

API Sicoob para Pix Recebimentos, Cobrança(Boletos) e Conta Corrente (Extrato)

• Client Id

Certificado Digital

Além das credenciais, será necessário a utilização de certificado digital.

As APIs do Sicoob cujo fluxo de autenticação é client credentials, utilizam certificados digitais garantindo mais proteção à comunicação, autenticação e integridade na utilização dos serviços. Quando um certificado é assinado por uma autoridade de certificação confiável, quem possuir o certificado pode contar com a chave pública que ele contém para estabelecer uma comunicação segura com a outra parte. O padrão internacional x.509 provê a especificação para certificados de chave pública e proporciona uma solução de segurança mais completa, assegurando a identidade de todas as partes envolvidas em uma integração.

Os certificados digitais devem ser emitidos por ACs (Autorizações Certificadoras) ICP Brasil, do tipo A1 e-CNPJ ou e-CPF emitido para o CNPJ do cooperado.

Chaves

O certificado digital é formado por um par de chaves assimétricas, que inclui uma chave privada e uma chave pública. A chave pública deve ser vinculada no momento da geração do aplicativo no Portal Developers, para ser realizada a configuração na ferramenta que estabelece a conexão entre o cooperado e o Sicoob. A chave privada deve ser sempre de conhecimento exclusivo do cooperado e nunca deve ser repassado para o Sicoob ou qualquer outra pessoa que não seja de confiança.

Aplicativo

Necessário criação do aplicativo no Sicoob para utilização em ambiente de Produção, deve-se utilizar somente a chave pública do certificado no formato .PEM, .CRT ou .CER. Caso o seu certificado esteja no formato .PFX siga o tutorial indicado no Portal Developers Sicoob:

https://developers.sicoob.com.br/portal/documentacao?slugItem=seguranca&slugSubItem=certificado-digital

Solicite ao gerente da conta a permissão para criação do aplicativo para utilizar ambiente de produção da Api do Sicoob.

Siga as instruções no portal do Sicoob para criação do Aplicativo de Produção no Portal Developers Sicoob:

https://developers.sicoob.com.br/portal/documentacao?slugItem=apis-do-sicoob&slugSubItem=aplicativos-de-producao

Configurações do Sistema

Necessário solicitar liberação da funcionalidade licenciada ao setor responsável: INTEGRACAO_API_SICOOB

Cadastro da Conta Corrente

Incluir ou alterar cadastro da conta corrente que será utilizada para integração com o Sicoob.

Preencher os dados:

• Registro/Endereço: CNPJ/CEI, Inscrição Estadual e Endereço Completo;
• Informações Bancárias: Banco, Agência, Conta e Digito Conta, Titular, Documento Titular, Sacador Avalista e Documento do Sacador Avalista;
• Padrões da Remessa: Descrição, Carteira, Lay-Out Remessa;
• Chave Pix (Para telefone utilizar padrão internacional. Ex: +5532912345678);

Atenção aos campos:

• Layout Config Remessa: Utilizar layout padrão SICOOB: INTEGRAÇÃO COM API – REMESSA;

• Evite configurar layout de impressão de boletos. Será gerado pela API do Sicoob.

Configuração do Certificado Digital

Após ter gerado os certificados no formato PEM, será necessário realizar a importação dos arquivos no cadastro da Conta. Acesse o módulo financeiro, cadastro da conta, entre na opção do botão Outros, selecione a opção Arquivos em Anexo.

Adote os nomes: 
 Descrição do arquivo: CERT_BOLETO
 Nome do Arquivo: CertificadoCob.pem
 Descrição do arquivo: CERT_PIX
 Nome do Arquivo: CertificadoPix.pem
 Descrição do arquivo: CERT_CONTACORRENTE
 Nome do Arquivo: CertificadoContaCorrente.pem
 Descrição do arquivo: CERT_GERAL
 Nome do Arquivo: CertificadoGeral.pem

Poderá ser utilizado apenas um certificado digital, neste cenário utilize apenas CERT_GERAL.

Configurações da Unidade de Codificação

Incluir na TekStore da conta do Suporte a unidade de codificação correspondente as configurações que serão utilizadas para Api do Sicoob. Seguir padrão JSON já conhecido para as demais integrações.

 Nome da Unit deverá ser P10_SICOOB_CONFIGURACAO_XXXX. Onde XXXX corresponde ao código do cliente cadastrado na Tek-System.

Exemplo de configuração: [

 {
   "contaBancaria": 0,
   "ambiente": "HOMOLOGACAO", 
   "_comentario_": "Conta 0 - Usada em Requisições sem Autenticação - Não remover - É necessária!"      
 },
 {
   "contaBancaria": 0,
   "_comentario_": "Integração com Sicoob",
   "ambiente": "HOMOLOGACAO",
   "clientIdSandbox": "",
   "clientIdProducao": "",    
   "tokenSandbox": "",  
   "autoIncChavePix" : 0,
   "autoIncPadraoRemessa" : 0,     
   "tipoTitulo": "DM",    
   "protestar": 3,
   "diasAposVencimentoParaProtestar": 0,
   "instrucaoNegativacao": 3,
   "diasAposVencimentoParaNegativar": 0,
   "tipoCobrancaMulta": 2,
   "vlrTxMulta": 2.00,
   "mensagemBoleto1": "",
   "mensagemBoleto2": "",
   "mensagemBoleto3": "",
   "mensagemBoleto4": "",
   "mensagemBoleto5": "",
   "mensagemPix": "",           
   "diasAposVencimentoParaAceitarRecebimento": 30,
   "diasAposVencimentoParaBaixarPIXAgendado": 30,
   "tipoDescontoBoleto": 0,
   "tipoDescontoPix": "1",    
   "dataDesconto": "0",
   "vlrDesconto": 2.2,
   "tokenWebhookTekSystem": "",
   "urlWebhook": "https://tekhook.teksystem.com.br:8080/hook/[token]"        
 }

]

Descrição dos campos:

contaBancaria: Código da conta corrente do Sicoob cadastrada no sistema Tek-System;

ambiente: Informar qual ambiente a conta está sendo utilizada. PRODUCAO/ HOMOLOGACAO;

clientIdSandbox: Client id que será utilizado em ambiente Sandbox;

clientIdProducao: Client id que será utilizado em ambiente Produção;

tokenSandbox: Token que será utilizado em ambiente Sandbox;

Observação sobre o ambiente Sandbox: Apesar de existir, não é possível realizar uma validação completa. Sugerimos que utilize o ambiente de produção com valores pequenos adotando alguns cuidados: 
a) Contate o gerente da conta para comunicar sobre o teste, solicitando isenção das taxas cobradas pelas operações;
b) Contate o contador da empresa solicitando orientações sobre a forma que irá conduzir os testes (considerando que haverá movimentação financeira na conta);
c) Após os testes, analise minunciosamente os extratos e relatórios de movimento na conta, observando os reflexos das operações. 

autoIncChavePix: Corresponde a sequência de cadastro da chave Pix na conta correte. Campo de sequência por padrão fica oculto no cadastro, deverá utilizar opção para mostrar os campos para verificar a sequência correta a ser utilizada;

autoIncPadraoRemessa: Corresponde a sequência do cadastro de padrão da remessa da conta corrente.

codigoTipoTitulo: Indica o tipo de título que será enviado na remessa bancária. Utilizar DM-Duplicata Mercantil;

protestar: O protesto é a ação através da qual o portador de um título comercial cujo pagamento não foi efetuado dentro do prazo, garante seu pagamento por ações judiciais;

1 - Protestar Dias Corridos
2 - Protestar Dias Úteis
3 - Não Protestar

diasAposVencimentoParaProtestar: Indica quantidade de dias após vencimento para protesto do título. Informar apenas se protestar diferente de 3. Caso contrário, campo será desconsiderado;

instrucaoNegativacao: A negativação é o ato de inserir uma pessoa em cadastros de maus pagadores, tais como Serasa e o Serviço Central de Proteção ao Crédito (SCPC), porque não pagou uma conta, uma prestação ou outra obrigação financeira;

2 - Negativar Dias Úteis. 
3 - Não Negativar

diasAposVencimentoParaNegativar: Indica quantidade de dias após vencimento para negativação do título. Informar apenas se negativar for 2. Caso contrário, campo será desconsiderado;

tipoCobrancaMulta: Indica o tipo de cobrança da multa. Podendo ser as opções:

0 - Isento; 
1 - Valor fixo de multa após o vencimento; 
2 - Percentual de multa após o vencimento.

taxaMulta: Informar percentual para valor de multa. Ex: 02.00;

mensagemBoleto1: Mensagem 1 individual a ser impressa no boleto;

mensagemBoleto2: Mensagem 2 individual a ser impressa no boleto;

mensagemBoleto3: Mensagem 3 individual a ser impressa no boleto;

mensagemBoleto4: Mensagem 4 individual a ser impressa no boleto;

mensagemBoleto5: Mensagem 5 individual a ser impressa no boleto;

mensagemPix: Mensagem individual a ser enviada no Pix Agendado;

diasAposVencimentoParaAceitarRecebimento: indica a quantidade de dias corridos após Data de Vencimento, em que a cobrança do Bolecode poderá ser paga. Sempre que a data de vencimento cair em um fim de semana ou em um feriado para o usuário pagador, ela deve ser automaticamente prorrogada para o primeiro dia útil subsequente;

diasAposVencimentoParaBaixarPIXAgendado: indica a quantidade de dias corridos após Data de Vencimento, em que a cobrança do Pix Agendado poderá ser paga. Sempre que a data de vencimento cair em um fim de semana ou em um feriado para o usuário pagador, ela deve ser automaticamente prorrogada para o primeiro dia útil subsequente;

tipoDescontoBoleto: indica o tipo de desconto do boleto. Podendo ser as opções:

00 - Quando não houver condição de desconto – sem desconto; 
01 - Quando o desconto for um valor fixo se o título for pago até a data informada (data_desconto); 
02 - Quando o desconto for um percentual do valor do título e for pago até a data informada (data_desconto); 
90 - Percentual por antecipação(utilizando parâmetros do cadastro de beneficiário para dias úteis ou corridos); 
91 -Valor por antecipação (utilizando parâmetros do cadastro de beneficiário para dias úteis ou corridos);

tipoDescontoPix: indica o tipo de desconto do pix. Podendo ser as opções:

0 - Sem desconto; 
1 - Valor Fixo até a[s] data[s] informada[s]; 
2 - Percentual até a data informada; 
3 - Valor por antecipação dia corrido; 
4 - Valor por antecipação dia útil; 
5 - Percentual por antecipação dia corrido; 
6 - Percentual por antecipação dia útil;

dataDesconto: Informa a data de desconto para o Pix ou Boleto. Caso mantenha o valor indicado 01/01/2000, será considerada a data de vencimento do título;

vlrDesconto: indicado o percentual ou valor de desconto que deverá ser aplicado ao título.

tokenWebhookTekSystem: token da configuração do cliente cadastrada na TekHook.

urlWebhook: Url de callback que foi utilizada para registro no Sicoob.

Funcionalidades

 Antes de prosseguir, verifique se os processamentos específicos, indicadores e relatórios específicos foram liberados para o usuário responsável pela utilização da API.

Remessa Bancária

Gerar Remessa Bancária

Incluir remessa bancária dos títulos para gerar boletos/pix.

Os títulos não podem possuir informações de boletos/pix já gerados. Estes campos são preenchidos pelo sistema após processar a remessa.

Na aba de Totalização/Outras, em Geração, deverá ser informado o layout SICOOB: INTEGRAÇÃO COM API – REMESSA.

Campo de instrução deverá ser informado BOLETO(GERAR BOLETO HÍBRIDO) ou PIX(GERAR PIX AGENDADO). As demais opções ainda não estão disponíveis para utilização.

Clique no botão Processar: O Sistema realizará a transmissão dos títulos para API do Sicoob.

Após finalizar o processo, será possível verificar a situação dos títulos no banco através dos Processamentos acessíveis na grade da guia Duplicatas do cadastro da Remessa ou na grade de duplicatas do cadastro de contas a receber (Menu Manutenção >> Contas a Receber).

Junção de Boletos(Python)

Para funcionamento da junção de boletos será necessário realizar a instalação do Python na estação que irá utilizar a integração com o Sicoob.

Caso não tenha o Python instalado, realize o download no site para versão para Windows: https://www.python.org/downloads/

Realize a instalação do Python. 
*Utilize instalação personalizada
*Marque todas opções em Optional Features
*Marque opção Associate files with Python
*Marque opção Add Python to environment variables

Execute no terminal do Windows (cmd.exe) como administrador o comando: py -m pip install PyPDF2

Feche e abra o sistema novamente após instalação.

Impressão dos Boletos

Abrir borderô de remessa bancária que deseja realizar a geração dos boletos em formato pdf.

Selecionar processamento específico SICOOB: Gerar PDF de Boletos do Borderô de Remessa através da grade de duplicatas ou botão F9 - Outros, e executar.

Será realizado o download dos boletos registrados na API do Sicoob. Por padrão, será salvo dentro da pasta temp do sistema (Ex: C:\Tek-System\ExecMC\TEMP\Usuario\Sicoob_Conta_C_Bordero_B. C = Código da conta, B = Código do Borderô).

Se na remessa existir apenas um boleto o mesmo será aberto ao final do processamento. Caso exista mais de uma boleto, o sistema irá tentar realizar a junção dos boletos em um único arquivo pdf com o nome de TodosBoletosSicredi.pdf. Ao realizar a junção, ao final do processamento será exibido o pdf com todos os boletos. Caso não seja possível, será aberto a pasta contendo todos boletos baixados.

Exemplo de impressão do boleto do Sicoob com dados fictícios.

Retorno Bancário

Retorno em análise de desenvolvimento.

Borderô de Recebimento

Realizar o recebimento de um complemento de borderô através do QRCode do Pix.

Processamentos específicos disponíveis: 
* SICOOB: Recebimento por Pix:  Processamento específico para gerar Pix para recebimento.
* SICOOB: Cancelar/Estornar Pix: Processamento específico para cancelar o Pix gerado. Se o Pix já foi pago, será realizado o estorno do valor recebido.
* SICOOB: Verificar Situação do Pix Imediato: Processamento específico para consultar a situação do Pix e atribuir Confirmação ou Cancelamento do Pagamento.

Recebimento através do Pix

O Pix somente será criado se o borderô estiver gravado, a data do acerto for igual a do dia atual e o horário for inferior às 23:40.

Ao clicar no processamento específico para Recebimento por Pix, será criado o Pix no Sicoob e exibido o QRCode e o QRCode Data para pagamento no estilo cópia e cola, possibilitando ao usuário enviar via WhatsApp.

Além disso, serão preenchidos os dados do Pix no registro complementar.

Após pagamento ou cancelamento, será informado no registro de complemento a confirmação ou cancelamento da operação.

Após finalizar operação, não será possível alterar informação do complemento no borderô.

Quando o Pix for gerado e estiver aguardando confirmação ou com a confirmação de pagamento realizada, será gerado movimento de entrada no caixa.
Pix com pagamento confirmado, o movimento no caixa é gerado como realizado.
Quando o Pix estiver expirado ou cancelado, será gerado movimento de saída no caixa. 
Pix com pagamento confirmado e cancelado, o movimento no caixa é gerado como realizado.

Indicadores

SICOOB: Verificar Situação do Boleto

Indicador para ser utilizado em diversos locais do sistema para verificar informações dos boletos híbrido registrado no Sicoob através da API.

• Contas a Receber;
• Ficha de Cliente;
• Borderôs de Acerto, Remessa e Retorno Bancário.

SICOOB: Verificar Situação do PIX

Indicador para ser utilizado em diversos locais do sistema para verificar informações dos PIX agendados registrado no Sicoob através da API.

• Contas a Receber;
• Ficha de Cliente;
• Borderôs de Acerto, Remessa e Retorno Bancário.

SICOOB: Qtd de PIX recebidos hoje

Indicador para informar a quantidade de PIX recebidos durante o dia.

Para funcionar, é necessário configurar os parâmetros do indicador. Deve ser informado a conta que será utilizada. Por padrão, será considerado o filtro referente ao dia atual.

Exemplo de configuração dos parâmetros:

{
  "conta":2
}

Relatórios Específicos

SICOOB: Listagem de recebimentos de PIX

Relatório para listagem do extrato de todas as transações ocorridas em uma conta corrente no devido mês, ano e dia. As informações exibidas são retornadas pela API do Sicoob.

Ao executar o relatório serão exibidos os filtros:

• Data Inicial e Final: período referente aos recebimentos do Pix;

• Tipo de Movimento: Ambos, Crédito e Débito;

• Compactação: analítico ou sintético. Ao selecionar analítico será apresentado as informações detalhadas de liquidação;

• Conta: filtro obrigatório para identificar qual conta será buscado as informações;

• Ordem: Nome da Pessoa, Data de Movimento, Data de Movimento do Lote e Valor;

• Exibir Info. Complementar: Indicar se irá apresentar informações completares dos movimentos;

• Exibir Saldo em Conta: Indicar se irá apresentar informações do saldo da conta;

• Quebras: filtro opcional para apresentação do relatório. Quebras por: Pessoa, Descrição do Movimento, Data de Movimento e Data de Movimento do Lote;

Outras Funcionalidades

Processamentos específicos disponíveis nas grades referente as duplicatas em alguns cadastros do sistema como Contas a Receber, Borderô Remessa Bancária, Borderô de Recebimento e Ficha de Histórico do Cliente e Retorno Bancário.

Clicar com botão direito na grade, e verifique os processamentos disponíveis para cada cadastro.

SICOOB: Prorrogar Boleto

Efetuar a alteração da data de vencimento de um boleto. A data de vencimento consiste no último dia para pagamento do boleto sem acréscimo de multa, juros e outros.

Antes de executar o processamento para prorrogação, o usuário deverá efetuar a prorrogação do título no sistema. Após alteração realizada, executar o processamento para alteração no Sicoob.

Não é possível realizar prorrogação do boleto no mesmo dia da emissão.

SICOOB: Protestar Boleto

Protestar um boleto no Sicoob. O protesto é a ação através da qual o portador de um título comercial cujo pagamento não foi efetuado dentro do prazo, garante seu pagamento por ações judiciais.

A executar o título será protestado.

SICOOB: Solicitar Baixa de Boleto

Baixar um boleto no Sicoob. O processo de baixa consiste na ação de invalidar o boleto.

Ao executar o título será baixado no Sicoob.

SICOOB: Verificar Situação do Boleto

Irá exibir informações da situação do título selecionado referente ao boleto no Sicoob.

SICOOB: Verificar Situação do PIX

Irá exibir informações da situação do título selecionado referente ao Pix no Sicoob.

SICOOB: Cancelar Pix Agendado

Efetuar o cancelamento de um pix agendado no Sicoob.

SICOOB: Prorrogar Pix

Efetuar a alteração da data de vencimento de um Pix Agendado. A data de vencimento consiste no último dia para pagamento do pix sem acréscimo de multa, juros e outros.

Antes de executar o processamento para prorrogação, o usuário deverá efetuar a prorrogação do título no sistema. Após alteração realizada, executar o processamento para alteração no Sicoob.