O que é esta API?

A API de Cobrança do Sicredi permite cadastrar, gerir e conciliar boletos por integração REST com seu sistema, site ou aplicativo. Suporta boletos Tradicionais (linha digitável + código de barras) e Híbridos (com QR Code Pix integrado), comandos de instrução (baixa, alteração de vencimento, desconto, juros, protesto, negativação), consultas para conciliação e notificações em tempo real via Webhook. Os boletos ficam disponíveis para liquidação imediatamente após o cadastro. Disponível 24 horas, 7 dias por semana.

Casos de uso principais:

Emissão automatizada de boletos (Tradicional ou Híbrido);
Gestão do ciclo de vida do boleto (baixa, alteração de vencimento, protesto, negativação);
Conciliação financeira (boletos liquidados por dia e movimentações financeiras);
Recebimento de notificações de liquidação em tempo real via Webhook.

🖐️
Qual é o seu ponto de partida?
→ Já tenho x-api-key: código de acesso e o produto Cobrança habilitado. Comece em Passo 1, Obter token de acesso.
→ Ainda não tenho acesso liberado: Veja Como obter acesso à API de Cobrança antes de continuar, essa etapa envolve sua cooperativa e o Internet Banking, e não é feita por aqui.

🗝️ Entenda as três credenciais antes de começar

Credencial	O que é	Onde você obtém	Onde ela vai
`x-api-key`	Identifica a sua aplicação	Portal do Desenvolvedor (ao criar a app)	Header x-api-key em todas as requisições
`access_token`	Autoriza a chamada (Bearer/JWT)	Retornado no Passo 1 (autenticação)	Header `Authorization: Bearer` ...
Código de acesso (`password`)	Sua senha de autenticação	Internet Banking (Cobrança > Código de Acesso > Gerar)	Corpo da requisição do Passo 1

⚠️
Três avisos que evitam a maioria dos erros de autenticação:

O x-api-key e o código de acesso são diferentes entre Sandbox e Produção. Use sempre o par correspondente ao ambiente.

O código de acesso é por conta, não pela sua base inteira. Se você integra mais de uma conta com Cobrança, gere e configure um código de acesso para cada conta.

Não confunda x-api-key (aplicação) com access_token (chamada). Os dois viajam juntos, em headers diferentes, em quase toda requisição.

Detalhes de geração passo a passo (com o caminho exato no Internet Banking e no Portal) estão em Autenticação em detalhe.

Antes de começar

Antes de fazer sua primeira chamada, você precisa ter:

Pré-requisito	Como obter	Onde encontrar
Produto Cobrança contratado	Contratar na modalidade API (Cobrança Online)	Gerente de conta / cooperativa
Código do Beneficiário	Gerado na contratação	Informado pela cooperativa
Código de acesso	Gerar no Internet Banking (perfil Master)	Internet Banking Sicredi
x-api-key	Criar aplicação no Portal e selecionar a API de Cobrança	Portal do Desenvolvedor
Modalidade Híbrida (se for emitir boleto com Pix)	Habilitar no Portal PJ	Você deverá solicitar ativação à sua cooperativa.
URL de Webhook (opcional)	Endpoint HTTPS da sua aplicação	Sua infraestrutura

📘
Boleto Híbrido não exige contratar Pix
Para emitir boletos híbridos, basta ter a modalidade híbrida habilitada no cadastro de Cobrança (Portal PJ). Se não estiver habilitada, solicite a ativação à sua cooperativa.

Ambientes

Ambiente	URL de Autenticação	URL Base da API
Homologação (Sandbox)	`https://api-parceiro.sicredi.com.br/sb/auth/openapi/token`	`https://api-parceiro.sicredi.com.br/sb/cobranca/boleto/v1/`
Produção	`https://api-parceiro.sicredi.com.br/auth/openapi/token`	`https://api-parceiro.sicredi.com.br/cobranca/boleto/v1/`

