Sicredi (748): boleto, boleto híbrido e extrato
Como ligar a cobrança do Sicredi no Hap: onde gerar a chave mestre no Internet Banking, o que é a API Key, quais campos do convênio são obrigatórios, o boleto híbrido com QR Code Pix e por que o extrato do Sicredi pede uma credencial diferente da cobrança.
Quando usar
Use ao configurar a conta Sicredi pela primeira vez, quando a emissão passar a falhar na autenticação, ou ao ligar o extrato da conta corrente.
Antes de começar
- Conta Sicredi cadastrada no Hap com agência e dígito da agência preenchidos - é de lá que saem a Cooperativa e o Posto.
- Acesso ao Portal de Parceiros Sicredi, solicitado ao gerente da agência.
- Acesso ao Internet Banking do Sicredi para gerar a chave mestre.
O que essa integração faz
Com o convênio Sicredi configurado, o Hap registra, consulta, altera e baixa boletos direto na API do Sicredi, sem arquivo de remessa. O extrato e o saldo da conta corrente são uma integração separada, com credencial e certificado próprios, e alimentam a busca automática em Caixas e Contas.
| Recurso | Como funciona |
|---|---|
| Boleto | Registrar, consultar, alterar e baixar direto na API, sem remessa. |
| Boleto híbrido | Marque Boleto híbrido no convênio e o boleto sai com QR Code Pix embutido. |
| Cancelamento | Automático e contextual: o Hap detecta se o título está em carteira, em protesto ou negativado e usa a rota certa. |
| Pagamentos | Por arquivo CNAB 240 nativo, não por API. |
| Webhook | Registrado sozinho ao salvar a conta. Dá baixa no financeiro quando o cliente paga. |
| Pix dinâmico (QR Code no caixa) | Sim, pela API Pix do Sicredi: o caixa do PDV V3 gera a cobrança com o valor da parcela, mostra o QR Code e só fecha a venda quando o banco confirma. Credencial separada da cobrança (Client ID e Client Secret da aplicação Pix); o certificado é o mesmo do extrato. |
| Extrato e saldo | Sim, mas é outra API, com credencial e certificado próprios. |
Antes de começar: o que pedir ao Sicredi
- 1
Peça ao gerente da sua agência o acesso ao Portal de Parceiros Sicredi.
- 2
O Sicredi informa a Cooperativa, o Posto e o Código beneficiário da conta.
- 3
O Sicredi também entrega a API Key oficial da aplicação, que é o valor do header x-api-key.
- 4
Defina o ambiente: SANDBOX, com as credenciais de teste do Sicredi, ou PROD.
Gerar a chave mestre no Internet Banking
No Internet Banking do Sicredi, no menu lateral, abra Código de Acesso e clique em Gerar. É essa chave, e não a senha de login do Internet Banking, que autentica o Hap na API de cobrança. Depois de gerada, cadastre-a no convênio no campo Código de acesso ou Senha: a partir dela o Hap obtém e renova sozinho o token usado no dia a dia.
Preencher o convênio no Hap
Abra Financeiro > Contas Bancárias, edite a conta do Sicredi e vá na aba Convênios. Marque Registro WebService? para ativar o roteamento pela API - os campos do Sicredi só aparecem depois dessa opção marcada.
| Campo no formulário | O que preencher |
|---|---|
| Código beneficiário (obrigatório) | O código fornecido pelo Sicredi. Ele vai no campo Número do convênio. |
| API Key (obrigatório) | O valor oficial do header x-api-key da aplicação cadastrada no portal Sicredi. |
| Código de acesso ou Senha (obrigatório) | A chave mestre gerada no Internet Banking em Código de Acesso > Gerar. |
| Ambiente (obrigatório) | PROD ou SANDBOX, conforme a aplicação registrada no portal. |
| Usuário API | Opcional. Em branco, o Hap monta sozinho a partir do código beneficiário e da cooperativa. |
| Scope | Opcional. Em branco, o Hap usa o escopo padrão de cobrança do Sicredi. |
| Correlation ID fixo | Opcional. Identificador fixo enviado em todas as chamadas, útil para rastrear nos registros. |
| Carteira | A carteira informada pelo Sicredi. Normalmente 1. |
| Client ID / Client Secret da API Pix | Só para o QR Code Pix dinâmico no caixa. Vêm da aplicação Pix criada no Portal do Desenvolvedor do Sicredi (developers.sicredi.com.br). São diferentes da API Key e do Código de acesso da cobrança. O Secret nunca é reexibido: em branco no salvar, o Hap mantém o já gravado. |
| Ambiente da API Pix | Produção. A homologação do Sicredi não é pública - só com URL informada pela equipe do banco. |
| Boleto híbrido | Marque para o boleto sair com QR Code Pix embutido. |
Protesto no Sicredi
O Sicredi aceita protesto automático (ou negativação) de 3 a 99 dias depois do vencimento. O Hap só manda os dias no registro quando o tipo de protesto do convênio pede protesto ou negativação: com "Não Protestar", o boleto é registrado sem protesto, qualquer que seja o número gravado nos dias.
Para os boletos que já estão registrados, o Sicredi aceita três comandos pela API, enviados em lote pela tela Financeiro > Protesto e cartório:
| Comando | Quando usar | O que o banco faz |
|---|---|---|
| Cancelar protesto automático | Antes de o título ir ao cartório | Tira o protesto agendado; o boleto continua valendo |
| Sustar e manter | Título no cartório e o cliente ainda vai pagar | Susta o protesto e mantém o boleto |
| Sustar e baixar | Título no cartório e já resolvido no Hap | Susta o protesto e baixa o boleto |
O Hap consulta o Sicredi antes de cada comando e confirma o efeito numa consulta posterior. Os dias de protesto que o banco ainda tem agendados aparecem na coluna Dias no banco: 0 quer dizer que o protesto foi cancelado.
Extrato: a outra integração
O extrato do Sicredi não usa as credenciais do boleto. Ele tem client_id e client_secret próprios, entregues pelo Sicredi na integração de Conta Corrente, e exige certificado. Na aba Extrato da conta, use o botão Gerar chave e CSR: o Hap gera o par de chaves e o arquivo .csr, e a chave privada nunca sai do sistema. Envie o .csr no Internet Banking, em Outros Serviços > Acesso API Pix > Gerenciar Certificados. A análise leva até 3 dias úteis.
Problemas comuns
- A emissão começou a falhar na autenticação do nada: alguém gerou uma nova chave mestre no Internet Banking. Gerar uma nova inválida a anterior - atualize o campo Código de acesso ou Senha no convênio.
- Testar credenciais reclama de Cooperativa ou Posto: eles não têm campo próprio. O Hap lê os dois da Agência e do Dígito da agência da conta bancária - confira esses dois campos na aba de dados.
- O boleto sai sem o QR Code Pix: marque Boleto híbrido no convênio. No Sicredi ele não é automático.
- O extrato não puxa mesmo com o boleto funcionando: no Sicredi o extrato tem credencial própria. A API Key e o código de acesso da cobrança não servem - é preciso client_id e client_secret da integração de Conta Corrente.
- O certificado do extrato foi recusado: ele não é o A1 fiscal da empresa. É emitido pelo próprio Sicredi a partir do CSR que o Hap gera na aba Extrato.