Sicoob.Sdk

Sicoob SDKs e Documentação da API

npx @openapitools/openapi-generator-cli generate
-i swagger/spb-transferencias.json
-g python
-o sicoob_sdk_py/spb-transferencias
--package-name sicoob_pix

Este repositório contém as especificações Swagger (OpenAPI) da API Sicoob, devidamente atualizadas e validadas estruturalmente com as configurações de ambientes de produção, incluindo os detalhes de Autenticação mTLS.

O objetivo deste projeto é facilitar a geração de SDKs em diferentes linguagens utilizando o OpenAPI Generator.

Estratégia de Módulos (Multi-SDK)

Para evitar a duplicação do serviço de autenticação em diversas APIs geradas, a arquitetura do projeto foi dividida. O endpoint de token foi extraído de todos os swaggers de produto e consolidado em um arquivo único:

• autenticacao.json: Contém apenas o endpoint /auth/realms/... de autenticação.
• Outros Swaggers (api-pix.json, cobranca-bancaria-v3.json, etc): Contêm estritamente as regras de negócio de seus produtos, exigindo o envio do Bearer token, mas não a sua geração.

Como arquitetar seu SDK Python (sicoob-sdk-py): Você deverá rodar o openapi-generator para cada um dos arquivos JSON, gerando "sub-módulos" dentro do seu pacote Python. Em seguida, fará uma classe "Wrapper" que une tudo.

Exemplo de estrutura gerada:

sicoob_sdk_py/
├── auth/            <-- Gerado a partir de autenticacao.json
├── pix/             <-- Gerado a partir de api-pix.json
├── cobranca/        <-- Gerado a partir de cobranca-bancaria-v3.json
└── client.py        <-- Sua classe customizada que orquestra os módulos

Requisitos de Autenticação e mTLS (Mutual TLS)

As APIs e o servidor de Autorização (Auth) do Sicoob requerem validação adicional por meio de mTLS (Mutual TLS) com um certificado digital corporativo.

Configuração do Certificado:

• Host de Autenticação: auth.sicoob.com.br
• Host da API: api.sicoob.com.br
• Arquivo de Certificado (Exemplo do cliente): /home/naruto/Desktop/certsks/cert/KA5 TELECON E-CNPJ A1 2026.pfx
• Senha do Certificado: <SENHA_FORNECIDA> (passphrase do arquivo PFX)

Para acessar a API, você precisa fornecer este certificado cliente em todas as requisições HTTPS. Como o Python prefere arquivos .pem, extraia o certificado do seu .pfx:

openssl pkcs12 -in "KA5 TELECON E-CNPJ A1 2026.pfx" -out client_cert.pem -nodes

Exemplo de Construção do SDK Wrapper em Python

Veja como usar os sub-módulos gerados sem duplicar a autenticação:

# sicoob_sdk_py/client.py

import sicoob_auth
import sicoob_pix
import sicoob_cobranca

class SicoobClient:
    def __init__(self, client_id: str, cert_path: str, key_path: str = None, cert_password: str = None):
        """
        Inicializa o cliente da Sicoob.
        :param client_id: Client ID da aplicação
        :param cert_path: Caminho para o certificado (em Python, geralmente .pem combinado ou público)
        :param key_path: Caminho para a chave privada (caso esteja separada do .pem)
        :param cert_password: Senha da chave privada (se aplicável)
        """
        self.client_id = client_id
        self.cert_path = cert_path
        self.key_path = key_path
        self.cert_password = cert_password
        self._access_token = None
        
        # Helper para aplicar as configurações de mTLS
        def setup_mtls(config):
            config.cert_file = self.cert_path
            if self.key_path:
                config.key_file = self.key_path
            # Em clientes urllib3 (usados no openapi-generator-python), se o certificado/chave 
            # exigir senha, o suporte nativo varia. Muitas vezes é necessário 
            # usar um certificado PEM sem senha gerado a partir do PFX. 
            
        # 1. Configura a API de Auth (mTLS)
        auth_config = sicoob_auth.Configuration(host="https://auth.sicoob.com.br")
        setup_mtls(auth_config)
        self.auth_api = sicoob_auth.AutenticacaoApi(sicoob_auth.ApiClient(auth_config))
        
        # 2. Configura a API do Pix (mTLS)
        self.pix_config = sicoob_pix.Configuration(host="https://api.sicoob.com.br/pix/api/v2")
        setup_mtls(self.pix_config)
        self.pix_api = sicoob_pix.PixApi(sicoob_pix.ApiClient(self.pix_config))
        
        # 3. Configura a API de Cobrança (mTLS)
        self.cob_config = sicoob_cobranca.Configuration(host="https://api.sicoob.com.br/cobranca-bancaria/v3")
        setup_mtls(self.cob_config)
        self.cob_api = sicoob_cobranca.CobrancaApi(sicoob_cobranca.ApiClient(self.cob_config))

    def authenticate(self, scopes="cco_transferencias cco_consulta openid"):
        """Gera o token e o injeta em todos os submódulos."""
        response = self.auth_api.auth_realms_cooperado_protocol_openid_connect_token_post(
            grant_type="client_credentials",
            client_id=self.client_id,
            scope=scopes
        )
        self._access_token = response.access_token
        
        # Injeta o token nas outras APIs
        self.pix_config.access_token = self._access_token
        self.cob_config.access_token = self._access_token

Resumo dos Endpoints Mapeados

• Token (Auth): https://auth.sicoob.com.br/auth/realms/cooperado/protocol/openid-connect/token
• API Principal (Pix, Pagamentos, etc.): https://api.sicoob.com.br/

Todos os arquivos .json na pasta de swagger estão formalmente validados e prontos para geração modular, garantindo que você tenha um SDK robusto sem redundâncias.