⚠️
Dados de teste do Sandbox
Autenticação: username: 123456789, password: teste123. Demais operações: cooperativa: 6789, posto: 03, codigoBeneficiario: 12345.

⚠️
Nem tudo tem Sandbox. O Webhook e a consulta v2
(data-movimento) existem apenas em Produção. O que não tem homologação está sinalizado no passo correspondente.

⚠️
Retornos do Sandbox são default.
Na impressão do boleto e na consulta por Nosso Número, o Sandbox devolve dados pré-montados, não os dados que você enviou no cadastro. Considere isso ao validar retornos em homologação.

Passo a passo: sua primeira chamada

Obter token de acesso

A API de Cobrança usa OAuth2 password (não client_credentials). Sua senha é o código de acesso gerado no Internet Banking.

curl --location 'https://api-parceiro.sicredi.com.br/sb/auth/openapi/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'x-api-key: SEU_X_API_KEY' \
  --header 'context: COBRANCA' \
  --data-urlencode 'grant_type=password' \
  --data-urlencode 'username=123456789' \
  --data-urlencode 'password=teste123' \
  --data-urlencode 'scope=cobranca'

username = Código do Beneficiário (5 posições) + Código da Cooperativa (4 posições), sem separadores. Ex.: 12345 + 6789 = 123456789.
context deve ir fixo como COBRANCA.

Resposta esperada:

{

  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldU...",
  "token_type": "Bearer",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldU...",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "scope": "cobranca profile email"
}

⚠️
Não autentique a cada chamada.
Reutilize o mesmo access_token até ele expirar. Quando expirar, use o refresh_token (com grant_type=refresh_token, sem reenviar username/password) para renovar. Só refaça a autenticação completa quando o refresh_token também expirar. Os tempos de expiração podem variar entre Sandbox e Produção, então leia sempre expires_in e refresh_expires_in da resposta em vez de fixá-los no código.

Fluxo completo de refresh, expiração e geração de credenciais em Autenticação em detalhe.

Criar um boleto

Com o token em mãos, cadastre um boleto. O exemplo abaixo é um boleto tradicional (tipoCobranca: NORMAL), o caminho mais curto para o primeiro sucesso.

curl -X POST \
  'https://api-parceiro.sicredi.com.br/sb/cobranca/boleto/v1/boletos' \
  -H 'Authorization: Bearer SEU_ACCESS_TOKEN' \
  -H 'x-api-key: SEU_X_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'cooperativa: 6789' \
  -H 'posto: 03' \
  -d '{
    "codigoBeneficiario": "12345",
    "tipoCobranca": "NORMAL",
    "especieDocumento": "DUPLICATA_MERCANTIL_INDICACAO",
    "dataVencimento": "2026-07-30",
    "valor": 500.00,
    "seuNumero": "NF123456",
    "pagador": {
      "tipoPessoa": "PESSOA_FISICA",
      "documento": "12345678909",
      "nome": "JOAO DA SILVA"
    }
  }'

Resposta esperada (201 Created):

{
  "txid": null,
  "qrCode": null,
  "linhaDigitavel": "74891125110061420512803153351030188640000050000",
  "codigoBarras": "74891886400000500001125100614205120315335103",
  "cooperativa": "6789",
  "posto": "03",
  "nossoNumero": "251006142"
}

Guarde o nossoNumero, é ele que identifica o boleto nas consultas e comandos de instrução seguintes.

Armadilhas comuns no cadastro (cada uma gera erro ou comportamento inesperado):

🔅
Boleto Híbrido (com Pix):
envie tipoCobranca: "HIBRIDO". Os campos txid e qrCode da resposta virão preenchidos. Requer a modalidade híbrida habilitada no Portal PJ (ver "Antes de começar").

⚠️
Híbrido que vira tradicional silenciosamente:
se você enviar tipoCobranca: "HIBRIDO" e informar dataInicioJuros ou dataInicioMulta, o boleto é registrado como tradicional, sem QR Code, porque o QR Code não comporta datas de carência. A API não avisa; o boleto simplesmente vem sem Pix.

