--- title: "PFM" description: "Il Personal Financial Manager (PFM) è oggi il fulcro del banking digitale. Il prodotto PFM di Fabrick è un progetto indipendente che fornisce al cliente Retail un \"personal trainer\" con suggerimenti e consigli…" url: "https://docs.fabrick.com/payment-institution/open-banking-and-psd2/active-engine/dev/ais-details/pfm-details/" language: "it" --- # PFM ## Introduzione Il Personal Financial Manager (PFM) è oggi il fulcro del banking digitale. Il prodotto PFM di Fabrick è un progetto indipendente che fornisce al cliente Retail un "personal trainer" con suggerimenti e consigli personalizzati per la gestione della propria situazione finanziaria e del budget, al fine di gestire al meglio il proprio denaro e trovare un buon equilibrio finanziario. Il PFM è principalmente dedicato ai conti retail (consumer); in caso di conti business è possibile richiedere un approfondimento sul progetto BFM (Business Financial Manager). Il progetto è molto ampio e descrivere tutte le sue funzionalità e potenzialità esula dallo scopo di questa guida, in cui ci concentreremo su un unico servizio: **GET GetPfmTransactions**. Questo servizio restituisce la lista delle transazioni del PSU esattamente come i servizi relativi alle transazioni descritti fino ad ora, ma arricchisce inoltre, in tempo reale (Near real-time), ogni singola transazione con una serie di informazioni aggiuntive. Sia per TPP che per FPP, la risposta ottenuta a seguito di una richiesta di transazioni PFM è esattamente la stessa ed è descritta di seguito. Le API di richiesta variano invece leggermente; per i dettagli implementativi è possibile fare riferimento alla relativa documentazione. In ogni caso, questo è il percorso: ```text .../movements/transactions ``` È disponibile un aggiornamento in cui tutti i campi sono in inglese. È possibile scegliere l'uno o l'altro modello semplicemente inserendo *en* nel percorso come mostrato di seguito: ```text .../movements/en/transactions ``` > Ad oggi, i prodotti Pass dispongono ancora solo della versione italiana. Sarà aggiornata a breve. Di seguito è mostrato un esempio di risposta: ```text { "errors": [], "status": "OK", "payload": { "list": [{ "id": 4237, "bankId": "5", "bankProfileId": "2964", "accountId": 10105, "userId": "1", "tppUid": "123456", "isTemporary": false "propBankTransactionCode": null, "tipoOperazione": "alt", "importo": 1.0, "stato": "ESEGUITO", "tipo": "income", "causaleStructured": null, "causale": "VOSTRADISPOSIZIONEBONIFICOURG./ISTANTANEO", "remittanceDescriptions": [] "remittanceAdditionalInfo": [] "bankReference": "123" "data": 1621893600000, "valueDate": 1621893600000, "createdDate": 1623140347621, "accounted": true, "recurrent": false, "categoria": "entertainment", "sottoCategoria": "sportEvents", "cro": null, "nomeBeneficiario": null, "merchant": "aMerchant", "merchantCity": "Milano", "mcc": "1234", "numeroContoAddebito": null, "numeroContoAccredito": null, "reference": null, "entryReference": null, "divisa": "EUR", "eseguitoDa": null, "ibanBeneficiario": null, "saldo": 3020803002.84, "saldoDisponibile": 3020803002.84, "isBookingDateForged": false, "normalizedMerchant": null }, { "id": 4238, ... }] } } ``` In base alla normativa PSD2, gli unici campi obbligatori sono importo, causale e data. Tutti i campi descritti di seguito saranno quindi valorizzati solo se la banca finale restituisce quella particolare informazione. Alcune informazioni vengono restituite direttamente, mentre altre vengono arricchite grazie a un lavoro di analisi da parte di Fabrick sulla causale bancaria completa (ovviamente più completa della causale inserita dal cliente). Tutti i parametri non valorizzati non compariranno nella risposta e saranno pertanto considerati *null*. Per quanto riguarda i parametri *categoria*, *sottoCategoria* e *tipoOperazione*, fare riferimento alle tabelle successive. Alcuni dettagli sull'output: - *saldo*: indica il saldo del conto aggiornato all'ultima richiesta di Fabrick alla banca. È basato sulla valuta del conto: ad esempio, se la valuta del conto è EUR, il saldo sarà in EUR; se la valuta del conto è USD, il saldo sarà in USD. Si consiglia di utilizzare il servizio dedicato più completo per ottenere le informazioni sui saldi (v. doc Dettagli Saldi). - *importo*: indica l'importo della transazione - *currency*: la valuta del conto Nel caso in cui si tratti di una transazione in valuta, saranno disponibili i seguenti parametri aggiuntivi: - *importoDivisa* - *tassoCambio* Il valore del parametro *importo* sarà calcolato come *importoDivisa / tassoCambio*. Nella risposta è presente un ulteriore parametro: - *tassoBce*: per PSD2 è possibile ignorare questo parametro, è utile solo per le transazioni native e non per le transazioni PSD2. Nella richiesta è possibile specificare i seguenti parametri di query per filtrare e/o ordinare le risorse richieste: - *fromDate* e *toDate* (saranno deprecati, v. sezione "Ricerca per data"): l'intervallo temporale entro il quale devono essere visualizzate le transazioni; fanno riferimento al parametro *data*; devono essere in epochTime in ms. - *fromCreatedDate* e *toCreatedDate* (saranno deprecati, v. sezione "Ricerca per data"): l'intervallo temporale entro il quale devono essere visualizzate le transazioni; fanno riferimento al parametro *createdDate*; devono essere in epochTime in ms. - *sortBy*: consente di ordinare le transazioni in base a qualsiasi parametro del modello di risposta; il valore di default è *createdDate*. Usare '-' per l'ordine decrescente (es. *sortBy=-data*)). - *future*: flag che consente, se true, di mostrare le transazioni in sospeso (solo per TPP e dipende dalle banche finali se disponibili); - *category*: qualsiasi categoria valida. Sono ammessi più valori; - *type*: il tipo di transazione, *income* o *outcome*; - *fromAmount*: per ottenere la lista delle transazioni con un importo maggiore o uguale al decimale indicato; - *toAmount*: per ottenere la lista delle transazioni con un importo minore o uguale al decimale indicato; - *operationType*: è possibile filtrare per tipo di operazione, v. tabella seguente. Sono ammessi più valori. Il PFM gestisce la paginazione; per questo motivo è possibile aggiungere anche: - *limit*: il numero di transazioni da ottenere. Il valore di default è 20 e il massimo è 300. - *offset*: indica l'offset e fa riferimento alle transazioni, non alla pagina. Il valore di default è 0. Nella risposta si otterrà un oggetto di paginazione: ```text ... "pagination": { "pageCount": 0, "resultCount": 0, "offset": 0, "limit": 20 }, ... ``` dove *offset* e *limit* indicano i parametri di query opzionali appena descritti, mentre *pageCount* e *resultCount* indicano rispettivamente il numero di pagine e di elementi. Ad esempio, se si dispone di un conto con 40 transazioni e si impone un limite di 20, si effettueranno due richieste distinte valorizzando l'offset come segue per ottenere la lista completa: ```text /accounts/movements/transactions?accountId=123&offset=0&limit=20&sortBy=-data /accounts/movements/transactions?accountId=123&offset=20&limit=20&sortBy=-data ``` ### Ricerca per data (disponibile a breve) L'API consentirà di filtrare per diversi tipi di data. I parametri *fromDate* e *toDate* indicano l'intervallo, mentre il parametro *dateFilter* indica il tipo di data. Questo campo può assumere i seguenti valori: - *data* = la data di contabilizzazione (booking date) - *valueDate* = la data valuta - *createdDate* = la data di creazione - *resyncDate* = la data di risincronizzazione - *createdModifiedDate* = *resyncDate* + *createdDate* I dati sono indicati in epochTime in ms, sia quelli nella richiesta che quelli restituiti nella risposta. Sebbene siano in millisecondi, tutte le date restituite dalle banche contengono solo informazioni relative al giorno (non all'orario); per questo motivo saranno tutte valorizzate alla mezzanotte. Ad esempio: ```text /movements/transactions?dateFilter=createdModifiedDate&fromDate=xxxx&toDate=yyyy ``` Se non viene indicato alcun filtro, verranno restituite tutte le transazioni. > Alcune transazioni possono avere *valueDate* pari a *null*: se si utilizza questo parametro come filtro, le transazioni con *valueDate* *null* non verranno restituite. Si consiglia di utilizzare la data di contabilizzazione (*data*), che è sempre presente. > Data la definizione di *resyncDate*, per la maggior parte delle transazioni questo valore sarà *null*: se si utilizza questo parametro come filtro, le transazioni con *resyncDate null* non verranno restituite. Lo scopo di questo filtro è mostrare solo le transazioni aggiunte, modificate ed eliminate in un secondo momento, in modo che il TPP possa correggere il proprio archivio/DB. ## Dati grezzi vs Dati arricchiti Di seguito è riportato un esempio che mostra la differenza tra i dati grezzi e quelli ottenuti tramite il servizio: ![pfmLabeledData](https://docs.fabrick.com/img/payment-institution/open-banking-and-psd2/common-pass-and-active-engine/pfm-labeled-data.png) Come accennato, il PFM è un progetto molto più ampio, pertanto il TPP potrà sempre arricchire la propria interfaccia integrando molte altre funzionalità PFM: per maggiori informazioni e approfondimenti, fare riferimento alla documentazione dedicata. In fondo a questa pagina sono presenti le tabelle con la lista di tutti i parametri restituiti e ulteriori dettagli. ### Mappatura tra dati grezzi e dati arricchiti (disponibile a breve) Per recuperare la lista dei movimenti sono disponibili due servizi distinti: - **GET getTransaction** (deprecato) - **GET getPFMTransactions** (descritto in questo documento) Per riconciliare i due movimenti è possibile affidarsi al parametro **reconciliationId**, un GUID creato da Fabrick che verrà inserito per ogni movimento in risposta ai due servizi sopra citati. In questo modo sarà possibile effettuare la transizione dal servizio **GET getTransaction** al servizio **GET getPFMTransactions** prima della dismissione. ## Dati Aggiuntivi Come opzione a valore aggiunto è possibile ottenere alcune informazioni aggiuntive. Ad oggi, le informazioni aggiuntive sono *nomeBeneficiario* e *eseguitoDa*. Se si è un TPP è sufficiente aggiungere il parametro di query *additionalData = true*. Di seguito è riportato un esempio di richiesta: ```text GET /api/fabrick/.../transactions?...&additionalData=true ``` Nel caso di FPP non è necessaria alcuna modifica (non è necessario aggiungere il parametro *additionalData*); sarà già incluso. ## Parametri di risposta | **Nome** | Nome in inglese | **Descrizione** | | | ------------------------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | accounted | accounted | Indica se la transazione è stata contabilizzata. Indica se la transazione è prenotata o in sospeso. Fabrick non applica alcuna logica; il valore si basa sulle informazioni fornite dalla banca: se quella transazione è indicata come prenotata, allora *accounted* sarà true. In base alle specifiche BG, la possibilità di gestire le transazioni in sospeso è opzionale; pertanto alcune banche potrebbero fornire solo quelle prenotate. | m | | accountId | accountId | ID conto | m | | bankId | bankId | ID banca | m | | bankProfileId | bankProfileId | ID profilo banca | m | | bankReference | bankReference | ID transazione opzionale fornito dalla banca | o | | categoria | category | La categoria della transazione (v. tabella successiva) | m | | causale | description | remittanceInformationUnstructured - psd2. Contiene la descrizione della transazione. Può contenere un massimo di 140 caratteri. | m | | causaleStructured | descriptionStructured | remittanceInformationStructured - psd2. Contiene informazioni strutturate sulla transazione. Ad oggi le banche non utilizzano questo campo. | o | | createdDate | createdDate | Data in cui il record è stato scritto - È la data (di sistema) in cui il record della transazione è stato ricevuto in Fabrick interrogando la banca. Non è un valore bancario. | m | | cro | cro | ID interno della banca | o | | data | bookingDate | Data di inserimento nel sistema Contabile. È la data valuta della transazione, comunicata dalla banca - Data di contabilizzazione (giorno in cui la transazione è stata eseguita dall'utente = data contabile). | m | | divisa | currency | Valuta | m | | entryReference | entryReference | Riferimento di registrazione così come ricevuto nelle transazioni. | o | | eseguitoDa | executedBy | Nome e cognome del debitore | o | | ibanBeneficiario | beneficiaryIban | IBAN del beneficiario. | o | | id | id | ID transazione | m | | importo | amount | Importo della transazione | m | | importoDivisa | originalAmount | Importo nella valuta originale | o | | isBookingDateForged | isBookingDateForged | Campo booleano che indica se la data di contabilizzazione è stata alterata su Agata. | m | | isTemporary | isTemporary | \[DEPRECATO: v. *resyncType*] Se true, il parametro *id* non è ancora definitivo e cambierà sicuramente valore. Anche altri parametri potrebbero cambiare (bankReference, description, ecc.). Se false, tutti i parametri saranno definitivi e non cambieranno valore. Utile se il TPP/FPP ha necessità di archiviare le transazioni. | o | | mcc | mcc | Codice di classificazione del merchant. Questo parametro è valorizzato solo se *operationType* è *crd* o *pos*. | o | | merchant | merchant | Nome del merchant | o | | merchantCity | merchantCity | Città del merchant | o | | nomeBeneficiario | beneficiaryName | Nome del beneficiario. Se il bonifico è in entrata è ovviamente recuperabile (corrisponde al titolare del conto stesso), ma se in uscita viene recuperato dalle informazioni restituite dalla banca e potrebbe quindi non essere valorizzato in tutti i casi. | o | | normalizedMerchant | normalizedMerchant | Nome merchant normalizzato associato al merchant di questa transazione (esempio: merchant = Esselunga Biella => normalizedMerchant = Esselunga) | o | | numeroContoAccredito | creditAccountNumber | Numero del conto accreditato. Se il bonifico è in entrata è ovviamente recuperabile (corrisponde al numero di conto stesso); se in uscita viene recuperato dalle informazioni restituite dalla banca. | o | | numeroContoAddebito | debitAccountNumber | Numero del conto addebitato. Se il bonifico è in uscita è ovviamente recuperabile (corrisponde al titolare del conto stesso), ma se in entrata viene recuperato dalle informazioni restituite dalla banca. | o | | propBankTransactionCode | propBankTransactionCode | Codice proprietario della transazione della banca finale | o | | recurrent | recurrent | true se si tratta di una transazione ricorrente | m | | reference | reference | Riferimento della transazione. Eventuali dettagli aggiuntivi recuperati dal sistema di classificazione Fabrick. Corrisponde al pattern individuato nella causale dall'analisi semantica. | o | | remittanceAdditionalInfo | remittanceAdditionalInfo | È un array contenente informazioni aggiuntive. Ad esempio, informazioni inserite dall'utente dove la banca lo consente. Generalmente è composto da un singolo elemento. | o | | remittanceDescriptions | remittanceDescriptions | remittanceInformationUnstructuredArray - psd2. È un array contenente la descrizione della transazione. Ogni elemento dell'array può contenere un massimo di 140 caratteri. Es: \[ "COMUNE DI BIELLA", "Data Regolamento: 23/12/22", "Coord.Ordinante: ITxx xxxx xxxx xxxx xxxx xxxx xxx", "Banca Ordinante: xxxxxx-xxx", "Cro: C0xxxxxxxxx", "Note: a note... - FATT. NR. xxxxxxx", "Id.Operazione: 12345", "(BP)" ] | o | | resyncType | resyncType | Tipo di risincronizzazione | m | | resyncDate | resyncDate | Data della fase di risincronizzazione | o | | saldo | balance | Saldo aggiornato all'ultima richiesta di Fabrick | m | | saldoDisponibile | balanceAvailable | Saldo disponibile aggiornato all'ultima richiesta di Fabrick | m | | sottoCategoria | subCategory | La sottocategoria della transazione (v. sezione successiva) | m | | stato | status | Stato della transazione (v. sezione successiva) | m | | tassoCambio | exchangeRate | Tasso di cambio | o | | tipo | type | Entrata o uscita: può assumere i seguenti valori: 'income' e 'outcome' | m | | tipoOperazione | operationType | Tipo di operazione (v. tabella successiva) | m | | tppUid | tppUid | ID TPP | m | | userId | userId | ID utente | m | | valueDate | valueDate | Data operazione o valuta - Data in cui la transazione diventa effettiva (data disponibile) | o | ### causale vs remittanceDescriptions Il parametro *causale* può contenere un massimo di 140 caratteri; per questo motivo lo standard BG ha aggiunto il parametro *remittanceDescriptions*, per consentire di superare questo limite ed evitare che il TPP ottenga una descrizione troncata. Purtroppo non tutte le banche hanno implementato questa evoluzione. Inoltre, lo standard ha lasciato le banche libere di interpretarlo; per questo non è possibile stabilire una regola uniforme. In altre parole, potrebbero esserci casi diversi: - *causale* e *remittanceDescriptions* contengono esattamente lo stesso valore; - *causale* contiene la prima parte della descrizione, fino al 140° carattere, mentre *remittanceDescriptions* contiene l'intera descrizione su più elementi del vettore; - *causale* contiene la prima parte della descrizione, fino al 140° carattere, e *remittanceDescriptions* contiene solo la parte in eccesso, ovvero quella troncata; - *remittanceDescriptions* potrebbe avere elementi ordinati, ovvero un elemento per ogni tipo di informazione, oppure riempire l'elemento fino al limite di 140 caratteri e poi continuare nel secondo elemento. Di seguito è riportato un esempio. ```text { ... "causale": "GIROFONDI BANCHE ... Iban Beneficiario : IT... Data ordine: 14/0", "remittanceDescriptions": ["GIROFONDI BANCHE ...", "Iban Beneficiario : IT...", "Data ordine: 14/07/2022 Data reg. benef.: 14/07/2022", "CASSA AZIENDA", "FIL: 00282 N.DIST.: ..."] ... } ``` Vista la complessità, al momento Fabrick non esegue alcuna mappatura su questi campi e li restituisce esattamente come recuperati dall'ASPSP. ### Approfondimento sul Resync A volte le banche restituiscono alcune transazioni giorni dopo la bookingDate della transazione stessa; generalmente si tratta ad esempio delle commissioni di un bonifico o di spese legate al conto in prossimità della fine del trimestre; di solito si parla di 1 o 2 giorni. Per questo motivo Fabrick continua a recuperare la lista delle transazioni con una data di contabilizzazione nel passato; di conseguenza alcune transazioni potrebbero comparire dopo la data attesa. Per gestire meglio questo caso, sono stati aggiunti i seguenti due parametri: - *resyncType* - *resyncDate* ***resyncType***: indica lo stato della transazione. Può assumere i seguenti valori: - *CREATED_TEMPORARY*: la transazione è stata appena recuperata dalla banca; l'ID della transazione può ancora cambiare, pertanto si consiglia di evitare di archiviarla. Questo è l'unico stato in cui l'ID della transazione è ancora temporaneo (sostituisce il booleano deprecato *isTemporary*). - *CREATED*: la transazione è definitiva; il parametro *id* rimarrà univoco e invariabile. - *INSERTED*: una transazione aggiunta in un secondo momento; il parametro *id* rimarrà univoco e invariabile. - *MODIFIED*: una descrizione di transazione modificata in un secondo momento; l'ID non verrà modificato. - *DELETED*: una transazione eliminata in un secondo momento (sostituisce il vecchio booleano *isDeleted*). *resyncType* sarà sempre presente; ciò significa che la maggior parte dei parametri sarà impostata su CREATED. Se il consenso scade mentre alcune transazioni sono nello stato *CREATED_TEMPORARY*, non sarà possibile aggiornare lo stato a *CREATED*. Il passaggio da *CREATED_TEMPORARY* a *CREATED* avverrà al successivo rinnovo del consenso (ovviamente la data della transazione deve essere inclusa nell'intervallo temporale post-consenso richiesto). ***resyncDate***: indica l'ultima data/ora in cui la transazione è cambiata a causa di una seconda sincronizzazione (resync). Ciò significa che questo parametro sarà valorizzato solo per gli stati *INSERTED*, *MODIFIED*, *DELETED* e sarà *null* per gli stati *CREATED_TEMPORARY* e *CREATED*. Ovviamente nel caso di *INSERTED* coinciderà con *createdDate*. > Entrambi i parametri sono disponibili solo in ambiente di produzione. ### Categorie e sottocategorie Una volta recuperate le transazioni e salvate nei DB di Fabrick, sono immediatamente disponibili. Ma il processo di categorizzazione inizia nello stesso momento, quindi potrebbe richiedere qualche secondo. È pertanto possibile osservare una variazione di questo parametro inizialmente valorizzato come *alt* (altro). | DIREZIONE | CATEGORIA | SOTTOCATEGORIA | | --------- | --------------------- | -------------------- | | INGOING | giroEntrance | na | | INGOING | inboundCashManagement | na | | INGOING | subsistence | na | | INGOING | giftAndDonations | na | | INGOING | rentIncoming | na | | INGOING | refunds | na | | INGOING | bondsIncome | na | | INGOING | medicalRefund | na | | INGOING | work | na | | INGOING | pension | na | | INGOING | loan | na | | INGOING | win | na | | INGOING | insuranceIncome | na | | INGOING | othersEntrance | na | | INGOING | depositsEntrance | na | | OUTGOING | tax | financialsCommission | | OUTGOING | transfers | extcreditCard | | OUTGOING | giro | giro | | OUTGOING | deposits | deposits | | OUTGOING | restaurants | bar | | OUTGOING | restaurants | restaurantsPizza | | OUTGOING | restaurants | takeAway | | OUTGOING | restaurants | othersRestaurants | | OUTGOING | entertainment | cinema | | OUTGOING | entertainment | musicAndFilm | | OUTGOING | entertainment | bet | | OUTGOING | entertainment | books | | OUTGOING | entertainment | papers | | OUTGOING | entertainment | theater | | OUTGOING | entertainment | museums | | OUTGOING | entertainment | sportEvents | | OUTGOING | entertainment | videogames | | OUTGOING | entertainment | othersEntertainment | | OUTGOING | health | relax | | OUTGOING | health | drugs | | OUTGOING | health | aid | | OUTGOING | health | medical | | OUTGOING | health | gym | | OUTGOING | health | sport | | OUTGOING | health | onlus | | OUTGOING | health | othersHealth | | OUTGOING | tax | fines | | OUTGOING | tax | financialsFees | | OUTGOING | tax | taxes | | OUTGOING | tax | billsPay | | OUTGOING | tax | businessConsultants | | OUTGOING | tax | expenseReport | | OUTGOING | tax | offices | | OUTGOING | tax | lawyers | | OUTGOING | tax | othersTax | | OUTGOING | home | rent | | OUTGOING | home | supermarket | | OUTGOING | home | mortgages | | OUTGOING | home | interior | | OUTGOING | home | homeDevices | | OUTGOING | home | maintenance | | OUTGOING | home | condoFees | | OUTGOING | home | bills | | OUTGOING | home | subscriptions | | OUTGOING | home | childHood | | OUTGOING | home | careGiven | | OUTGOING | home | laundry | | OUTGOING | home | babySitter | | OUTGOING | home | veterinary | | OUTGOING | home | insurance | | OUTGOING | home | internet | | OUTGOING | home | othersHome | | OUTGOING | transfers | creditCard | | OUTGOING | transfers | investments | | OUTGOING | transfers | cashManagement | | OUTGOING | transfers | othersTransfer | | OUTGOING | school | nursery | | OUTGOING | school | courses | | OUTGOING | school | teachingMaterials | | OUTGOING | school | schoolEducation | | OUTGOING | school | university | | OUTGOING | school | othersSchool | | OUTGOING | travel | carMaintenance | | OUTGOING | travel | telepass | | OUTGOING | travel | fuel | | OUTGOING | travel | trains | | OUTGOING | travel | fly | | OUTGOING | travel | publicTransport | | OUTGOING | travel | carRent | | OUTGOING | travel | bus | | OUTGOING | travel | taxy | | OUTGOING | travel | hotel | | OUTGOING | travel | holiday | | OUTGOING | travel | carSharing | | OUTGOING | travel | boats | | OUTGOING | travel | othersTravel | | OUTGOING | shopping | clothing | | OUTGOING | shopping | accessories | | OUTGOING | shopping | shoes | | OUTGOING | shopping | jewelry | | OUTGOING | shopping | electronics | | OUTGOING | shopping | sportingGoods | | OUTGOING | shopping | othersShopping | | OUTGOING | others | clubAndOnlus | | OUTGOING | others | professionals | | OUTGOING | others | tobaccoAndAlcool | | OUTGOING | others | maintenanceOthers | | OUTGOING | others | maintenance | | OUTGOING | others | funding | | OUTGOING | others | atm | | OUTGOING | others | give | | OUTGOING | others | othersOthers | ### Tipo Operazione È possibile ottenere la lista aggiornata dei valori tramite API: ```text POST {{domain}}/access/transactions/operationType/search { } ``` È possibile filtrare per un valore specifico: ```text POST {{domain}}/access/transactions/operationType/search { "operationType": "ver" } ``` | tipoOperazione | Operazione | Descrizione italiana | | -------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | aec | Addebito e/c carta | Addebito e/c carta | | aft | Anticipo fattura | Anticipo fattura | | alt | altro | Altri movimenti | | amz | Amazon Gift Voucher Payment | Gift Amazon | | ass | assegno | Assegno | | atm | carta di debito ATM | Prelievo da sportello ATM | | baf | SCT agevolazione fiscale | Bonifico Agevolazione Fiscale | | bap | SCT paesi esteri | SEPA Credit Transfer - estero | | bil | bollettini | Bollettini postali | | blt | bollette | Bollette | | boa | bollo auto | Bollo auto | | bog | SCT generico (deprecato) | SCT generico (deprecated) | | boi | SCT istantaneo | SEPA Credit Transfer Instant | | bol | imposta di bollo | Imposta di bollo | | bon | SCT italia | SEPA Credit Transfer in Italia | | bop | SCT periodico | SEPA Credit Transfer ricorrente | | can | canone | Canone | | cas | Commissioni assegni | Commissioni assegni | | cbi | C-bill | Pagamento bollettini postali | | cbl | Commissioni bollettino | Commissioni bollettino | | cbn | Commissioni bonifico | Commissioni bonifico | | cca | Commissioni Carta | Commissioni Carta | | ccr | carta di credito (deprecato) | Pagamento con carta di credito (deprecated) | | cdd | Commissioni sdd | Commissioni sdd | | cds | Commissioni distinta | Commissioni distinta | | cfi | Commissioni fideiussioni/fido | Commissioni fideiussioni/fido | | cid | Commissioni insoluto sdd | Commissioni insoluto sdd | | cir | Commissioni insoluto riba | Commissioni insoluto riba | | com | commissione | Commissioni | | cpl | Commissioni prelievo | Commissioni prelievo | | cpo | Commissioni/canone POS | Commissioni/canone POS | | crd | carta di debito ecommerce | Pagamento online | | crg | Carte Generic | Carte Generic | | cri | Commissioni su presentazioni ri.ba | Commissioni su presentazioni ri.ba | | div | Dividendi e cedole | Dividendi e cedole | | dst | Distinta | Distinta | | f24 | F24 | Modello F24 utilizzato in Italia per il pagamento di gran parte delle imposte, delle tasse e dei contributi | | fat | fattura | Pagamento fattura utenza | | fin | Finanziamenti | Finanziamenti | | gir | giroconto | Giroconto | | idd | Insoluti sdd | Insoluti sdd | | ins | Insoluti effetti | Insoluti effetti | | int | interessi | Accredito Interessi | | irb | Insoluti RIBA | Insoluti RIBA | | lin | deposito | Conto deposito | | lor | Ricavo sconto lordo | Ricavo sconto lordo | | mav | MAV | MAV: Pagamento mediante avviso tramite bollettino | | net | altri ricavi | Altri ricavi | | p2p | bonifico bancario | Trasferimento bancario | | par | Partita prenotata | Le partite prenotate sono delle voci in addebito che la banca rende indisponibili in attesa di regolare le operazioni. Ad esempio gli assegni che versi sul tuo conto corrente sono indisponibili fino a quando l'istituto titolare dell'assegno comunica la copertura dello stesso. | | pol | Polizze | Polizze | | pos | carta di debito POS | Pagamento tramite POS | | ppa | PagoPA | sistema dei pagamenti a favore delle pubbliche amministrazioni e dei gestori di pubblici servizi in Italia | | pre | deprecato | | | prs | Prestiti | Prestiti | | rat | Ricarica carta | Ricarica carta | | rav | RAV | RAV: Ruoli Mediante Avviso - utilizzato per pagare somme iscritte a ruolo (ovvero tasse, tributi, sanzioni amministrative, ecc. verso l'Agenzia delle Entrate, Inps, Comuni, Province e Regioni) | | rcp | Ricarica carta | Ricarica carta | | rdc | Ricavo effetti al dopo incasso | Ricavo effetti al dopo incasso | | rib | Riba | Riba (Ricevuta Bancaria) è uno strumento finanziario molto usato da imprese e professionisti che permette di agevolare i pagamenti tramite banca | | ric | ricarica mobile | Ricarica telefonica | | rim | rimborso | Rimborso da altri enti | | rit | ritenuta bancaria | Ritenuta su interessi | | rtf | Rettifiche | Rettifiche | | rvs | storno | Storno | | sdd | Sepa Direct Debit | SDD, addebito diretto, o domiciliazione bancaria | | spc | Spese comunicazioni | Spese comunicazioni | | spe | spese | Spese | | spo | Prelievo sportello | Prelievo sportello | | ssb | Disposizione SBF stornate/insolute | Disposizione SBF stornate/insolute | | sti | stipendio | Accredito stipendio/pensione | | tas | imposte | Pagamento imposte | | tit | titoli e obbligazioni | Titoli e obbligazioni | | utz | pagamenti generici | Pagamenti generici | | ver | pagamento / versamento | Versamento | ### Stato - Status | Tipo mov. | Tipo op. | stato | descrizione | default | | -------------------------- | ------------------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------- | ------- | | Bonifico | lin , p2p , bon, boi , bap, baf ,gir | ATTESA_AUTOR | da eliminare in attesa di autorizzazione | | | | | ATTESA_AUTOR_GRUPPO | NON IN USO - attesa di autorizzazione gruppo | | | | | ATTESA_CONFERMA_DA_TESORERIA | ATTESA CONFERMA DA TESORERIA | | | | | ATTESA_CONF_RETE | in attesa di conferma da rete | | | | | ATTESA_DI_AUTORIZZAZIONE | in attesa di autorizzazione | | | | | ATTESA_DI_AUTORIZZA_GRUPPO | attesa di autorizzazione gruppo | | | | | ATTESA_TESOR | in attesa di conferma da tesoreria | | | | | AUTORIZZATO_T2S | AUTORIZZATO T2S | | | | | DA_AUTORIZZARE | da autorizzare | | | | | DA_AUTORIZZARE_GRUPPO | da autorizzare gruppo | | | | | DA_AUTORIZZARE_T2S | DA AUTORIZZARE T2S | | | | | DA_CONTABILIZZARE_FTF | Da contabilizzare ftf | | | | | DA_ESEGUIRE | da eseguire | | | | | DA_INVIARE_FTF | da inviare via FTF | | | | | DA_INVIARE_OUT_T2S | Messaggio da inviare in banca diretta senza ulteriore contabilizzazione | | | | | DA_INVIARE_OUT_T2S_DOPO_AUT | da inviare come banca diretta in attesa di autorizzazione | | | | | DA_PREPARARE | da preparare | | | | | INSERITO_RDC_T2S | Messaggio da inviare in banca diretta con contabilizzazione su A7 della banca ordinante | | | | | INSERITO_T2S | INSERITO T2S | | | | | INVIATO | inviato | | | | | ESAURITO | bonifico altro istituto >> ESAURITO >> bonifico riaccreditato all'ordinante perchè rifiutato | X | | | | | bonifico stesso istituto >> ESAURITO >> bonifico accreditato sul conto beneficiario | | | | | | bonifico in entrata >> ESAURITO >> bonifico accreditato sul conto beneficiario | | | | | INVIO_DATA_FUTURA_SEBA | In attesa di maturazione regolamento per invio SEBA | | | | | INVIO_DATA_FUTURA_SEPA | In attesa di maturazione regolamento per invio SEPA | | | | | IN_ATTESA_AUT_CAMBIO_E_CSSE | IN_ATTESA_AUT_CAMBIO_E_CSSE | | | | | IN_ATTESA_DI_BIBO | stato intermedio per banca indiretta quando viene registrato il bibo nella banca mittente | | | | | IN_ATTESA_DI_INVIO | IN_ATTESA_DI_INVIO | | | | | IN_ATTESA_DI_INVIO_E_AUT | da inviare come banca indiretta in attesa di aut. da banca ordinante | | | | | IN_ATTESA_DI_INVIO_E_CSSE | IN_ATTESA_DI_INVIO_E_CSSE | | | | | IN_ATTESA_E_AUT | da inviare come banca indiretta in attesa di aut. da banca mittente | | | | | IN_ATTESA_E_AUT_E_CSSE | IN_ATTESA_E_AUT_E_CSSE | | | | | IN_ATTESA_E_CSSE | IN_ATTESA_E_CSSE | | | | | IN_ATTESA_INVIO_E_AUT_E_CSSE | IN_ATTESA_INVIO_E_AUT_E_CSSE | | | | | IN_ATTESA_PER_AUT_E_CAMBIO | IN_ATTESA_PER_AUT_E_CAMBIO | | | | | IN_ATTESA_PER_AUT_E_CSSE | IN_ATTESA_PER_AUT_E_CSSE | | | | | IN_ATTESA_PER_AUT_E_FISSAZIONE_CAMBIO | cambio a listino inserito in attesa di autorizzazione e di fissazione cambio | | | | | IN_ATTESA_PER_CAMBIO | IN_ATTESA_PER_CAMBIO | | | | | IN_ATTESA_PER_CAMBIO_E_CSSE | IN_ATTESA_PER_CAMBIO_E_CSSE | | | | | IN_ATTESA_PER_CSSE | IN_ATTESA_PER_CSSE | | | | | IN_ATTESA_PER_FISSAZIONE_CAMBIO | cambio a listino inserito in attesa di fissazione cambio | | | | | IN_ATT_PER_SMISTAMENTO | In attesa di smistamento | | | | | IN_ATT_PER_SMISTAMENTO_E_AUT | In attesa di smistamento e autorizzazione | | | | | IN_ATT_PER_SMISTAMENTO_E_CSSE | IN_ATT_PER_SMISTAMENTO_E_CSSE | | | | | IN_ATT_PER_SMIS_AUT_CSSE | IN_ATT_PER_SMIS_AUT_CSSE | | | | | IN_ESECUZIONE | in esecuzione | | | | | PRENOTATO 1 | Prenotato bonifico stesso istituto e bonifico altro istituto italia | | | | | PRENOTATO_LISTINO | prenotato per listino | | | | | PRENOTATO_STESSO_OUT 1 | Prenotazione compravendita divisa o bonifico stesso istituto in divisa | | | | | PRENOTATO_T2S 1 | Prenotato Bonifico altro istituto estero | | | Bonifico Ordini Permanenti | bop | ESAURITO | | X | | Debit Card | crd, pos, atm | NEGAZIONE | Rifiutato | | | | | STORNO | Storno o Annullato | | | | | AUTORIZZAZIONE / PREAUTORIZZAZIONE | Autorizzato / PRE Autorizzato (applicabile nei casi di stazioni di servizio) | | | Credit Card | ccr | ANNULLATO DA POS | | | | | | CASH | | | | | | RETTIFICA | | | | | | SPESA | | X | | | | STORNO | | | | MAV/RAV | mav/rav | Pagato | P (risposta effettiva del servizio) | X | | | | Prenotato | I | | | | | Annullato | A | | | | | Stornato | N | | | | | Non Pagato / Errato | E | | | | | Sconfino | S | | | F24 | f24 | Pagata | | X | | | | Prenotata | | | | | | InSospeso | | | | | | Annullata | | | | | | NonPagata | | | | CBILL | cbi | PAGATO | | X | | | | CANCELLATO | | | | | | INSERITO | | | | | | PRENOTATO | | | | Pago PA | ppa | INSERITO | | | | | | CANCELLATO | | | | | | PAGATO | | X | | | | PRENOTATO | | | | Bollettini | bil | INSERITO | | | | | | PAGATO | | X | | | | CANCELLATO | | | | | | PRENOTATO | | | | | | STORNATO | | | | RiBa | rib | Pagato | | X | | | | Prenotato | | | | | | Addebitato al cedente | | | | Partita prenotata | par | PRENOTATO | | | | Ricarica cellulare | ric | PRENOTATO | | | | | | ESEGUITO | | X | | Ricarica con carta | rat | ESEGUITO | | X | | Sepa Direct Debit | sdd | ESEGUITO | | X | # Linee guida PFM Questo documento descrive le linee guida ed alcuni suggerimenti riguardo al servizio PFM. ## GET getPfmTransactions L'API in questione è la seguente: ```text /api/fabrick/pfm/psd2/fabrick/v4.0/movements/transactions ``` Nel caso in cui la FPP invocasse il servizio senza alcun parametro (come sopra), verranno applicati i valori di default, ovvero: - *dateFilter* sarà *createdModifiedDate* (created || resync) - *toDate* sarà pari alla giornata attuale - *fromDate* sarà pari alla giornata attuale - 1 La suddetta richiesta sarà quindi equivalente alla seguente: ```text /api/fabrick/pfm/psd2/fabrick/v4.0/movements/transactions?dateFilter=createdModifiedDate&fromDate=[today-1]&toDate=[today] ``` I dettagli relativi ai parametri di input ed output sono descritti nel documento specifico PFM. ### Quando invocare l'API? Visti i 4 aggiornamenti quotidiani automatici da parte di Fabrick, suggeriamo di invocare l'API in successione a questi 4 slot. Per sicurezza consigliamo inoltre 1 ora di margine dall'aggiornamento di Fabrick, in quanto a seconda della mole dei dati potrebbero esserci dei ritardi. La FPP potrebbe quindi invocare la **GET getPfmTransactions** nei seguenti slot: 1. 09:30 2. 12:30 3. 15:30 4. 18:30 È possibile invocare l'API in qualsiasi momento, ma ovviamente all'interno delle tre ore di differenza tra uno slot e l'altro, oppure nel lasso temporale tra sera e mattina, la FPP otterrà esattamente lo stesso output, vista la mancanza di aggiornamenti. È quindi consigliato implementare uno scheduler in modo da ottimizzare il numero di richieste quotidiane. Nel caso in cui l'obiettivo della FPP fosse quello di archiviare i dati e non fosse necessario utilizzare i dati della giornata attuale, potrebbe invocare l'API anche una sola volta al giorno. ### Come invocare l'API? Come si può notare dalla documentazione di specifiche, è possibile filtrare per diversi parametri e anche per diverse tipologie di date. Suggeriamo di filtrare per la data *createdModifiedDate* e di impostare come intervallo temporale solamente un giorno, come mostra il seguente esempio: ```text /api/fabrick/pfm/psd2/fabrick/v4.0/movements/transactions?dateFilter=createdModifiedDate&fromDate=[today-1]&toDate=[today] ``` In questo modo si ottimizza la mole di dati in risposta. Ovviamente è necessario che il consenso sia sempre attivo, ovvero che il PSU lo rinnovi prima della scadenza. In caso contrario la FPP dovrà essere predisposta per modificare la data e quindi il lasso temporale di richiesta dati. Se ad esempio il PSU rinnova il consenso 20 giorni dopo la scadenza dello stesso, allora la FPP dovrà richiedere la lista dei movimenti degli ultimi 20 giorni e non solo delle ultime 24 ore. > In base ai comportamenti e alle fasi di contabilizzazione delle varie banche, potrebbe capitare che, a parità di *createdModifiedDate*, il parametro *data* (booking date) sia differente, ad esempio di uno o due giorni nel passato. Se si utilizzasse come filtro solamente la *createdDate*, non si perderebbero i movimenti *inserted*, ma si perderebbero i movimenti *cancelled* o *modified*. ### Archiviazione: quale parametro valutare? Questa sezione contiene una linea guida suggerita per tutte quelle società AISP FPP o TPP che, oltre a recuperare e visualizzare le transazioni dei propri clienti, desiderano archiviarle nei propri database. Purtroppo, i diversi comportamenti delle banche dal punto di vista contabile e della gestione delle transazioni aggiungono un livello di complessità che non ci consente di individuare una regola generale ed efficace. Ovviamente per l’FPP o il TPP che crea un’app che recupera le transazioni da Fabrick solo per visualizzarle e/o mostrarle al proprio cliente, ciò non causa alcun problema, poiché tutte le transazioni sono reali. Il problema potrebbe sorgere se l'FPP o il TPP volessero archiviare le transazioni ricevute in tempo reale all'interno dei propri database: è ovvio che le transazioni odierne non sono né complete né definitive. La lacuna principale è certamente l'impossibilità di fare affidamento su un ID univoco per ogni transazione; infatti, il *referenceId* che corrisponde all'ID della transazione non è un parametro obbligatorio per il regolamento PSD2, oltre al fatto che non è garantito che sia univoco. Per questo e per molte altre ragioni, l'FPP/TPP dovrà basarsi sul parametro *resyncType* in risposta al **GET getPfmTransactions** (vedi documentazione PFM). Nel caso in cui la FPP volesse archiviare i movimenti nel proprio database, consigliamo di basarsi sul parametro *id*. Questo parametro, definito da Fabrick, sarà sempre definitivo e univoco e potrà quindi essere utilizzato come chiave primaria. L'unico punto di attenzione sarà verificare che il movimento non sia ancora in uno stato temporaneo, in quanto in questo caso il parametro *id* potrebbe ancora variare. Per far ciò è necessario valutare il parametro *resyncType* e verificare che sia diverso da *CREATED_TEMPORARY*.