bench get-app https://github.com/Solede-SA/solede_openbanking

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=Solede-SA%2Fsolede_openbanking)](https://frappegems.com/gems/apps/Solede-SA/solede_openbanking)

Solede OpenBanking

Frappe app per l'integrazione con ACube Open Banking API. Questa app permette di integrare le tue aziende ERPNext con le banche europee attraverso gli standard PSD2 Open Banking.

✨ Funzionalità

Gestione Autenticazione

• Token JWT Automatico - Generazione e rinnovo automatico dei token (validità 24 ore)
• Decodifica Token - Visualizzazione dettagli token per debugging
• Credenziali Sicure - Password crittografate usando i meccanismi di sicurezza di Frappe

Business Registry

• Creazione Business Registry - Registrazione azienda presso ACube Open Banking
• Gestione per Company - Configurazione separata per ogni azienda ERPNext
• Info Registry - Visualizzazione dettagli completi del Business Registry

Connessioni Bancarie

• Flusso OAuth - Connessione sicura con autorizzazione bancaria
• Multi-Account - Supporto per più account bancari per azienda
• Gestione Account - Abilitazione/disabilitazione account autorizzati
• Eliminazione Account - Rimozione completa delle connessioni bancarie
• Test Mode - Ambiente sandbox con banche fake per test

Transazioni Bancarie

• Import Transazioni - Importazione automatica movimenti bancari in Bank Transaction
• Filtri Avanzati - Ricerca per data, account, importo
• Transaction Log - Tracciamento completo di tutte le operazioni
• Riconciliazione - Integrazione nativa con Bank Reconciliation Tool di ERPNext
• Dati Completi - Salvataggio raw data JSON per audit e debugging

Pagamenti SEPA

• Bonifici da Purchase Invoice - Esegui pagamenti SEPA direttamente da fatture fornitori
• SEPA Instant - Supporto bonifici istantanei (completati in pochi secondi)
• Validazione SEPA - Controllo automatico paese IBAN per bonifici SEPA
• IBAN Enrichment - Creazione automatica Bank/Bank Account da IBAN
• Payment Entry Automatico - Creazione automatica Payment Entry da webhook con status confirmed
• Associazione Banca Corretta - Il Payment Entry usa il conto bancario effettivo del pagamento (lookup IBAN)
• Callback Page - Pagina di ritorno dopo autorizzazione pagamento
• Mode of Payment Configurabile - Modalità pagamento configurabile per ogni company
• Tracking Completo - Tracciamento UUID e End-to-End ID per ogni pagamento

Reporting

• Authorized Bank Accounts Report - Visualizzazione conti autorizzati in sola lettura
• Ordinamento per Balance - Conti ordinati per saldo decrescente
• Permessi Granulari - Accesso report anche per utenti non amministratori
• Workspace Dedicato - Interfaccia centralizzata per tutte le operazioni

UI/UX

• Interfaccia Intuitiva - Pulsanti contestuali e dropdown organizzati
• Modal con Dettagli - Visualizzazione completa dati API per ogni account
• Auto-Return URL - Redirect automatico dopo autorizzazione bancaria
• Validazione Password - Controlli pattern per password Business Registry

📋 Requisiti

• Frappe Framework v15+
• ERPNext v15+
• Python 3.10+
• Account ACube Open Banking valido
• Company con Partita IVA (Tax ID) configurata

🚀 Installazione

1. Scarica l'app da GitHub

cd frappe-bench
bench get-app https://github.com/Solede-SA/solede_openbanking.git

2. Installa sul sito

bench --site your-site.local install-app solede_openbanking

3. Migra il database

bench --site your-site.local migrate

4. Riavvia il bench

bench restart

⚙️ Configurazione

1. Configurazione Company

Prima di tutto, assicurati che il documento Company abbia: - Tax ID (Partita IVA) configurato correttamente - Company Name compilato

Questi dati verranno usati per creare il Business Registry.

2. OpenBanking Settings

Naviga in OpenBanking > OpenBanking Settings e crea un nuovo documento:

Configurazione API

• Company: Seleziona la tua azienda
• Common API URL: Endpoint autenticazione
  • Sandbox: https://common-sandbox.api.acubeapi.com
  • Production: https://common.api.acubeapi.com
• Open Banking API URL: Endpoint operazioni
  • Sandbox: https://ob-sandbox.api.acubeapi.com
  • Production: https://ob.api.acubeapi.com

Credenziali

• Email: Email del tuo account ACube
• Password: Password del tuo account ACube

Configurazione Pagamenti (opzionale)

• Callback Base URL: URL pubblico per callback pagamenti
  • Sandbox: https://your-ngrok-url.ngrok.io
  • Production: https://your-domain.com
• Mode of Payment: Modalità di pagamento per Payment Entry automatici
  • Seleziona un Mode of Payment esistente (es. "Bonifico Bancario")

Configurazione IBAN Validation API (opzionale)

• IBAN API Provider: Provider per validazione IBAN
  • Opzioni: iban.com, ibanapi.com, api-ninjas
• IBAN API Key: Chiave API del provider selezionato

📖 Guida all'Uso

Step 1: Genera Token

1. Apri il documento OpenBanking Settings della tua Company
2. Clicca Generate Token
3. Il token verrà generato e salvato automaticamente
4. Puoi visualizzare i dettagli del token nella sezione "Token Information"

Il token ha validità di 24 ore e viene rinnovato automaticamente quando necessario.

Step 2: Crea Business Registry

1. Clicca Actions > Create Business Registry
2. Inserisci l'email dell'azienda da associare al Business Registry (riceverà alert e notifiche)
3. Conferma la creazione

⚠️ Attenzione: Questa operazione comporta un addebito da parte di ACube.

Il sistema userà: - Fiscal ID: dalla Partita IVA della Company - Business Name: dal nome della Company - Email: quella inserita dall'operatore nel dialog (specifica per l'azienda, diversa dalle credenziali ACube)