⚠️
Códigos são texto, não número.
Envie codigoBeneficiario, cooperativa e posto como string (entre aspas) no JSON. Como número, o zero à esquerda é descartado e a requisição falha.

⚠️
Juros percentual exige o tipo.
Ao usar juros percentual, informe também tipoJurosPercentual (DIARIO ou MENSAL). Enviar só o valor do juros leva a comportamento default inesperado.

⚠️
Endereço do pagador pode ser obrigatório.
endereco, cidade, uf e cep são opcionais por padrão, mas passam a ser obrigatórios se o beneficiário tiver validação de CEP ativada, ou em pedidos de protesto/negativação.

Todos os campos, espécies de documento, descontos escalonados, protesto/negativação automáticos, informativos, mensagens e Split estão em Referência de cadastro.

Consultar um boleto

Consulte a situação de um boleto pelo Nosso Número:

curl -X GET \
  'https://api-parceiro.sicredi.com.br/sb/cobranca/boleto/v1/boletos?codigoBeneficiario=12345&nossoNumero=251006142' \
  -H 'Authorization: Bearer SEU_ACCESS_TOKEN' \
  -H 'x-api-key: SEU_X_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'cooperativa: 6789' \
  -H 'posto: 03'

A resposta traz a situação do boleto (em carteira, liquidado, baixado, protestado, negativado, entre outras) e os dados de liquidação quando houver. A lista completa de situações e seus significados está em Situações do boleto.

🔅
Conciliação em fim de semana:
para liquidações Pix em fins de semana e feriados, a data efetiva do pagamento difere da data de movimento contábil. Use a consulta v2 com o header data-movimento: true para obter a data de movimento ajustada ao próximo dia útil. A v2 existe apenas em Produção.

Imprimir o boleto (PDF / 2ª via).

curl -X GET \
  'https://api-parceiro.sicredi.com.br/sb/cobranca/boleto/v1/boletos/pdf?linhaDigitavel=74891125110061420512803153351030188640000050000' \
  -H 'Authorization: Bearer SEU_ACCESS_TOKEN' \
  -H 'x-api-key: SEU_X_API_KEY' \
  -H 'Content-Type: application/json'

⚠️
ATENÇÃO
Caso seja necessário imprimir a 2° via do boleto, será necessário realizar o download via Internet Banking (IB).

Dar baixa em um boleto

Os comandos de instrução alteram o estado de um boleto já cadastrado. A baixa é o exemplo mais comum (use quando o pagamento for recebido por outro meio):

curl -X PATCH \
  'https://api-parceiro.sicredi.com.br/sb/cobranca/boleto/v1/boletos/251006142/baixa' \
  -H 'Authorization: Bearer SEU_ACCESS_TOKEN' \
  -H 'x-api-key: SEU_X_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'cooperativa: 6789' \
  -H 'posto: 03' \
  -H 'codigoBeneficiario: 12345'

Resposta esperada (202 Accepted):

{
  "transactionId": "abc12345-...",
  "dataMovimento": "2026-06-24",
  "codigoBeneficiario": "12345",
  "nossoNumero": "251006142",
  "cooperativa": "6789",
  "posto": "03",
  "statusComando": "MOVIMENTO_ENVIADO",
  "dataHoraRegistro": "2026-06-24T10:15:00-03:00",
  "tipoMensagem": "BAIXA"
}

📘
Todos os comandos de instrução são assíncronos
O retorno 202 Accepted com statusComando: MOVIMENTO_ENVIADO significa que a instrução foi recebida e será processada depois, não que já foi concluída. Alteração de vencimento, desconto, juros, protesto, negativação e os demais seguem exatamente este padrão.

Os outros 12 comandos (com seus endpoints, corpos, regras por situação do título e restrições por espécie de documento) estão em Comandos de instrução.

Receber notificações via Webhook (opcional)

Para ser notificado automaticamente das liquidações, contrate um Webhook apontando para um endpoint seu:

