Integração Open Finance Santander

Este projeto disponibiliza scripts Python para realização de consultas e operações bancárias de empresas utilizando a API do Open Finance do Banco Santander.

Oriundo de uma necessidade empresarial, o objetivo deste projeto é fornecer um exemplo simples e funcional de integração com APIs bancárias usando autenticação OAuth2 e mTLS (certificado digital), permitindo realizar requisições autenticadas para obtenção de dados financeiros e exportação dos resultados.

📊 Funcionalidades

• Autenticação OAuth2: obtenção automática de token de acesso utilizando client_credentials.
• Autenticação mTLS: uso de certificado digital para comunicação segura com a API.
• Consulta de saldo: recuperação do saldo atual da conta via endpoint balances.
• Consulta de extrato: recuperação de transações via endpoint statements.
• Exportação de dados: salvamento dos resultados em arquivos .json.
• Uso de variáveis de ambiente: armazenamento seguro de credenciais via .env.

Exemplo

Exemplo de resposta retornada pela API ao consultar extrato:

[
    {
        "creditDebitType": "DEBITO",
        "transactionName": "PREST. DE EMPREST.",
        "historicComplement": "PARC 002/024",
        "amount": "2000.00",
        "transactionDate": "12/03/2026"
    },
    {
        "creditDebitType": "CREDITO",
        "transactionName": "PIX RECEBIDO",
        "historicComplement": "CPF",
        "amount": "3000.00",
        "transactionDate": "12/03/2026"
    },
    {
        "creditDebitType": "DEBITO",
        "transactionName": "PREST. DE EMPREST.",
        "historicComplement": "PARC 002/024",
        "amount": "326.94",
        "transactionDate": "11/03/2026"
    }
]

📈 Estrutura

O projeto possui a seguinte estrutura:

openfinance_santander_integration/ 
│  
├── openfinance_santander_balance.py 
├── openfinance_santander_statement.py 
│  
├── certificates/  
│   ├── client.pem  
│   └── client.key  
| 
├── data/   
│  
├── .env/  
├── .gitignore  
├── README.md  
└── LICENSE  

⚙️ Como Usar

1. Instalar dependências

    pip install requests
    pip install python-dotenv

2. Configurar variáveis de ambiente

   Crie um arquivo .env na raiz do projeto contendo:

   CLIENT_ID     = seu_client_id
   CLIENT_SECRET = seu_client_secret
   CLIENT_CERT   = certificates/client.pem
   CLIENT_KEY    = certificates/client.key
   BANK_ID       = cnpj_do_banco
   ACCOUNT_ID    = agencia.conta

   As credenciais CLIENT_ID e CLIENT_SECRETsão fornecidas no portal Santander Developers ao registrar uma aplicação (no modo produção).

3. Configurar certificados

   Coloque os arquivos de certificado digital da empresa na pasta:

   certificates/client.pem
   certificates/client.key

4. Executar o script

   Para consultar saldo execute:

   python openfinance_santander_balance.py

   Para consultar extrato execute:

   python openfinance_santander_statement.py

   Os resultados são exportados automaticamente para a pasta data/

📌 Observações

• Este projeto possui finalidade educacional e de experimentação com APIs bancárias.
• A estrutura pode ser facilmente adaptada para:
  • integração com outros bancos participantes do Open Finance;
  • automação de coleta de dados financeiros;
  • armazenamento em banco de dados;
  • criação de dashboards financeiros.
• Contribuições são bem-vindas. Abra uma issue ou envie um pull request caso queira sugerir melhorias.