--- title: "Banking as a Service" description: "In questo documento puoi trovare un'introduzione al mondo Banking As A Service." url: "https://docs.fabrick.com/payment-institution/banking-as-a-service/introduction/money-transfer-vop/" language: "it" --- # Banking as a Service L'integrazione con le API BaaS di Fabrick consente di: - Automatizzare le operazioni finanziarie; - Riconciliare le transazioni; - Ridurre il lavoro manuale; - Creare flussi finanziari sofisticati; - Offrire ai clienti un'esperienza di pagamento fluida. Questa guida è pensata per aiutarti a integrare rapidamente la soluzione Banking as a Service (BaaS) di Fabrick nei tuoi sistemi backend. Fornisce le basi tecniche necessarie per iniziare a operare negli ambienti sandbox e di produzione e per realizzare un'integrazione solida, manutenibile e in grado di crescere insieme al tuo business. ## Guida all'integrazione delle API Banking as a Service Questa guida all'integrazione include: - Autenticazione e configurazione - Come configurare in modo sicuro le credenziali API; - Gestione dei conti - Recupero e gestione dei conti di pagamento Fabrick; - Creazione di bonifici - Istruzioni passo passo per avviare trasferimenti di denaro; - Monitoraggio dello stato dei trasferimenti - Tracciamento in tempo reale delle transazioni; - Regole di disponibilità bancaria - Comprensione delle date di esecuzione e della logica dei giorni lavorativi; - Gestione degli errori - Problemi comuni e modalità di risoluzione. ## Integrazione delle API Banking as a Service ### Prerequisiti Assicurati di disporre di: - Un abbonamento Fabrick; - Un conto di pagamento Sella collegato al tuo abbonamento Fabrick; - Credenziali API. ## Flusso di integrazione ## Passaggi di integrazione ### Passaggio 1: Recuperare i tuoi conti > **Nota:** Assicurati di utilizzare l'ambiente e le credenziali API corretti. > > - `sandbox.fabrick.com` (SANDBOX) > - `api.fabrick.com` (LIVE) Prima di poter inviare pagamenti o monitorare le transazioni, devi recuperare i tuoi conti di pagamento e i relativi identificativi univoci. Per recuperare i tuoi conti di pagamento, utilizza l'endpoint `GET Accounts`: ```text https://api.fabrick.com/api/gbs/banking/v4.0/accounts ``` #### Esempio di richiesta ```bash curl --location 'https://api.fabrick.com/api/gbs/banking/v4.0/accounts' \ --header 'Content-Type: application/json' \ --header 'Api-Key: {{YOUR_API_KEY}}' \ --header 'Auth-Schema: S2S' ``` #### Esempio di risposta ```json { "status": "OK", "errors": [], "payload": { "list": [ { "accountId": "30493889", "iban": "IT80R0326822300052819105040", "abiCode": "03268", "cabCode": "22300", "accountNumber": "0052819105040", "accountName": "Company Operating Account", "activationDate": "2024-01-15", "currency": "EUR" } ] } } ``` | Campo | Descrizione | Utilizzo | | ---------------- | ---------------------------------------------------------------- | ------------------------------------------------- | | `accountId` | Identificativo univoco del conto Sella per il conto di pagamento | Obbligatorio in tutte le richieste di transazione | | `iban` | Numero IBAN completo (formato SEPA) | Per bonifici SEPA e riconciliazione | | `abiCode` | Codice dell'Associazione Bancaria Italiana | Informazione di riferimento | | `cabCode` | Codice della filiale | Informazione di riferimento | | `currency` | Valuta del conto (EUR) | Validazione e conversione della valuta | | `activationDate` | Data di attivazione del conto | Monitoraggio del ciclo di vita del conto | #### Per recuperare i dettagli di un conto specifico Utilizza l'endpoint `GET Accounts` e includi l'`accountId` nell'URL: ```bash curl --location 'https://api.fabrick.com/api/gbs/banking/v4.0/accounts/{{accountId}}' \ --header 'Content-Type: application/json' \ --header 'apikey: {{YOUR_API_KEY}}' \ --header 'Auth-Schema: S2S' ``` Utilizzando il pacchetto API Cash Account Management puoi inoltre: - GET Account Balance: recuperare il saldo di uno specifico conto di pagamento; - GET Account Transactions: recuperare le transazioni di uno specifico conto di pagamento; - GET Account Reserved Entries: recuperare l'elenco delle partite prenotate di un conto. ### Passaggio 2: Creazione di bonifici: l'operazione principale La creazione di un trasferimento di denaro è l'operazione fondamentale per i pagamenti automatizzati. Sono supportati sia i bonifici SEPA Credit Transfer (SCT) standard sia i bonifici SEPA Instant Credit Transfer (SCT Inst). #### Prerequisiti Prima di avviare un trasferimento, assicurati di avere: - **Verifica del conto:** un `accountId` valido ottenuto dalla chiamata Get Accounts. - **Informazioni sul creditore:** i dati completi del beneficiario del pagamento. - Definito la tua strategia di Verification of Payee (VoP). Il processo Verification of Payee (VoP) si applica ai bonifici SEPA e verifica che l'IBAN indicato per un trasferimento corrisponda al nome del beneficiario previsto. Per abilitare la verifica per ogni pagamento, imposta l'header `X-VoP-Force-Verification` su `true`. #### Creare un bonifico Utilizza l'endpoint `POST Create Money Transfer`: ```text https://api.fabrick.com/api/gbs/banking/v4.1/accounts/{{accountId}}/payments/money-transfers ``` #### Header della richiesta (obbligatori) - `X-Time-Zone`: impostare sempre su `Europe/Rome`; - `Auth-Schema`: sempre `S2S` per l'autenticazione server-to-server; - `Api-Key`: la chiave API Fabrick assegnata; - `accountId`: il conto di origine. ```bash curl --location 'https://api.fabrick.com/api/gbs/banking/v4.1/accounts/{{accountId}}/payments/money-transfers' \ --header 'apikey: {{YOUR_API_KEY}}' \ --header 'Auth-Schema: S2S' \ --header 'Content-Type: application/json' \ --header 'X-Time-Zone: Europe/Rome' \ --data '{ "creditor": { "name": "John Doe", "account": { "accountCode": "IT59B0300203280461484318754" } }, "executionDate": "2025-05-28", "description": "Refund from ACME SPA", "amount": 55.50, "currency": "EUR", "isUrgent": false, "isInstant": false, "feeType": "SHA" }' ``` #### Descrizione dei campi | Campo | Tipo | Descrizione | | ------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------- | | `creditor.name` | String | Nome completo del beneficiario. Deve essere accurato ai fini della conformità VoP. | | `creditor.account.accountCode` | String | IBAN per i bonifici SEPA o SWIFT per i bonifici non-SEPA. | | `executionDate` | Date (YYYY-MM-DD) | Data in cui viene eseguito il trasferimento; deve rispettare le regole di disponibilità bancaria. | | `description` | String | Causale del trasferimento. Massimo 140 caratteri. | | `amount` | Number | Importo del trasferimento. Massimo 2 decimali. | | `currency` | String | Valuta del trasferimento di denaro (EUR). | | `isInstant` | Boolean | Valore predefinito `false`; impostare su `true` per i trasferimenti istantanei. | > Per un IBAN utilizzato al di fuori dell'Italia sono obbligatori ulteriori campi relativi all'indirizzo del creditore: `creditor.address.address`, `creditor.address.city`, `creditor.address.countryCode`. ### Passaggio 3: Esempio di risposta (esito positivo) ```json { "status": "OK", "errors": [], "payload": { "moneyTransferId": "628947306", "cro": "4393165470703268", "trn": null, "status": "BOOKED", "direction": "OUTGOING", "description": "Refund from ACME SPA", "createdDatetime": "2025-10-27T17:37:59.225+0200", "debtorValueDate": "2025-10-28", "creditorValueDate": "2025-10-29", "amount": { "debtorAmount": 100.50, "debtorCurrency": "EUR", "creditorAmount": 100.50, "creditorCurrency": "EUR", "currencyRatio": 1 }, "isUrgent": false, "isInstant": false, "feeType": "SHA", "fees": [] } } ``` #### Campi principali della risposta | Campo | Significato | | ------------------- | ------------------------------------------------------------------------------------------- | | `moneyTransferId` | Identificativo univoco del trasferimento. Utilizzalo per monitorarne lo stato. | | `CRO` | Numero di riferimento bancario italiano, utilizzato per SCT all'interno della stessa banca. | | `TRN` | Transaction Reference Number, identificativo ISO 20022 utilizzato nei messaggi SEPA. | | `status` | Stato corrente del trasferimento: `WORK_IN_PROGRESS`, `BOOKED`, `EXECUTED`, `REJECTED`. | | `debtorValueDate` | Data in cui i fondi vengono addebitati sul tuo conto. | | `creditorValueDate` | Data in cui i fondi arrivano sul conto del beneficiario. | | `fees` | Commissioni associate al trasferimento. | ### Passaggio 4: Codici di stato del trasferimento | Codice di stato | Descrizione | | ------------------ | ------------------------------------------------------------------------------------ | | `WORK_IN_PROGRESS` | Trasferimento creato prima delle 16:00, ancora in elaborazione. | | `BOOKED` | Trasferimento creato dopo le 16:00, pianificato per il giorno lavorativo successivo. | | `EXECUTED` | Elaborato correttamente dalla banca. | | `REJECTED` | Trasferimento non riuscito, ad esempio per IBAN non valido o fondi insufficienti. | ## Validare le date di esecuzione ### SCT istantaneo Per i pagamenti istantanei (`isInstant == true`) non è necessario specificare `executionDate`: i trasferimenti vengono effettuati in pochi secondi, 24 ore su 24, 7 giorni su 7, 365 giorni all'anno. ### SCT ordinario Si raccomanda di creare il trasferimento di denaro prima dell'orario di cut-off bancario delle 16:00 Europe/Rome. `executionDate` è facoltativo perché il sistema calcola automaticamente la prima data disponibile. Evita i giorni non lavorativi: - Sabato e domenica; - Festività italiane: 1 gennaio, 25 aprile, 1 maggio, 2 giugno, 15 agosto, 1 novembre, 8 dicembre, 25-26 dicembre; - Lunedì dell'Angelo. Regole per la data minima di esecuzione: - Prima delle 16:00 in un giorno lavorativo: oggi; - Dopo le 16:00 in un giorno lavorativo: domani; - Festività bancaria: giorno lavorativo successivo. ## Monitoraggio dello stato del trasferimento Fabrick mette a disposizione approcci complementari per il monitoraggio: ### Monitoraggio pianificato Esegui un job automatico una volta al giorno, ad esempio alle 9:00. ### Monitoraggio on-demand Utilizzalo quando: - Un cliente chiede informazioni su uno specifico trasferimento; - È necessaria una riconciliazione immediata; - Stai effettuando test o troubleshooting. ### Monitoraggio del conto Rilevamento e notifica quasi in tempo reale degli eventi relativi alle transazioni in entrata e in uscita sui conti inseriti in whitelist tramite callback. ## Ricerca dei trasferimenti Utilizza l'API Search Money Transfer: ```http POST /money-transfers/search HTTP/1.1 Host: api.fabrick.com X-Time-Zone: Europe/Rome Content-Type: application/json Auth-Schema: S2S Api-Key: {YOUR_API_KEY} accountId: {ACCOUNT_ID} { "direction": "OUTGOING", "createdDatetime": { "from": "2025-05-18", "to": "2025-05-27" }, "pagination": { "offset": 0, "limit": 2000 } } ``` ### Parametri di ricerca Finestra di ricerca consigliata: una finestra mobile di 7 giorni. | Parametro | Descrizione | | ---------------------- | -------------------------------------------------------------------------------- | | `direction` | `OUTGOING` per i trasferimenti avviati; `INCOMING` per i trasferimenti ricevuti. | | `createdDatetime.from` | Data di inizio della ricerca, ad esempio now() - 7 giorni. | | `createdDatetime.to` | Data di fine della ricerca, ad esempio now(). | | `pagination.limit` | Numero massimo di risultati per pagina. | | `pagination.offset` | Posizione iniziale per la paginazione. | ### Logica di riconciliazione dello stato Per ogni trasferimento restituito: 1. Associa i record locali utilizzando `moneyTransferId`. 2. Confronta i valori dello stato. 3. Se lo stato è invariato, non è necessaria alcuna azione. 4. Se lo stato è cambiato, aggiorna il database e attiva i processi downstream. 5. Gestisci gli stati speciali: - `REJECTED`: avvisa il cliente, analizza il motivo ed eventualmente riprova; - `EXECUTED`: conferma l'accredito e aggiorna i record; - `BOOKED`: continua il monitoraggio dopo la data di esecuzione. ## Gestione dei timeout Se una richiesta va in timeout: - **Non** presumere che il trasferimento non sia riuscito; - Registra il timeout con il timestamp esatto; - Per errori HTTP 500 e 504, esegui una ricerca di verifica utilizzando nome del beneficiario, IBAN, importo, valuta e descrizione; - Attendi almeno 100 secondi; - Aggiorna lo stato in base ai risultati della ricerca; - Riprova solo dopo aver effettuato la verifica tramite ricerca. In questo modo si evitano trasferimenti duplicati causati dalla logica di retry dopo un timeout. ## Gestione degli errori e validazione ### Codici di stato HTTP | Codice | Significato | Azione | | ------ | ----------------- | ----------------------------------------------------------------------- | | 200 | OK | Elabora normalmente la risposta. | | 400 | Bad Request | Valida la richiesta e riprova dopo aver apportato le correzioni. | | 401 | Unauthorized | Verifica le credenziali e rigenera i token se necessario. | | 403 | Forbidden | Verifica l'accesso al conto e le autorizzazioni. | | 429 | Too Many Requests | Implementa un backoff esponenziale. | | 500+ | Server Error | Riprova dopo 30 secondi; se il problema persiste, contatta il Supporto. | ## Risoluzione degli errori di validazione più comuni ### IBAN non valido Verifica: - Il formato dell'IBAN; - Che l'IBAN sia aggiornato; - Il prefisso del Paese; - L'algoritmo di controllo delle cifre dell'IBAN. ### Data di esecuzione non valida Verifica: - Che la data di esecuzione sia un giorno lavorativo; - Che la data non sia nel passato; - Che la data rientri nei 30 giorni lavorativi; - Le regole di disponibilità bancaria. ### Campo descrizione non valido Verifica: - Massimo 140 caratteri; - Evita caratteri speciali, ad eccezione di trattini e spazi; - Utilizza caratteri alfanumerici; - Abbrevia le informazioni di riferimento troppo lunghe, se necessario. ## Supporto e risorse aggiuntive Per problemi tecnici, contatta il team di supporto API di Fabrick tramite il sito web di Fabrick. ## Iniziare a utilizzare le API Fabrick ### Principali casi d'uso - **Riconciliazione e contabilità:** recupera automaticamente gli elenchi delle transazioni per il riconoscimento dei pagamenti e la riconciliazione. - **Flussi di payout automatizzati:** automatizza rimborsi, erogazioni di prestiti e rimborsi spese. - **Cash pooling e gestione multi-conto:** consolida i dati provenienti da più conti di pagamento. - **Metodi di pagamento locali:** gestisci pagamenti F24, F24 semplificati, PagoPA, MAV/RAV e bollo auto. - **Conti di salvaguardia:** gestisci conti di custodia per soggetti regolamentati come IMEL, PI, SGR e SIM. ### Pacchetti API e funzionalità | Pacchetto API | Versione | Scopo | | -------------------------- | -------- | ------------------------------------------------------------------------ | | Cash Account Management | v4.0 | Recuperare dettagli del conto, saldi e transazioni del conto. | | Payments / Money Transfers | v4.1 | Creare trasferimenti, monitorarne lo stato e controllare le transazioni. | ### Metodi di autenticazione Fabrick supporta: - **Autenticazione tramite API Key (S2S):** comunicazione server-to-server; - **OAuth 2.0:** accesso delegato e integrazioni di terze parti; - **JWT (JSON Web Token):** accesso basato su token. Per la maggior parte delle integrazioni dirette, utilizza l'autenticazione S2S con l'API key assegnata.