Informações Gerais

Bem-vindo ao ecossistema de APIs do Sicredi. Aqui você encontra a documentação técnica para conectar seu ERP, fintech ou sistema de gestão aos nossos serviços financeiros, com guias de início rápido por produto e referência completa de cada API.

Esta página é o ponto de partida. Ela explica como as APIs funcionam de forma geral, como cada uma se autentica, como funcionam os webhooks e onde buscar ajuda. Para integrar de fato, siga o guia de início rápido (Getting Started) da API que você precisa.

---

1. Vamos Começar?

Como são as APIs no Sicredi

Nossas APIs são RESTful e seguem padrões de segurança adequados ao contexto de cada produto. Elas estão organizadas por produto, permitindo que você integre exatamente o que o seu negócio precisa, sem carregar o que não vai usar.

Cada API tem o seu próprio modelo de autenticação, os seus próprios endpoints e a sua própria documentação. Por isso, depois de ler esta visão geral, consulte sempre o guia específico do produto que você vai integrar.

Mapa das APIs:

Primeiros passos

Para integrar com o Sicredi, siga estas etapas:

1. Consulte a documentação da API. Navegue pelo guia de início rápido do produto que deseja integrar (Pix, Cobrança, Multipag, Conta Salário, Extrato de Conta Corrente ou Saldo de Conta Corrente) e revise a referência da API.
2. Solicite adesão e credenciais à sua cooperativa. A contratação do produto e a liberação de acesso são feitas pela sua cooperativa Sicredi. Cada produto exige adesão e, na maioria dos casos, assinatura de um termo.
3. Prepare a segurança da integração. Conforme a API, isso envolve gerar um certificado digital (mTLS) e obter as credenciais de acesso. Os detalhes estão no guia de cada produto.
4. Teste em homologação (Sandbox). Algumas APIs oferecem ambiente de homologação. Cada guia indica como obter acesso e quais dados de teste utilizar.
5. Vá para produção. Com a integração validada, utilize as credenciais e URLs de produção descritas no guia da API.

Credenciais

O modelo de credenciais é definido por API, porque cada produto tem um fluxo próprio de segurança. De forma geral:

• As credenciais de acesso (por exemplo, Client ID e Secret, ou Código de Acesso) são obtidas no Portal do Desenvolvedor ou no Internet Banking, conforme a API.
• Os certificados digitais (para as APIs que usam mTLS) são gerados a partir de um CSR e validados pelo Sicredi.

Consulte o guia da API que você vai integrar para o passo a passo exato de geração e renovação de credenciais.

Dúvidas gerais

Preciso ter conta no Sicredi para ver a documentação?
Não. A documentação técnica é pública. Você não precisa de cadastro para explorar nossas APIs.

Preciso ter uma aplicação criada para acessar o Sandbox?
Depende da API. Consulte o guia específico de cada produto para verificar a disponibilidade de homologação e os requisitos de acesso.

Posso testar antes de contratar?
Você pode explorar livremente a documentação. Para acessar o Sandbox real ou produção, o produto precisa estar contratado junto à sua cooperativa.

---

2. Segurança

A segurança é um princípio central em todas as nossas APIs. Cada produto implementa os mecanismos adequados ao seu contexto de uso e aos requisitos regulatórios.

Visão geral

As APIs do Sicredi combinam dois mecanismos de segurança, que podem ser usados isoladamente ou em conjunto, dependendo do produto:

• mTLS (autenticação mútua de certificados): garante que cliente e servidor são quem dizem ser, através da troca e validação de certificados digitais.
• OAuth2: protocolo de autorização padrão da indústria, no qual você obtém um token de acesso para autenticar suas chamadas.

Não existe um modelo único para todas as APIs. A maioria dos produtos usa as duas camadas em conjunto (mTLS no transporte e OAuth2 para autorização), enquanto a API de Cobrança usa apenas OAuth2. O resumo abaixo orienta onde olhar antes de começar.

Modelos de autenticação por API:

Autenticação mútua de certificados (mTLS)

O mTLS é usado nas APIs que requerem o mais alto nível de segurança no transporte: Pix, Multipag, Conta Salário, Extrato de Conta Corrente e Saldo de Conta Corrente. Nessas APIs, além do token OAuth2, toda chamada precisa apresentar um certificado digital válido.

Para obter o certificado, você gera um CSR (Certificate Signing Request) e o submete para que o Sicredi emita o certificado correspondente. O guia de cada API traz o passo a passo de geração do CSR, validação e instalação, incluindo a conversão de formato quando necessário (alguns certificados são entregues em DER e precisam ser convertidos para PEM).