Step 3: Connetti Banca

1. Clicca Actions > Connect Bank Account
2. Configura i parametri (opzionali):
   • Bank Manager Email: Email del responsabile
   • Consent Days: Durata consenso (1-180 giorni, default: 180)
   • Test Mode: Attiva per usare banca fake in sandbox
3. Clicca Connect

Si aprirà una nuova finestra dove potrai: 1. Selezionare la banca 2. Autenticarti con le credenziali bancarie 3. Autorizzare l'accesso agli account

Il sistema usa automaticamente l'URL corrente come return URL.

Step 4: Aggiorna Lista Account

Dopo aver completato l'autorizzazione: 1. Clicca Refresh Accounts 2. Gli account autorizzati verranno mostrati nella tab "Authorized Bank Accounts"

Per ogni account puoi: - View Details: Visualizzare tutti i dati dell'account - Enable/Disable: Abilitare o disabilitare l'account - Delete: Eliminare la connessione (solo se disabilitato)

Step 5: Importa Transazioni

1. Naviga in OpenBanking > OpenBanking Settings
2. Clicca Actions > Import Transactions
3. Configura i filtri:
   • Account: Seleziona un account specifico o lascia vuoto per tutti
   • From Date: Data inizio
   • To Date: Data fine
4. Clicca Import

Le transazioni verranno importate in: - Bank Transaction: Per la riconciliazione - ACube Transaction Log: Per il tracciamento

Step 6: Esegui Bonifici SEPA

Da Purchase Invoice

1. Crea una Purchase Invoice e fai Submit
2. Assicurati che abbia un outstanding_amount > 0
3. Clicca OpenBanking > Esegui Bonifico
4. Il sistema verifica/crea il Bank Account del fornitore:
   • Se il fornitore ha già un IBAN configurato: selezionalo o inseriscine uno nuovo
   • Se non ha IBAN: inserisci l'IBAN del fornitore
   • Il sistema validerà l'IBAN e creerà automaticamente Bank e Bank Account
5. Configura il pagamento:
   • Conto da cui pagare: Seleziona l'account OpenBanking (solo account con supporto pagamenti SEPA)
   • IBAN Fornitore: IBAN destinatario (deve essere paese SEPA)
   • Bonifico Istantaneo: Spunta per SEPA Instant (max €100.000)
