Com a carteira ligada à API, o Sicoob registra o boleto no momento em que ele é gravado no Mestre, devolve a linha digitável, o código de barras, o nosso número e o QR Code do Pix, e as liquidações voltam pela própria API, sem arquivo de retorno. Este artigo conduz a equipe de suporte do pedido ao banco até o primeiro boleto registrado. Resumo O cliente cria uma aplicação no Portal Developers do Sicoob, vincula a ela o mesmo certificado digital A1 e-CNPJ que a empresa já usa nos documentos fiscais e autoriza o uso das APIs no SicoobNet. Disso sai o Client ID. No Mestre, na maioria dos atendimentos não se cadastra certificado novo: basta abrir o certificado fiscal que já está cadastrado, marcar “Gerar CRT/KEY automaticamente a partir do PFX” e regravar. Depois é preencher a carteira de cobrança com Client ID, Versão da API, Escopo e Certificado, confirmar que o ambiente fiscal está em Produção e emitir um boleto de teste. Não existe Client Secret na Cobrança Bancária V3 do Sicoob: quem prova a identidade da aplicação é o certificado. |
O Client ID e o certificado são um par E esse certificado é o mesmo A1 e-CNPJ que a empresa usa na NF-e e nos demais documentos fiscais, já cadastrado no Mestre. O Sicoob exige conexão com certificado (mTLS) em todas as chamadas, inclusive na de token, e valida o certificado vinculado àquela aplicação. A chave pública enviada ao portal precisa ser a do certificado fiscal que está no Mestre. Se forem certificados diferentes, o banco recusa antes de olhar o boleto, com “O seu acesso nao foi autorizado. Certificado digital e obrigatorio para este recurso.” |
Visão rápida- Credenciais: Client ID (portal) + o certificado digital A1 e-CNPJ que a empresa já usa nos documentos fiscais. A tela da carteira nem exibe Client Secret e Key User para esta API.
- Nosso número: quem numera é o Sicoob. A faixa Início/Fim/Atual da carteira não é usada na emissão por API.
- Pix no boleto: depende de o boleto híbrido estar contratado na cooperativa, com chave Pix vinculada à conta. O Mestre apenas sinaliza o pedido no registro.
- Impressão: o Sicoob devolve o PDF do próprio banco quando a carteira marca “Utilizar layout de impressão padrão do Banco”.
- Ambiente: não fica na carteira. Vem da configuração fiscal da empresa (a mesma da NF-e).
| Etapa | Quem executa | Resultado esperado |
|---|
| 1. Contratar a cobrança (e o boleto híbrido) | Cliente + cooperativa | Número do beneficiário, modalidade e conta confirmados | | 2. Criar a aplicação no portal | Cliente | Client ID ativo, com a API de cobrança e o certificado vinculados | | 3. Preparar o certificado no Mestre | Suporte Mestre | CRT e KEY gerados a partir do PFX fiscal | | 4. Configurar a carteira | Suporte Mestre | Carteira WebService completa e ambiente conferido | | 5. Emitir o primeiro boleto | Suporte Mestre | Boleto registrado, com linha digitável e código de barras |
1. O que o cliente precisa ter no SicoobConfirme os itens abaixo com a cooperativa antes de agendar o atendimento técnico. Todos são definições do banco e nenhum deles se resolve dentro do Mestre. | Item a confirmar | Para que serve |
|---|
| Contrato de cobrança bancária ativo, com o número do cliente/beneficiário e a modalidade contratada | Alimenta os campos Código do cedente e Carteira da carteira de cobrança | | Cooperativa (agência) e conta corrente vinculadas ao contrato | Identificam o beneficiário em cada requisição | | Boleto híbrido (Pix) contratado, com chave Pix vinculada à conta | Sem isso o boleto sai sem QR Code. É contratação na cooperativa, não configuração do Mestre | | Certificado digital A1 e-CNPJ válido — o mesmo já usado na NF-e e nos demais documentos fiscais | É a identidade da aplicação no portal e a conexão segura com a API. Não é preciso comprar nem gerar um certificado só para a cobrança | | Usuário do SicoobNet com poderes para autorizar o uso de APIs | Em conta PJ, a aplicação só fica ativa depois dessa autorização |
2. Criar a aplicação no Portal Developers e obter o Client IDO cadastro é feito pelo cliente, em developers.sicoob.com.br, com os dados da empresa. O suporte pode acompanhar, mas a autorização final depende de quem tem poderes na conta. | 1 | Fazer o cadastro no portal como pessoa jurídica e definir a senha pelo link enviado por e-mail. | | 2 | Criar uma nova aplicação e selecionar a API Cobrança Bancária V3 com os escopos de boleto — no mínimo inclusão, consulta e alteração, que são os que o Mestre solicita no token. | | 3 | Enviar a parte pública do certificado A1 no formato aceito pelo portal (.pem, .crt ou .cer) — a do mesmo certificado fiscal que está cadastrado no Mestre. O portal não aceita o arquivo PFX; a chave privada nunca sai da empresa. | | 4 | Autorizar o uso das APIs no SicoobNet ou no aplicativo do Sicoob, na área de transações pendentes, até a aplicação deixar de ficar pendente. | | 5 | Copiar o Client ID da aplicação. Ele será informado na carteira do Mestre. |
Não procure Client Secret A Cobrança Bancária V3 autentica com Client ID + certificado, sem segredo de aplicação. Se o atendente ficar procurando um “secret” no portal, está no caminho errado — e o campo nem aparece na carteira quando a Versão da API está preenchida. Os nomes dos menus do portal podem mudar; o que não muda é o resultado: aplicação ativa, com a API de cobrança e o certificado vinculados, e um Client ID para copiar. |
3. Preparar o certificado fiscal no MestreA conexão com o Sicoob usa o certificado em dois arquivos — CRT e KEY —, que o próprio Mestre extrai do PFX. Na prática, não há certificado novo para cadastrar: o certificado da cobrança é o mesmo A1 e-CNPJ dos documentos fiscais, que já está em Configurações > Certificados Digitais. O que falta é ligar a geração do CRT/KEY nesse cadastro. | 1 | Abrir Configurações > Certificados Digitais e localizar o certificado da empresa — o mesmo usado na NF-e. | | 2 | Clicar em Modificar. | | 3 | Marcar Gerar CRT/KEY automaticamente a partir do PFX. | | 4 | Clicar em Gravar. Os campos Arquivo CRT e Arquivo KEY ficam desabilitados e são preenchidos pelo sistema, a partir do PFX que já estava gravado. |
Cadastro novo é exceção Só clique em Novo se a empresa não tiver certificado cadastrado no Mestre — o que é raro, porque o mesmo certificado já é exigido pela emissão fiscal. Duplicar o certificado em dois cadastros só cria mais um lugar para esquecer de atualizar na renovação anual. |
Se for mesmo um cadastro novo, estes são os campos que importam: | Campo | O que informar |
|---|
| Descrição | Um nome que identifique o certificado da empresa | | Arquivo | O arquivo PFX do certificado A1 da empresa | | Senha | A senha do PFX | | Gerar CRT/KEY automaticamente a partir do PFX | Marcado. O Sicoob não entrega CRT e KEY separados; quem os produz é o Mestre, a partir do PFX, ao gravar. É o único ajuste necessário quando o certificado já está cadastrado | | Arquivo CRT e Arquivo KEY | Ficam desabilitados com a opção acima marcada e são preenchidos pelo sistema na gravação | | Número de Série (nesta estação) | Deixar em branco: esse campo é para certificado instalado no repositório do Windows |
Depois de gravar, a tela mostra os dados do certificado com a validade. Se a carteira apontar para um certificado sem CRT/KEY, o Mestre recusa o envio com uma mensagem que já diz o que fazer: regravar o cadastro com a opção de geração automática marcada. Na renovação anual do certificado, o cadastro é atualizado com o novo PFX pelo procedimento fiscal de sempre, e o Mestre regera o CRT/KEY na gravação. Lembre o cliente de enviar a nova chave pública ao Portal Developers do Sicoob: enquanto a aplicação estiver com o certificado antigo, o banco recusa a conexão e a emissão de boletos para. 4. Configurar a carteira de cobrançaAbra a rotina Carteiras de cobrança, localize a carteira do cliente (ou cadastre conforme o contrato) e marque Utilizar WebService. Os campos de credencial só aparecem depois que a Versão da API é escolhida. | Campo | O que informar |
|---|
| Banco | 756 - Sicoob | | Agência | A cooperativa do contrato | | Nº Conta e dígito | A conta corrente do contrato. O Mestre envia conta e dígito juntos, como o Sicoob espera | | Código do cedente | O número do cliente/beneficiário do contrato de cobrança. É o que identifica a carteira em todas as chamadas | | Carteira | A modalidade contratada (o Mestre a envia como código de modalidade do boleto). Use a do contrato, não presuma | | Código de transmissão | Opcional. Quando preenchido, vai ao Sicoob como número do contrato de cobrança | | Emissor | Banco | | Utilizar WebService | Marcado | | Versão da API | Sicoob - API V3. Sem esse campo o Mestre não encontra o provedor e a tela não sabe quais credenciais exibir | | Escopo | Sicoob - API V3 — envia inclusão, consulta e alteração de boletos ao pedir o token | | Client Id | O Client ID da aplicação, colado sem espaços | | Certificado | O certificado fiscal da empresa — o mesmo preparado no passo 3 | | Time Out | 60000 (padrão de uma carteira nova) | | Boleto Híbrido (com PIX) | Marque apenas se o boleto híbrido estiver contratado na cooperativa | | Utilizar layout de impressão padrão do Banco | Marque para imprimir o PDF que o próprio Sicoob devolve no registro. Desmarcado, o boleto sai pelo layout do Mestre | | Data Retorno | A data já conciliada. A consulta de movimentação começa no dia seguinte a ela |
Os campos Client Secret e Key User não aparecem nesta versão de API — o Sicoob não usa nenhum dos dois. A faixa de nosso número continua na aba de cobrança escritural e não participa da emissão por API: quem numera é o banco. 5. Conferir o ambiente antes do testeO ambiente da cobrança por API não fica na carteira: ele vem da tela Documentos fiscais eletrônicos - Configuração, campo Ambiente — o mesmo que vale para a NF-e. Em homologação o boleto não é real Com a empresa em Homologação, o Mestre conversa com o ambiente de testes do Sicoob, que responde com massa de dados fixa. A tela conclui sem erro, mas o boleto não existe no banco e o nosso número não é do cliente. Confirme Produção antes do boleto de teste — e lembre que virar esse campo afeta a emissão fiscal da empresa inteira, não só o boleto. |
6. Liberação de redeNão é preciso abrir porta de entrada nem cadastrar o IP do cliente. O computador ou servidor onde o Mestre roda precisa conseguir iniciar conexões de saída HTTPS (TCP 443) para: api.sicoob.com.br auth.sicoob.com.br |
7. Emitir o primeiro boleto- Gere um título de teste, de valor baixo, na carteira configurada.
- Grave o boleto: é na gravação que o registro é enviado ao Sicoob.
- Confira se voltaram nosso número, linha digitável e código de barras. O Mestre recusa o registro que chegar sem esses dados.
- Imprima o boleto e confira o QR Code, quando o Pix estiver contratado.
- Confirme com o cliente que o título aparece na cobrança do Sicoob.
Implantação concluída Considere a implantação concluída apenas depois que um boleto for registrado com sucesso em produção, com linha digitável e código de barras conferidos. |
8. Trazer as liquidações (retorno)Com a carteira por API não existe arquivo de retorno para baixar. Em Contas a Receber > Cobrança > Retorno, escolha a carteira e clique em Processar: o Mestre consulta a movimentação direto no Sicoob. - A consulta vai dia a dia, do dia seguinte à Data Retorno até o dia anterior ao de hoje — o banco só fecha o movimento depois do expediente.
- Cada dia consultado com sucesso avança a Data Retorno, e o log mostra o que foi processado.
- Na implantação, ajuste a Data Retorno para o último dia já conciliado, para não reprocessar nem pular liquidação.
Como o Mestre faz O Mestre conversa com o Sicoob por implementação própria, sem componente de terceiros, e o que ele mostra na tela é o que o banco respondeu: - Registra o título na gravação do boleto e também na emissão automática pela finalização da nota.
- Nunca calcula linha digitável, código de barras ou nosso número: registro cuja resposta venha incompleta é tratado como falha, e não vira boleto “meio pronto”.
- Envia prorrogação, baixa e demais instruções na hora em que o movimento é gravado, uma requisição por título.
- Quebra as mensagens ao pagador em até cinco linhas de 40 caracteres, que é o limite aceito pelo Sicoob.
- Respeita o limite de duas requisições por segundo da API e repete automaticamente as consultas de movimentação quando o gateway do banco falha sem explicação.
- Grava a requisição e a resposta de cada operação, com a URL e o status, para diagnóstico posterior.
|
Checklist de conferência- Aplicação criada no portal, com a API de Cobrança V3, e já autorizada no SicoobNet (sem status pendente).
- A chave pública vinculada à aplicação no portal é a do certificado fiscal que está cadastrado no Mestre.
- Certificado fiscal regravado com “Gerar CRT/KEY automaticamente a partir do PFX” marcado — sem cadastrar certificado novo.
- Carteira com Banco 756, Utilizar WebService, Versão da API, Escopo, Client Id e Certificado preenchidos.
- Código do cedente e Carteira conferem com o contrato de cobrança.
- Ambiente da configuração fiscal em Produção.
- Boleto de teste registrado, com nosso número, linha digitável e código de barras.
- Data Retorno ajustada antes do primeiro processamento de retorno.
Erros comuns e como evitar - “Certificado digital e obrigatorio para este recurso” — a conexão chegou ao Sicoob sem o certificado certo. Confira se a carteira aponta para o certificado fiscal da empresa e se a chave pública vinculada à aplicação no portal é a desse mesmo certificado. Depois de uma renovação anual, é o primeiro item a conferir.
- Aplicação pendente no portal — o Client ID existe, mas ainda não vale. Peça ao responsável pela conta que autorize o uso das APIs no SicoobNet ou no aplicativo.
- “O certificado … não possui os arquivos CRT/KEY” — o certificado fiscal está cadastrado, mas sem a geração automática ligada. Reabra o cadastro, marque a opção e grave de novo; não é preciso cadastrar outro certificado.
- “Retorno do banco sem nosso número, linha digitável…” — quase sempre é ambiente em Homologação respondendo com massa de teste. Confira o campo Ambiente antes de qualquer outra hipótese.
- “O serviço do banco está temporariamente indisponível” — instabilidade do próprio gateway do Sicoob. O Mestre já repete a consulta automaticamente; se persistir, tente mais tarde, sem mexer na configuração.
- Boleto sem QR Code — boleto híbrido não contratado ou sem chave Pix vinculada à conta. Enquanto isso não se resolve na cooperativa, desmarque “Boleto Híbrido (com PIX)” e emita boleto comum.
- Retorno “sem nada a consultar” — a Data Retorno já está no dia de ontem ou à frente. O movimento do dia corrente só fica disponível depois do fechamento no banco.
|
FontesFluxo em uma linha Cooperativa libera a cobrança → cliente cria a aplicação no portal com o certificado fiscal → autoriza no SicoobNet → suporte liga o CRT/KEY no certificado → configura a carteira → confere o ambiente → emite o boleto de teste. |
Revisão: setembro de 2026 — Mestre 9.0.1, API Cobrança Bancária V3 do Sicoob. Campos, mensagens e comportamento conferidos no fonte do provedor e nas telas de Carteiras de cobrança e Certificados Digitais; etapas do portal do banco conferidas na documentação pública do Sicoob. |