Dúvidas gerais de segurança

Preciso gerar um certificado para cada API?
Apenas para as APIs que usam mTLS (Pix, Multipag, Conta Salário, Extrato de Conta Corrente e Saldo de Conta Corrente). A API de Cobrança não exige certificado. Consulte o guia de cada produto.

O que acontece se meu certificado expirar?
As chamadas que dependem de mTLS passam a ser rejeitadas. Gere e valide um novo certificado seguindo o guia da API, ou procure sua cooperativa.

Qual é o tempo de expiração do token?
Varia por API e pode diferir entre homologação e produção. A recomendação é sempre ler o tempo de expiração retornado na resposta de autenticação, em vez de fixá-lo no código.

Boas práticas

• Armazene Client ID, Secret, Código de Acesso e a chave privada do certificado de forma segura, em cofre de senhas ou HSM.
• Nunca compartilhe suas credenciais nem versione chaves privadas em repositórios.
• Implemente a renovação de token respeitando o tempo de expiração retornado na resposta.
• Mantenha suas bibliotecas de TLS e segurança sempre atualizadas.

Glossário de segurança

• mTLS: Mutual Transport Layer Security. Autenticação mútua por certificado entre cliente e servidor.
• OAuth2: protocolo de autorização padrão da indústria.
• Client ID e Secret: par de credenciais que identifica a sua aplicação no fluxo client_credentials.
• Código de Acesso: credencial usada pela API de Cobrança no fluxo password, gerada no Internet Banking.
• CSR: Certificate Signing Request. Arquivo que você gera para solicitar a emissão do seu certificado.
• JWT: JSON Web Token. Formato do token de acesso.

---

3. Comunicados

Este é o canal central para anúncios sobre as APIs: novas versões, mudanças de comportamento, depreciações e eventos programados. Acompanhe esta seção para se manter atualizado sobre o que muda no ecossistema.

Comunicados atuais

Nenhum comunicado ativo no momento.

---

4. Parcerias

Nosso objetivo é construir um ecossistema próspero, no qual integrar-se ao Sicredi seja um acelerador para o seu negócio. Ao se tornar um parceiro, você passa a oferecer aos seus clientes acesso aos serviços financeiros de uma das maiores instituições financeiras cooperativas do Brasil.

A relação entre o Sicredi, o associado e o parceiro desenvolvedor é formalizada por meio de adesão e termos específicos de cada produto, tratados junto à sua cooperativa. Para iniciar uma parceria ou entender as condições de cada produto, fale com a sua cooperativa Sicredi.

---

5. Webhooks

Webhooks são a forma mais eficiente de se manter atualizado sobre eventos das APIs, sem precisar fazer consultas repetitivas (polling). Quando um evento acontece, o Sicredi envia uma notificação para a URL que você configurou.

APIs com webhook

Atualmente, quatro das seis APIs oferecem algum modelo de webhook (Extrato de Conta Corrente e Saldo de Conta Corrente são consultas diretas e não emitem webhook). O comportamento e os eventos variam por produto:

Segurança dos webhooks

O modelo de segurança do endpoint que recebe as notificações varia por API, e cada produto define os seus próprios requisitos. De forma geral, o seu endpoint precisa usar HTTPS, mas detalhes como versão mínima de TLS, exigência de certificado de CA pública, porta e tempo máximo de resposta diferem entre as APIs.

Por isso, não existe um requisito único de webhook para todas as APIs. Antes de publicar o seu endpoint, consulte o guia da API correspondente para confirmar:

• Requisitos de HTTPS e de certificado (CA pública, certificado não autoassinado, etc.).
• Versão de TLS e porta exigidas.
• Tempo máximo de resposta esperado pelo Sicredi.
• Como validar a origem da notificação (por exemplo, um valor de autorização enviado no header).

Cadastro e testes

O cadastro do webhook é feito por endpoint específico de cada API, e a disponibilidade de simulação em Sandbox também varia por produto. O guia de cada API descreve como contratar o webhook, quais eventos ele passa a receber e como testá-lo.

---

6. Suporte Técnico

Se você tiver qualquer dúvida ou problema durante a integração, nosso time está aqui para ajudar.

Canais de atendimento

• Portal do Desenvolvedor: developer.sicredi.com.br — Abertura de chamados pelo menu de Suporte e acesso a credenciais e certificados.
• Documentação pública: developers.sicredi.com.br — Guias de início rápido e referência completa das APIs (esta documentação).
• Sua cooperativa Sicredi: para questões comerciais, adesão e contratação de produtos.

Canais específicos por API