6. Clicca Avvia Bonifico
7. Si apre una finestra per autorizzare il pagamento presso la banca
8. Dopo l'autorizzazione, il sistema:
   • Crea un documento OpenBanking Payment con status "pending"
   • Quando la banca completa il pagamento, ACube invia un webhook
   • Il webhook crea automaticamente un Payment Entry con Mode of Payment configurato
   • La Purchase Invoice viene marcata come Paid

Monitoraggio Pagamento

• Nella Purchase Invoice vedrai lo status del pagamento
• Clicca OpenBanking > Aggiorna Status per controllare manualmente
• Il documento OpenBanking Payment mostra tutti i dettagli (UUID, End-to-End ID, status)

Stati Pagamento

• pending: Pagamento inizializzato, in attesa autorizzazione
• requested: Autorizzazione completata, in elaborazione
• processing: Pagamento in corso
• confirmed: Pagamento confermato dalla banca (Payment Entry creato automaticamente)
• failed: Pagamento fallito
• cancelled: Pagamento annullato (solo lato sistema, non presso la banca)

Gestione Pagamenti Bloccati (PENDING/FAILED)

Se un pagamento rimane in stato pending o failed, hai a disposizione diverse opzioni:

1. Riprova Pagamento - Riapre l'URL di autorizzazione presso la banca - Utile se l'utente non ha completato l'autorizzazione o la finestra si è chiusa - Clicca OpenBanking > Riprova Pagamento dalla Purchase Invoice - Si aprirà una nuova finestra per completare l'autorizzazione - Dopo aver completato, clicca Aggiorna Status per verificare l'esito

2. Annulla Pagamento - Cambia lo stato del pagamento a cancelled - Sblocca la fattura permettendo di creare un nuovo pagamento - Clicca OpenBanking > Annulla Pagamento dalla Purchase Invoice - Conferma nel dialog (include warning che l'annullamento è solo locale) - Il bottone Esegui Bonifico riapparirà per creare un nuovo pagamento

3. Aggiorna Status - Interroga l'API ACube per ottenere lo status aggiornato del pagamento - Clicca OpenBanking > Aggiorna Status dalla Purchase Invoice - Lo status locale verrà sincronizzato con quello del sistema bancario

Nota importante: L'operazione "Annulla Pagamento" annulla SOLO il record locale nel sistema. Se il pagamento è già stato autorizzato presso la banca, NON verrà annullato automaticamente. In quel caso, dovrai procedere manualmente tramite il portale della banca.

Visualizza Report

Naviga in OpenBanking Workspace e clicca su Authorized Bank Accounts per visualizzare tutti gli account autorizzati ordinati per saldo decrescente.

Il report è accessibile anche a utenti con ruolo "Accounts User" o "Accounts Manager".

📁 Struttura

``` soledeopenbanking/ ├── api/ │ ├── authentication.py # Gestione JWT token │ ├── businessregistry.py # Business Registry e operazioni │ ├── client.py # Client API centralizzato │ ├── payments.py # Gestione pagamenti SEPA │ ├── ibanenrichment.py # Validazione e enrichment IBAN │ ├── webhooks.py # Gestione webhook ACube │ └── utils.py # Utility functions ├── soledeopenbanking/ │ ├── doctype/ │ │ ├── openbankingsettings/ │ │ │ ├── openbankingsettings.json │ │ │ ├── openbankingsettings.py │ │ │ └── openbankingsettings.js │ │ ├── openbankingaccount/ │ │ │ ├── openbankingaccount.json │ │ │ └── openbankingaccount.py │ │ ├── openbankingpayment/ │ │ │ ├── openbankingpayment.json │ │ │ └── openbankingpayment.py │ │ ├── acubetransactionlog/ │ │ │ ├── acubetransactionlog.json │ │ │ └── acubetransactionlog.py │ │ └── acubewebhooklog/ │ │ ├── acubewebhooklog.json │ │ └── acubewebhooklog.py │ ├── report/ │ │ └── authorizedbankaccounts/ │ │