{"id":32497528,"url":"https://github.com/solede-sa/solede_openbanking","last_synced_at":"2026-05-14T19:32:45.262Z","repository":{"id":320996674,"uuid":"1075445021","full_name":"Solede-SA/solede_openbanking","owner":"Solede-SA","description":"Open Banking integration for ERPNext - Connect banks, import transactions, and process SEPA payments via PSD2 APIs","archived":false,"fork":false,"pushed_at":"2025-10-27T06:09:16.000Z","size":282,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"develop","last_synced_at":"2025-10-27T08:12:45.072Z","etag":null,"topics":["banking","erpnext","frappe","frappe-framework","openbanking","payments","psd2","sepa"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Solede-SA.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-13T14:06:25.000Z","updated_at":"2025-10-27T06:17:29.000Z","dependencies_parsed_at":"2025-10-27T08:12:51.123Z","dependency_job_id":"3f53da11-1650-48a5-ad6d-27ee62240874","html_url":"https://github.com/Solede-SA/solede_openbanking","commit_stats":null,"previous_names":["solede-sa/solede_openbanking"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/Solede-SA/solede_openbanking","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Solede-SA%2Fsolede_openbanking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Solede-SA%2Fsolede_openbanking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Solede-SA%2Fsolede_openbanking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Solede-SA%2Fsolede_openbanking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Solede-SA","download_url":"https://codeload.github.com/Solede-SA/solede_openbanking/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Solede-SA%2Fsolede_openbanking/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281287154,"owners_count":26475269,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-27T02:00:05.855Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["banking","erpnext","frappe","frappe-framework","openbanking","payments","psd2","sepa"],"created_at":"2025-10-27T15:00:13.468Z","updated_at":"2026-05-14T19:32:45.254Z","avatar_url":"https://github.com/Solede-SA.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Solede OpenBanking\n\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)\n[![Frappe](https://img.shields.io/badge/Frappe-v15+-orange.svg)](https://github.com/frappe/frappe)\n[![ERPNext](https://img.shields.io/badge/ERPNext-v15+-blue.svg)](https://github.com/frappe/erpnext)\n\nFrappe 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.\n\n## ✨ Funzionalità\n\n### Gestione Autenticazione\n- **Token JWT Automatico** - Generazione e rinnovo automatico dei token (validità 24 ore)\n- **Decodifica Token** - Visualizzazione dettagli token per debugging\n- **Credenziali Sicure** - Password crittografate usando i meccanismi di sicurezza di Frappe\n\n### Business Registry\n- **Creazione Business Registry** - Registrazione azienda presso ACube Open Banking\n- **Gestione per Company** - Configurazione separata per ogni azienda ERPNext\n- **Info Registry** - Visualizzazione dettagli completi del Business Registry\n\n### Connessioni Bancarie\n- **Flusso OAuth** - Connessione sicura con autorizzazione bancaria\n- **Multi-Account** - Supporto per più account bancari per azienda\n- **Gestione Account** - Abilitazione/disabilitazione account autorizzati\n- **Eliminazione Account** - Rimozione completa delle connessioni bancarie\n- **Test Mode** - Ambiente sandbox con banche fake per test\n\n### Transazioni Bancarie\n- **Import Transazioni** - Importazione automatica movimenti bancari in Bank Transaction\n- **Filtri Avanzati** - Ricerca per data, account, importo\n- **Transaction Log** - Tracciamento completo di tutte le operazioni\n- **Riconciliazione** - Integrazione nativa con Bank Reconciliation Tool di ERPNext\n- **Dati Completi** - Salvataggio raw data JSON per audit e debugging\n\n### Pagamenti SEPA\n- **Bonifici da Purchase Invoice** - Esegui pagamenti SEPA direttamente da fatture fornitori\n- **SEPA Instant** - Supporto bonifici istantanei (completati in pochi secondi)\n- **Validazione SEPA** - Controllo automatico paese IBAN per bonifici SEPA\n- **IBAN Enrichment** - Creazione automatica Bank/Bank Account da IBAN\n- **Payment Entry Automatico** - Creazione automatica Payment Entry da webhook con status `confirmed`\n- **Associazione Banca Corretta** - Il Payment Entry usa il conto bancario effettivo del pagamento (lookup IBAN)\n- **Callback Page** - Pagina di ritorno dopo autorizzazione pagamento\n- **Mode of Payment Configurabile** - Modalità pagamento configurabile per ogni company\n- **Tracking Completo** - Tracciamento UUID e End-to-End ID per ogni pagamento\n\n### Reporting\n- **Authorized Bank Accounts Report** - Visualizzazione conti autorizzati in sola lettura\n- **Ordinamento per Balance** - Conti ordinati per saldo decrescente\n- **Permessi Granulari** - Accesso report anche per utenti non amministratori\n- **Workspace Dedicato** - Interfaccia centralizzata per tutte le operazioni\n\n### UI/UX\n- **Interfaccia Intuitiva** - Pulsanti contestuali e dropdown organizzati\n- **Modal con Dettagli** - Visualizzazione completa dati API per ogni account\n- **Auto-Return URL** - Redirect automatico dopo autorizzazione bancaria\n- **Validazione Password** - Controlli pattern per password Business Registry\n\n## 📋 Requisiti\n\n- Frappe Framework v15+\n- ERPNext v15+\n- Python 3.10+\n- Account ACube Open Banking valido\n- Company con Partita IVA (Tax ID) configurata\n\n## 🚀 Installazione\n\n### 1. Scarica l'app da GitHub\n\n```bash\ncd frappe-bench\nbench get-app https://github.com/Solede-SA/solede_openbanking.git\n```\n\n### 2. Installa sul sito\n\n```bash\nbench --site your-site.local install-app solede_openbanking\n```\n\n### 3. Migra il database\n\n```bash\nbench --site your-site.local migrate\n```\n\n### 4. Riavvia il bench\n\n```bash\nbench restart\n```\n\n## ⚙️ Configurazione\n\n### 1. Configurazione Company\n\nPrima di tutto, assicurati che il documento **Company** abbia:\n- **Tax ID** (Partita IVA) configurato correttamente\n- **Company Name** compilato\n\nQuesti dati verranno usati per creare il Business Registry.\n\n### 2. OpenBanking Settings\n\nNaviga in **OpenBanking \u003e OpenBanking Settings** e crea un nuovo documento:\n\n#### Configurazione API\n- **Company**: Seleziona la tua azienda\n- **Common API URL**: Endpoint autenticazione\n  - Sandbox: `https://common-sandbox.api.acubeapi.com`\n  - Production: `https://common.api.acubeapi.com`\n- **Open Banking API URL**: Endpoint operazioni\n  - Sandbox: `https://ob-sandbox.api.acubeapi.com`\n  - Production: `https://ob.api.acubeapi.com`\n\n#### Credenziali\n- **Email**: Email del tuo account ACube\n- **Password**: Password del tuo account ACube\n\n#### Configurazione Pagamenti (opzionale)\n- **Callback Base URL**: URL pubblico per callback pagamenti\n  - Sandbox: `https://your-ngrok-url.ngrok.io`\n  - Production: `https://your-domain.com`\n- **Mode of Payment**: Modalità di pagamento per Payment Entry automatici\n  - Seleziona un Mode of Payment esistente (es. \"Bonifico Bancario\")\n\n#### Configurazione IBAN Validation API (opzionale)\n- **IBAN API Provider**: Provider per validazione IBAN\n  - Opzioni: iban.com, ibanapi.com, api-ninjas\n- **IBAN API Key**: Chiave API del provider selezionato\n\n## 📖 Guida all'Uso\n\n### Step 1: Genera Token\n\n1. Apri il documento **OpenBanking Settings** della tua Company\n2. Clicca **Generate Token**\n3. Il token verrà generato e salvato automaticamente\n4. Puoi visualizzare i dettagli del token nella sezione \"Token Information\"\n\nIl token ha validità di 24 ore e viene rinnovato automaticamente quando necessario.\n\n### Step 2: Crea Business Registry\n\n1. Clicca **Actions \u003e Create Business Registry**\n2. Inserisci l'**email dell'azienda** da associare al Business Registry (riceverà alert e notifiche)\n3. Conferma la creazione\n\n⚠️ **Attenzione**: Questa operazione comporta un addebito da parte di ACube.\n\nIl sistema userà:\n- **Fiscal ID**: dalla Partita IVA della Company\n- **Business Name**: dal nome della Company\n- **Email**: quella inserita dall'operatore nel dialog (specifica per l'azienda, diversa dalle credenziali ACube)\n\n### Step 3: Connetti Banca\n\n1. Clicca **Actions \u003e Connect Bank Account**\n2. Configura i parametri (opzionali):\n   - **Bank Manager Email**: Email del responsabile\n   - **Consent Days**: Durata consenso (1-180 giorni, default: 180)\n   - **Test Mode**: Attiva per usare banca fake in sandbox\n3. Clicca **Connect**\n\nSi aprirà una nuova finestra dove potrai:\n1. Selezionare la banca\n2. Autenticarti con le credenziali bancarie\n3. Autorizzare l'accesso agli account\n\nIl sistema usa automaticamente l'URL corrente come return URL.\n\n### Step 4: Aggiorna Lista Account\n\nDopo aver completato l'autorizzazione:\n1. Clicca **Refresh Accounts**\n2. Gli account autorizzati verranno mostrati nella tab \"Authorized Bank Accounts\"\n\nPer ogni account puoi:\n- **View Details**: Visualizzare tutti i dati dell'account\n- **Enable/Disable**: Abilitare o disabilitare l'account\n- **Delete**: Eliminare la connessione (solo se disabilitato)\n\n### Step 5: Importa Transazioni\n\n1. Naviga in **OpenBanking \u003e OpenBanking Settings**\n2. Clicca **Actions \u003e Import Transactions**\n3. Configura i filtri:\n   - **Account**: Seleziona un account specifico o lascia vuoto per tutti\n   - **From Date**: Data inizio\n   - **To Date**: Data fine\n4. Clicca **Import**\n\nLe transazioni verranno importate in:\n- **Bank Transaction**: Per la riconciliazione\n- **ACube Transaction Log**: Per il tracciamento\n\n### Step 6: Esegui Bonifici SEPA\n\n#### Da Purchase Invoice\n\n1. Crea una Purchase Invoice e fai Submit\n2. Assicurati che abbia un `outstanding_amount \u003e 0`\n3. Clicca **OpenBanking \u003e Esegui Bonifico**\n4. Il sistema verifica/crea il Bank Account del fornitore:\n   - Se il fornitore ha già un IBAN configurato: selezionalo o inseriscine uno nuovo\n   - Se non ha IBAN: inserisci l'IBAN del fornitore\n   - Il sistema validerà l'IBAN e creerà automaticamente Bank e Bank Account\n5. Configura il pagamento:\n   - **Conto da cui pagare**: Seleziona l'account OpenBanking (solo account con supporto pagamenti SEPA)\n   - **IBAN Fornitore**: IBAN destinatario (deve essere paese SEPA)\n   - **Bonifico Istantaneo**: Spunta per SEPA Instant (max €100.000)\n6. Clicca **Avvia Bonifico**\n7. Si apre una finestra per autorizzare il pagamento presso la banca\n8. Dopo l'autorizzazione, il sistema:\n   - Crea un documento **OpenBanking Payment** con status \"pending\"\n   - Quando la banca completa il pagamento, ACube invia un webhook\n   - Il webhook crea automaticamente un **Payment Entry** con Mode of Payment configurato\n   - La Purchase Invoice viene marcata come **Paid**\n\n#### Monitoraggio Pagamento\n\n- Nella Purchase Invoice vedrai lo status del pagamento\n- Clicca **OpenBanking \u003e Aggiorna Status** per controllare manualmente\n- Il documento OpenBanking Payment mostra tutti i dettagli (UUID, End-to-End ID, status)\n\n#### Stati Pagamento\n\n- **pending**: Pagamento inizializzato, in attesa autorizzazione\n- **requested**: Autorizzazione completata, in elaborazione\n- **processing**: Pagamento in corso\n- **confirmed**: Pagamento confermato dalla banca (Payment Entry creato automaticamente)\n- **failed**: Pagamento fallito\n- **cancelled**: Pagamento annullato (solo lato sistema, non presso la banca)\n\n#### Gestione Pagamenti Bloccati (PENDING/FAILED)\n\nSe un pagamento rimane in stato `pending` o `failed`, hai a disposizione diverse opzioni:\n\n**1. Riprova Pagamento**\n- Riapre l'URL di autorizzazione presso la banca\n- Utile se l'utente non ha completato l'autorizzazione o la finestra si è chiusa\n- Clicca **OpenBanking \u003e Riprova Pagamento** dalla Purchase Invoice\n- Si aprirà una nuova finestra per completare l'autorizzazione\n- Dopo aver completato, clicca **Aggiorna Status** per verificare l'esito\n\n**2. Annulla Pagamento**\n- Cambia lo stato del pagamento a `cancelled`\n- Sblocca la fattura permettendo di creare un nuovo pagamento\n- Clicca **OpenBanking \u003e Annulla Pagamento** dalla Purchase Invoice\n- Conferma nel dialog (include warning che l'annullamento è solo locale)\n- Il bottone **Esegui Bonifico** riapparirà per creare un nuovo pagamento\n\n**3. Aggiorna Status**\n- Interroga l'API ACube per ottenere lo status aggiornato del pagamento\n- Clicca **OpenBanking \u003e Aggiorna Status** dalla Purchase Invoice\n- Lo status locale verrà sincronizzato con quello del sistema bancario\n\n**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.\n\n### Visualizza Report\n\nNaviga in **OpenBanking Workspace** e clicca su **Authorized Bank Accounts** per visualizzare tutti gli account autorizzati ordinati per saldo decrescente.\n\nIl report è accessibile anche a utenti con ruolo \"Accounts User\" o \"Accounts Manager\".\n\n## 📁 Struttura\n\n```\nsolede_openbanking/\n├── api/\n│   ├── authentication.py        # Gestione JWT token\n│   ├── business_registry.py     # Business Registry e operazioni\n│   ├── client.py                # Client API centralizzato\n│   ├── payments.py              # Gestione pagamenti SEPA\n│   ├── iban_enrichment.py       # Validazione e enrichment IBAN\n│   ├── webhooks.py              # Gestione webhook ACube\n│   └── utils.py                 # Utility functions\n├── solede_openbanking/\n│   ├── doctype/\n│   │   ├── openbanking_settings/\n│   │   │   ├── openbanking_settings.json\n│   │   │   ├── openbanking_settings.py\n│   │   │   └── openbanking_settings.js\n│   │   ├── openbanking_account/\n│   │   │   ├── openbanking_account.json\n│   │   │   └── openbanking_account.py\n│   │   ├── openbanking_payment/\n│   │   │   ├── openbanking_payment.json\n│   │   │   └── openbanking_payment.py\n│   │   ├── acube_transaction_log/\n│   │   │   ├── acube_transaction_log.json\n│   │   │   └── acube_transaction_log.py\n│   │   └── acube_webhook_log/\n│   │       ├── acube_webhook_log.json\n│   │       └── acube_webhook_log.py\n│   ├── report/\n│   │   └── authorized_bank_accounts/\n│   │       ├── authorized_bank_accounts.json\n│   │       └── authorized_bank_accounts.py\n│   └── workspace/\n│       └── openbanking/\n│           └── openbanking.json\n├── public/\n│   └── js/\n│       ├── openbanking_helpers.js  # Helper JavaScript\n│       ├── purchase_invoice.js     # Client-side pagamenti Purchase Invoice\n│       ├── supplier.js             # Validazione IBAN fornitore\n│       └── bank_transaction.js     # Arricchimento transazioni\n├── templates/\n│   └── pages/\n│       ├── payment_callback.py     # Callback page pagamenti\n│       └── payment_callback.html   # Template callback\n├── fixtures/                       # Custom fields e configurazioni\n├── hooks.py\n└── README.md\n```\n\n## 🔌 API Endpoints\n\n### Autenticazione\n| Endpoint | Method | Descrizione |\n|----------|--------|-------------|\n| `/login` | POST | Genera token JWT |\n\n### Business Registry\n| Endpoint | Method | Descrizione |\n|----------|--------|-------------|\n| `/business-registry` | POST | Crea Business Registry |\n| `/business-registry/{fiscalId}` | GET | Info Business Registry |\n| `/business-registry/{fiscalId}/connect` | POST | Avvia connessione banca |\n\n### Account\n| Endpoint | Method | Descrizione |\n|----------|--------|-------------|\n| `/business-registry/{fiscalId}/accounts` | GET | Lista account autorizzati |\n| `/accounts/{uuid}` | PUT | Abilita/disabilita account |\n| `/accounts/{uuid}` | DELETE | Elimina account |\n\n### Transazioni\n| Endpoint | Method | Descrizione |\n|----------|--------|-------------|\n| `/business-registry/{fiscalId}/transactions` | GET | Recupera transazioni |\n\n### Pagamenti\n| Endpoint | Method | Descrizione |\n|----------|--------|-------------|\n| `/payments/send/sepa` | POST | Invia bonifico SEPA |\n| `/payments/send/sepa-instant` | POST | Invia bonifico SEPA Instant |\n| `/payments/{uuid}` | GET | Recupera status pagamento |\n\n### Webhook\n| Endpoint | Method | Descrizione |\n|----------|--------|-------------|\n| `/api/method/solede_openbanking.api.webhooks.acube_webhook` | POST | Riceve webhook da ACube |\n\n## 🔐 Sicurezza\n\n- **Password Crittografate**: Uso del campo Password di Frappe per crittografia automatica\n- **Token JWT**: Autenticazione Bearer token per tutte le chiamate API\n- **Raw Data Storage**: Salvataggio completo JSON per audit trail\n- **Validazione Campi**: Controlli pattern per email, password e altri campi critici\n\n## 🎨 Principi di Design\n\nQuesta app segue rigorosamente i principi:\n\n- **DRY (Don't Repeat Yourself)**: Codice riutilizzabile e modulare\n- **KISS (Keep It Simple, Stupid)**: Soluzioni semplici e dirette\n- **No Fallback**: Gli errori vengono sempre mostrati all'utente senza sistemi di fallback\n- **Explicit Errors**: Messaggi di errore chiari e dettagliati\n\n## 🗃️ Modello Dati\n\n### OpenBanking Settings (DocType)\nConfigurazione principale per ogni Company.\n\n**Campi principali:**\n- `company` (Link): Company di riferimento\n- `api_url` (Data): URL API Common\n- `openbanking_api_url` (Data): URL API Open Banking\n- `email` (Data): Email account ACube\n- `password` (Password): Password crittografata\n- `business_registry_created` (Check): Flag creazione registry\n- `access_token` (Long Text): Token JWT corrente\n- `token_created_at` (Datetime): Data creazione token\n- `token_expires_at` (Datetime): Data scadenza token\n- `callback_base_url` (Data): URL base per callback pagamenti\n- `payment_mode_of_payment` (Link): Mode of Payment per Payment Entry automatici\n- `accounts` (Table): Child table con account autorizzati\n\n### OpenBanking Account (Child Table)\nAccount bancari autorizzati.\n\n**Campi principali:**\n- `uuid` (Data): Identificativo univoco ACube\n- `iban` (Data): IBAN account\n- `bank_display` (Data): Nome banca\n- `balance_display` (Data): Saldo formattato\n- `enabled` (Check): Stato attivo/disattivo\n- `raw_data` (Long Text): JSON completo da API (include campo \"systems\" con capabilities pagamenti)\n\n### OpenBanking Payment (DocType)\nTracciamento pagamenti SEPA.\n\n**Campi principali:**\n- `uuid` (Data): UUID pagamento da ACube\n- `payment_direction` (Select): outbound/inbound\n- `status` (Data): pending/requested/processing/confirmed/failed/cancelled\n- `system` (Select): sepa/sepa-instant\n- `amount` (Currency): Importo pagamento\n- `currency_code` (Data): Valuta (default EUR)\n- `description` (Small Text): Descrizione pagamento\n- `reference_doctype` (Link): DocType di riferimento (es. Purchase Invoice)\n- `reference_name` (Dynamic Link): Nome documento di riferimento\n- `company` (Link): Company\n- `supplier` (Link): Fornitore\n- `creditor_name` (Data): Nome beneficiario\n- `creditor_iban` (Data): IBAN beneficiario\n- `account_uuid` (Data): UUID account OpenBanking debitore\n- `connect_url` (Data): URL autorizzazione pagamento\n- `end_to_end_id` (Data): End-to-End ID transazione\n- `error_message` (Text): Messaggio errore se failed\n- `raw_response` (Code): Risposta completa API JSON\n\n### ACube Transaction Log (DocType)\nLog di tutte le transazioni importate.\n\n**Campi principali:**\n- `company` (Link): Company\n- `bank_account` (Link): Bank Account ERPNext\n- `acube_account_uuid` (Data): UUID account ACube\n- `transaction_date` (Date): Data transazione\n- `acube_transaction_id` (Data): ID transazione ACube\n- `transaction_status` (Data): Stato transazione\n- `amount` (Currency): Importo\n- `currency` (Link): Valuta\n- `import_status` (Select): Pending/Imported/Failed\n- `bank_transaction` (Link): Link a Bank Transaction\n- `error_message` (Text): Messaggio errore se fallita\n- `raw_data` (Long Text): JSON completo\n\n### Custom Fields su Payment Entry\nL'app aggiunge campi custom a Payment Entry:\n\n- `custom_openbanking_payment` (Link): Collegamento al documento OpenBanking Payment\n\n### Custom Fields su Bank Transaction\nL'app aggiunge campi custom a Bank Transaction:\n\n- `acube_section` (Section Break): Sezione dati ACube\n- `acube_transaction_id` (Data): ID transazione univoco\n- `api_source` (Data): Fonte (sempre \"ACube\")\n- `acube_booking_date` (Date): Data registrazione\n- `acube_value_date` (Date): Data valuta\n- `acube_status` (Data): Stato transazione\n- `acube_category` (Data): Categoria\n- `acube_raw_data` (Long Text): Dati completi JSON\n\n## 🔧 Funzioni API Principali\n\n### authentication.py\n\n```python\ngenerate_token(company)\n# Genera nuovo token JWT\n\nget_valid_token(company)\n# Ottiene token valido (rinnova se scaduto)\n\ndecode_token_payload(token)\n# Decodifica payload JWT per debug\n```\n\n### business_registry.py\n\n```python\ncreate_business_registry(company, business_email)\n# Crea Business Registry con email specifica per l'azienda\n\nget_business_registry_info(company)\n# Recupera info Business Registry\n\nstart_connect_request(company, return_url, bank_manager_email, days, test_mode)\n# Avvia connessione bancaria\n\nget_accounts(company)\n# Recupera account autorizzati\n\ntoggle_account(company, uuid, enabled)\n# Abilita/disabilita account\n\ndelete_account(company, uuid)\n# Elimina account\n\nimport_transactions(company, account_uuid, from_date, to_date)\n# Importa transazioni in Bank Transaction\n```\n\n### payments.py\n\n```python\nget_supplier_bank_accounts(supplier_name)\n# Recupera Bank Account del fornitore\n\nget_company_openbanking_accounts(company)\n# Recupera account OpenBanking con capabilities pagamenti\n\ninitiate_sepa_payment(reference_doctype, reference_name, account_uuid,\n                     creditor_iban, creditor_name, use_instant)\n# Avvia pagamento SEPA/SEPA Instant\n# Valida IBAN paese SEPA e capabilities account\n\nget_payment_status(payment_uuid)\n# Aggiorna status pagamento da API\n\ncancel_payment(payment_name)\n# Annulla un pagamento OpenBanking (solo lato sistema)\n# Cambia status a 'cancelled' per sbloccare la fattura\n# Permette solo su pagamenti pending/requested/failed\n\ncreate_or_get_supplier_bank_account(supplier_name, iban, account_name)\n# Crea/recupera Bank Account fornitore da IBAN\n```\n\n### webhooks.py\n\n```python\nacube_webhook()\n# Endpoint pubblico per ricevere webhook ACube\n# Gestisce eventi: connect, reconnect, payment\n\nhandle_payment_webhook(payload, company, log_name)\n# Gestisce webhook pagamento\n# Crea automaticamente Payment Entry se status = \"confirmed\"\n\ncreate_payment_entry_from_payment(payment_doc)\n# Crea Payment Entry da OpenBanking Payment\n# Associa il conto bancario corretto (lookup IBAN da account_uuid)\n# Usa Mode of Payment da settings\n```\n\n### client.py\n\n```python\nclass ACubeAPIClient:\n    # Client centralizzato per chiamate API\n    # Gestisce automaticamente:\n    # - Autenticazione token\n    # - Headers comuni\n    # - Error handling\n    # - Logging\n```\n\n## 🌍 Ambienti\n\n### Sandbox (Testing)\n- **Common API**: `https://common-sandbox.api.acubeapi.com`\n- **OpenBanking API**: `https://ob-sandbox.api.acubeapi.com`\n- Usa **Test Mode** per connetterti a banche fake (country code: XF)\n\n### Production\n- **Common API**: `https://common.api.acubeapi.com`\n- **OpenBanking API**: `https://ob.api.acubeapi.com`\n- Banche reali italiane (country code: IT)\n\n## 🐛 Troubleshooting\n\n### Il token non viene generato\n- Verifica che email e password siano corretti\n- Controlla che gli URL API siano configurati correttamente\n- Verifica i log di sistema per errori dettagliati\n\n### Business Registry fallisce\n- Assicurati che la Company abbia Tax ID configurato\n- Verifica che il formato Tax ID sia valido (Partita IVA italiana)\n- Controlla di avere credito sufficiente su ACube\n\n### Connessione banca non funziona\n- Verifica che il Business Registry sia stato creato\n- Controlla che la finestra popup non sia bloccata dal browser\n- Usa Test Mode in sandbox per fare prove\n\n### Transazioni non vengono importate\n- Verifica che l'account sia abilitato\n- Controlla che la valuta esista in ERPNext\n- Verifica che la valuta della transazione corrisponda a quella del Bank Account\n- Controlla ACube Transaction Log per vedere errori specifici\n\n### Pagamento SEPA non funziona\n- Verifica che l'account OpenBanking supporti pagamenti (campo \"systems\" in raw_data)\n- Controlla che l'IBAN destinatario sia di un paese SEPA\n- Per SEPA Instant: importo massimo €100.000\n- Verifica che `callback_base_url` sia configurato e raggiungibile pubblicamente\n- In sandbox: importo massimo €10\n\n### Payment Entry non viene creato automaticamente\n- Verifica che `payment_mode_of_payment` sia configurato in OpenBanking Settings\n- Controlla ACube Webhook Log per verificare ricezione webhook (lo status atteso da ACube e' `confirmed`)\n- Controlla Error Log (cerca \"Payment Webhook Error\") per eccezioni durante creazione Payment Entry\n- Verifica che Purchase Invoice abbia ancora outstanding_amount \u003e 0\n- Verifica che il Bank Account ERPNext abbia l'IBAN corrispondente all'account OpenBanking usato per il pagamento\n\n### Errore \"Not allowed to change Mode of Payment after submission\"\n- Assicurati di aver configurato `payment_mode_of_payment` in OpenBanking Settings prima di testare\n- Il Mode of Payment deve essere impostato PRIMA del submit del Payment Entry\n\n### Pagamento bloccato in stato PENDING\n- Usa **Riprova Pagamento** per riaprire l'URL della banca e completare l'autorizzazione\n- Se il pagamento non può essere completato, usa **Annulla Pagamento** per sbloccare la fattura\n- Dopo l'annullamento, potrai creare un nuovo pagamento\n- Ricorda: l'annullamento è solo locale, verifica presso la banca che il pagamento non sia stato eseguito\n\n### Pagamento in stato FAILED\n- Controlla il campo `error_message` nel documento OpenBanking Payment per vedere il motivo\n- Usa **Annulla Pagamento** per rimuovere il pagamento fallito\n- Crea un nuovo pagamento risolvendo il problema (es. saldo insufficiente, IBAN errato)\n\n## 🤝 Contributing\n\nI contributi sono benvenuti! Per contribuire:\n\n1. Fai fork del progetto\n2. Crea un branch per la tua feature (`git checkout -b feature/AmazingFeature`)\n3. Commit delle modifiche (`git commit -m 'feat: Add some AmazingFeature'`)\n4. Push al branch (`git push origin feature/AmazingFeature`)\n5. Apri una Pull Request\n\n### Setup Pre-commit\n\nL'app usa `pre-commit` per formattazione e linting:\n\n```bash\ncd apps/solede_openbanking\npre-commit install\n```\n\nTool configurati:\n- **ruff**: Linting Python\n- **eslint**: Linting JavaScript\n- **prettier**: Formattazione\n- **pyupgrade**: Aggiornamento sintassi Python\n\n### Convenzioni Commit\n\nUsa [Conventional Commits](https://www.conventionalcommits.org/):\n\n- `feat:` Nuove funzionalità\n- `fix:` Bug fix\n- `refactor:` Refactoring codice\n- `docs:` Modifiche documentazione\n- `test:` Aggiunta/modifica test\n- `chore:` Maintenance tasks\n\n## 📝 Changelog\n\n### v1.3.0 (Current)\n- 🐛 **Fix Payment Entry automatico** - Corretto status webhook da \"completed\" a \"confirmed\" (allineamento con API ACube)\n- ✨ **Associazione banca corretta** - Il Payment Entry usa il conto bancario effettivo del pagamento (lookup IBAN da account_uuid)\n- ✨ **Custom field Payment Entry** - Aggiunto campo `custom_openbanking_payment` su Payment Entry per tracciabilità\n- 🐛 **Fix KeyError endToEndId** - Accesso sicuro al campo endToEndId nel webhook payload\n- 🐛 **Fix deductions vuote** - Pulizia deductions auto (es. early payment discount) che potevano bloccare la creazione del Payment Entry\n\n### v1.2.0\n- ✨ **Gestione Pagamenti Bloccati** - Nuove funzionalità per gestire pagamenti PENDING/FAILED\n- ✨ **Riprova Pagamento** - Riapri l'URL della banca per completare autorizzazioni incomplete\n- ✨ **Annulla Pagamento** - Annulla pagamenti locali per sbloccare fatture e crearne di nuovi\n- ✨ **Stati Pagamento Migliorati** - Aggiunto stato \"cancelled\" con indicatore grigio\n- ✨ **UX Migliorata** - Bottoni contestuali basati sullo stato del pagamento\n- 🔧 **API Cancel Payment** - Nuova funzione whitelisted per annullamento pagamenti\n\n### v1.1.0\n- ✨ **Pagamenti SEPA** - Bonifici SEPA da Purchase Invoice\n- ✨ **SEPA Instant** - Supporto bonifici istantanei\n- ✨ **IBAN Enrichment** - Creazione automatica Bank/Bank Account da IBAN\n- ✨ **Validazione SEPA** - Controllo paese IBAN per bonifici SEPA\n- ✨ **Payment Entry Automatico** - Creazione automatica da webhook\n- ✨ **Callback Page** - Pagina ritorno dopo autorizzazione\n- ✨ **Mode of Payment Configurabile** - Per ogni company\n- ✨ **Webhook Management** - Gestione completa webhook ACube\n- ✨ **NO FALLBACK** - Errori sempre mostrati all'utente\n\n### v1.0.0\n- ✨ Gestione completa Business Registry\n- ✨ Connessione multi-account bancari\n- ✨ Import transazioni con riconciliazione\n- ✨ Report conti autorizzati\n- ✨ Workspace dedicato OpenBanking\n- ✨ Transaction Log completo\n- ✨ Client API centralizzato (DRY principle)\n- ✨ Test mode con fake banks\n\n## 📄 Licenza\n\nGNU Affero General Public License v3.0 - vedi il file [LICENSE](LICENSE) per dettagli.\n\nCopyright (C) 2024-2026 Solede SA and contributors\n\nQuesta app è rilasciata sotto licenza AGPL v3. Se modifichi questa app e la offri come servizio web/SaaS, DEVI rendere disponibile il codice sorgente modificato a tutti gli utenti del servizio.\n\nQuesto significa:\n- ✅ Puoi usare, modificare e distribuire liberamente\n- ✅ Puoi offrire come servizio commerciale (hosting/SaaS)\n- ✅ DEVI condividere le modifiche se offri come servizio web\n- ✅ Il codice derivato deve rimanere AGPL v3\n\nPer maggiori informazioni: https://www.gnu.org/licenses/agpl-3.0.html\n\n## 👥 Autori\n\n**Solede SA**\n- Website: [solede.com](https://solede.com)\n- Email: info@solede.com\n\n## 🙏 Credits\n\n- Sviluppato con [Claude Code](https://claude.com/claude-code)\n- Basato su [Frappe Framework](https://frappeframework.com/)\n- Integrazione [ACube Open Banking API](https://acubeapi.com/)\n\n## 💬 Supporto\n\nPer problemi, domande o richieste di funzionalità:\n- Apri una [Issue su GitHub](https://github.com/Solede-SA/solede_openbanking/issues)\n- Contatta il team Solede: info@solede.com\n\n## 📚 Risorse Utili\n\n- [Documentazione Frappe](https://frappeframework.com/docs)\n- [Documentazione ERPNext](https://docs.erpnext.com/)\n- [ACube Open Banking Documentation](https://docs.acubeapi.com/documentation/open-banking/)\n- [PSD2 Directive - European Central Bank](https://www.ecb.europa.eu/press/intro/mip-online/2018/html/1803_revisedpsd.en.html)\n- [Open Banking Standards (UK)](https://standards.openbanking.org.uk/)\n\n---\n\nMade with ❤️ by Solede SA\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolede-sa%2Fsolede_openbanking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolede-sa%2Fsolede_openbanking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolede-sa%2Fsolede_openbanking/lists"}