Sicoob (756): boleto e extrato pelo Portal Developers
Como ligar a cobrança do Sicoob no Hap: cadastro da aplicação no Portal Developers, o Client ID, o certificado A1 obrigatório em produção, os campos do convênio, e por que o Sicoob não gera segunda via de boleto vencido.
Quando usar
Use ao configurar a conta Sicoob pela primeira vez, quando a emissão falhar com erro de certificado, ou quando o cliente pedir a segunda via de um boleto que já venceu.
Antes de começar
- Aplicação cadastrada em developers.sicoob.com.br para o seu cooperado.
- Em produção: certificado digital A1 da empresa cadastrado em Cadastros > Empresa > Certificado Digital, com a senha.
O que essa integração faz
Com o convênio Sicoob configurado, o Hap emite, consulta, altera e baixa boletos pela API de Cobrança Bancária v3, e registra sozinho o webhook que dá baixa no financeiro quando o cliente paga. O extrato e o saldo da conta corrente vêm da API de Conta Corrente e alimentam a busca automática em Caixas e Contas.
| Recurso | Como funciona |
|---|---|
| Boleto | Registrar, consultar, alterar e baixar pela API de Cobrança Bancária v3. |
| Webhook | Registrado sozinho ao salvar a conta. Dá baixa no financeiro quando o cliente paga. |
| Extrato e saldo | Sim, pela API de Conta Corrente. Usa a mesma credencial do boleto, com o escopo de consulta liberado. |
| Pix avulso | Não suportado. |
| Pagamento de contas | Não suportado. |
Antes de começar: o que pedir ao Sicoob
- 1
Acesse developers.sicoob.com.br e cadastre uma aplicação para o seu cooperado.
- 2
Solicite no portal os escopos de cobrança: inclusão, consulta, alteração e webhooks.
- 3
Anote o Client ID que o portal gera para a aplicação.
- 4
Para produção, cadastre o certificado A1 da empresa em Cadastros > Empresa > Certificado Digital, junto com a senha. O sandbox não exige certificado.
Preencher o convênio no Hap
Abra Financeiro > Contas Bancárias, edite a conta do Sicoob e vá na aba Convênios. Marque Registro WebService? e escolha o ambiente - os campos do Sicoob aparecem depois disso.
| Campo no formulário | O que preencher |
|---|---|
| Número do cliente (obrigatório) | O número do convênio fornecido pelo Sicoob. |
| Modalidade (obrigatório) | A modalidade da carteira fornecida pelo Sicoob. |
| Client ID (obrigatório) | O identificador da aplicação cadastrada no Portal Developers. |
| Ambiente (obrigatório) | PROD usa o certificado A1 da empresa; SANDBOX usa o token do portal de testes. |
| Token Sandbox | Obrigatório apenas em SANDBOX. O campo aparece ao escolher esse ambiente. |
| Scope | Opcional. Em branco, o Hap usa os escopos padrão. |
| Correlation ID fixo | Opcional. Identificador fixo para rastrear as chamadas nos registros. |
| Contrato de cobrança | Preencha apenas se o seu contrato com o Sicoob exigir esse identificador. |
Segunda via de boleto vencido
O Sicoob não gera PDF pela API para boleto já vencido, baixado, liquidado ou cancelado. É uma trava do próprio banco, para evitar a reimpressão de um título inválido com código de barras antigo. O Hap detecta a situação e desenha o PDF localmente, com o nosso número, o código de barras e a linha digitável da última consulta - o documento sai, mas continua sendo o título vencido.
Problemas comuns
- Erro de TLS ou handshake ao emitir em produção: falta o certificado A1 da empresa. Ele é cadastrado em Cadastros > Empresa > Certificado Digital, não no convênio. O sandbox não exige certificado.
- O cliente pede a segunda via de um boleto vencido e ela não vem do banco: o Sicoob bloqueia isso na API - é regra do banco, para evitar reimpressão de título inválido. O Hap detecta e desenha o PDF localmente. Para uma via realmente nova, cancele o boleto vencido e emita outro com nova data.
- O boleto foi pago mas o título continua aberto: o Sicoob tira o boleto pago da carteira e a consulta passa a responder que não encontrou. O Hap reconcilia isso por um outro caminho, em lote, na rotina noturna.
- Token Sandbox não aparece: ele só é exibido quando o Ambiente está em SANDBOX.
- O extrato consulta só parte do período: o Sicoob devolve mês a mês. Divida o período em consultas mensais.