curl -X POST \
  'https://api-parceiro.sicredi.com.br/cobranca/boleto/v1/webhook/contrato/' \
  -H 'Authorization: Bearer SEU_ACCESS_TOKEN' \
  -H 'x-api-key: SEU_X_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "cooperativa": "6789",
    "posto": "03",
    "codBeneficiario": "12345",
    "eventos": ["LIQUIDACAO"],
    "url": "https://seu-sistema.com/webhook/cobranca",
    "urlStatus": "ATIVO",
    "contratoStatus": "ATIVO"
  }'

Na contratação, eventos recebe o valor genérico ["LIQUIDACAO"]. O contrato passa então a entregar os eventos granulares de liquidação (Pix, rede, compensação, cartório, estorno, entre outros).

⚠️
Webhook é só Produção, não há Sandbox.
O endpoint que você informar precisa: usar HTTPS com certificado não autoassinado, suportar TLS 1.2, e responder HTTP 200 em até 10 segundos. Sem resposta nesse prazo, o evento é marcado como "NÃO ENTREGUE". Recomenda-se receber o evento, enfileirar e processar de forma assíncrona.

🔅
Segurança do endpoint:
a API não define uma assinatura criptográfica padrão. Use os campos opcionais header/token do contrato para proteger seu endpoint e, como camada extra, valide a liquidação pela API de consulta antes de efetivar qualquer processamento financeiro.

Contratação, consulta, alteração de contrato, estrutura dos eventos recebidos e tratamento de reentrega em Webhook completo.

✅ Você fez sua primeira chamada. Próximos passos.

Tópico	Descrição	Onde encontrar
Referência de cadastro	Todos os campos, espécies de documento, descontos, protesto/negativação automáticos, informativos e mensagens	Referência de cadastro
Distribuição de Crédito (Split)	Rateio do crédito entre até 30 contas, cancelamento de parcelas e liberação de repasse	Split de crédito
Comandos de instrução	Alteração de vencimento, desconto, juros, seu número, abatimento, protesto, negativação	Comandos de instrução
Consultas e conciliação	Consulta v1/v2, liquidados por dia, movimentações financeiras (Francesinha)	Consultas e conciliação
Webhook	Contratação, consulta, alteração e eventos recebidos	Webhook completo
Geração do Nosso Número	Estrutura, composição e cálculo do dígito verificador	Nosso Número
Códigos de erro	Cenários por status HTTP e por situação do título	Códigos de erro
Glossário	Beneficiário, pagador, cooperativa, posto, situações do boleto	Glossário

Precisa de ajuda?

Portal do Desenvolvedor: developer.sicredi.com.br abertura de chamados via menu Suporte
Cooperativa: para contratação, habilitação de modalidades e questões comerciais

O que é esta API?

Qual é o seu ponto de partida?

🗝️ Entenda as três credenciais antes de começar

Três avisos que evitam a maioria dos erros de autenticação:

Antes de começar

Boleto Híbrido não exige contratar Pix

Ambientes

Dados de teste do Sandbox

Nem tudo tem Sandbox. O Webhook e a consulta v2

Retornos do Sandbox são default.

Passo a passo: sua primeira chamada

Obter token de acesso

Resposta esperada:

Não autentique a cada chamada.

Criar um boleto

Resposta esperada (201 Created):

Boleto Híbrido (com Pix):

Híbrido que vira tradicional silenciosamente:

Códigos são texto, não número.

Juros percentual exige o tipo.

Endereço do pagador pode ser obrigatório.

Consultar um boleto

Conciliação em fim de semana:

Imprimir o boleto (PDF / 2ª via).

ATENÇÃO

Dar baixa em um boleto

Resposta esperada (202 Accepted):

Todos os comandos de instrução são assíncronos

Receber notificações via Webhook (opcional)

Webhook é só Produção, não há Sandbox.

Segurança do endpoint:

✅ Você fez sua primeira chamada. Próximos passos.

Precisa de ajuda?