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
Para a criação do aplicativo no Sicoob, 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:
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:
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 Banco Itaú. Seguir padrão JSON já conhecido para as demais integrações.
Nome da Unit deverá ser P10_ITAU_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": 2,
"_comentario_": "Integração com Banco Itaú",
"ambiente": "PRODUCAO",
"client_id_sandbox": "cb77fc699b0c4d11b673f6a96f037dc0",
"client_secret_sandbox": "3039529e30a141248a7740debeedda86",
"boletopix_client_id_producao": "950ea2e6f04047339d5b741a5df1e0d8",
"boletopix_client_secret_producao": "aa9ef1b95491482da49dad4006f19178",
"boleto_client_id_producao": "3eda5d330847430cbbb19d9344a7ae2d",
"boleto_client_secret_producao": "1e0c781da493421ca5d1e3efbeb3f720",
"AutoIncChavePix": 1,
"AutoIncPadraoRemessa": 1,
"codigoTipoTitulo": 2,
"protestar": false,
"diasAposVencimentoParaProtestar": 0,
"instrucaoNegativacao": false,
"diasAposVencimentoParaNegativar": 0,
"tipoCobrancaMulta": "02",
"vlrTxMulta": "02.00",
"mensagemBoleto": "Mensagem de teste",
"diasAposVencimentoParaAceitarRecebimento": 30,
"diasAposVencimentoParaBaixarPIXAgendado": 30,
"tipoDescontoBoleto": "02",
"tipoDescontoPix": "02",
"dataDesconto": "01/01/2000",
"vlrDesconto": 2,
"tokenWebhookTekSystem": "",
"urlWebhook": ""
}
]
Descrição dos campos:
contaBancaria: Código da conta corrente do Itaú cadastrada no sistema Tek-System;
ambiente: Informar qual ambiente a conta está sendo utilizada. PRODUCAO/ HOMOLOGACAO;
client_id_sandbox: Client id que será utilizado em ambiente Sandbox;
client_secret_sandbox: Client Secret que será utilizado para geração do Token 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.
boletopix_client_id_producao: Client ID que será utilizado para geração do Token em ambiente de produção para APIs Exclusivas Itaú Pix Recebimentos e APIs Regulatórios Pix Recebimentos;
boletopix_client_secret_producao: Client Secret que será utilizado para geração do Token em ambiente de produção para APIs Exclusivas Itaú Pix Recebimentos e APIs Regulatórios Pix Recebimentos;
boleto_client_id_producao: Client ID que será utilizado para geração do Token em ambiente de produção para API Emissão, Instrução e Consulta de boletos;
boleto_client_secret_producao: Client Secret que será utilizado para geração do Token em ambiente de produção para API Emissão, Instrução e Consulta de boletos;
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 02-Duplicata Mercantil;
protestar: Indicar true/false para protesto dos títulos. 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;
diasAposVencimentoParaProtestar: Indica quantidade de dias após vencimento para protesto do título. Informar apenas se protestar for verdadeiro. Caso contrário, campo será desconsiderado;
instrucaoNegativacao: Indicar true/false para negativação dos títulos. 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;
diasAposVencimentoParaNegativar: Indica quantidade de dias após vencimento para negativação do título. Informar apenas se protestar for verdadeiro. Caso contrário, campo será desconsiderado;
tipoCobrancaMulta: Indica o tipo de cobrança da multa. Podendo ser as opções:
01 - Quando se deseja cobrar um valor fixo de multa após o vencimento; 02 - Quando se deseja cobrar um percentual do valor do título de multa após o vencimento; 03 - Quando não se deseja cobrar multa caso o pagamento seja feito após o vencimento (isento).
taxaMulta: Informar percentual para valor de multa. Ex: 02.00;
mensagemBoleto: Mensagem individual a ser impressa no boleto;
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 Banco Itaú.