Habilitar a emissão de boletos Sicoob pela API (WebService)
21 min
Criado por Felipe Mateus Hoffmann em 01/09/2026 10:38
Atualizado por Felipe Mateus Hoffmann em 01/09/2026 11:38
BOLETO SICOOB
Como habilitar a emissão de boletos Sicoob pela API no ERP Mestre

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).
EtapaQuem executaResultado esperado
1. Contratar a cobrança (e o boleto híbrido)Cliente + cooperativaNúmero do beneficiário, modalidade e conta confirmados
2. Criar a aplicação no portalClienteClient ID ativo, com a API de cobrança e o certificado vinculados
3. Preparar o certificado no MestreSuporte MestreCRT e KEY gerados a partir do PFX fiscal
4. Configurar a carteiraSuporte MestreCarteira WebService completa e ambiente conferido
5. Emitir o primeiro boletoSuporte MestreBoleto registrado, com linha digitável e código de barras

1. O que o cliente precisa ter no Sicoob

Confirme 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 confirmarPara que serve
Contrato de cobrança bancária ativo, com o número do cliente/beneficiário e a modalidade contratadaAlimenta os campos Código do cedente e Carteira da carteira de cobrança
Cooperativa (agência) e conta corrente vinculadas ao contratoIdentificam o beneficiário em cada requisição
Boleto híbrido (Pix) contratado, com chave Pix vinculada à contaSem 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 APIsEm conta PJ, a aplicação só fica ativa depois dessa autorização

2. Criar a aplicação no Portal Developers e obter o Client ID

O 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.

1Fazer o cadastro no portal como pessoa jurídica e definir a senha pelo link enviado por e-mail.
2Criar 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.
3Enviar 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.
4Autorizar 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.
5Copiar 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 Mestre

A 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.

1Abrir Configurações > Certificados Digitais e localizar o certificado da empresa — o mesmo usado na NF-e.
2Clicar em Modificar.
3Marcar Gerar CRT/KEY automaticamente a partir do PFX.
4Clicar 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:

CampoO que informar
DescriçãoUm nome que identifique o certificado da empresa
ArquivoO arquivo PFX do certificado A1 da empresa
SenhaA senha do PFX
Gerar CRT/KEY automaticamente a partir do PFXMarcado. 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 KEYFicam 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ça

Abra 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.

CampoO que informar
Banco756 - Sicoob
AgênciaA cooperativa do contrato
Nº Conta e dígitoA conta corrente do contrato. O Mestre envia conta e dígito juntos, como o Sicoob espera
Código do cedenteO número do cliente/beneficiário do contrato de cobrança. É o que identifica a carteira em todas as chamadas
CarteiraA modalidade contratada (o Mestre a envia como código de modalidade do boleto). Use a do contrato, não presuma
Código de transmissãoOpcional. Quando preenchido, vai ao Sicoob como número do contrato de cobrança
EmissorBanco
Utilizar WebServiceMarcado
Versão da APISicoob - API V3. Sem esse campo o Mestre não encontra o provedor e a tela não sabe quais credenciais exibir
EscopoSicoob - API V3 — envia inclusão, consulta e alteração de boletos ao pedir o token
Client IdO Client ID da aplicação, colado sem espaços
CertificadoO certificado fiscal da empresa — o mesmo preparado no passo 3
Time Out60000 (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 BancoMarque para imprimir o PDF que o próprio Sicoob devolve no registro. Desmarcado, o boleto sai pelo layout do Mestre
Data RetornoA 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 teste

O 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 rede

Nã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

  1. Gere um título de teste, de valor baixo, na carteira configurada.
  2. Grave o boleto: é na gravação que o registro é enviado ao Sicoob.
  3. Confira se voltaram nosso número, linha digitável e código de barras. O Mestre recusa o registro que chegar sem esses dados.
  4. Imprima o boleto e confira o QR Code, quando o Pix estiver contratado.
  5. 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.

Fontes

Fluxo 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.