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:

.../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:

.../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:

{
    "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:

...
"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:

/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:

/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:

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:

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.

{
    ...
    "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:

POST {{domain}}/access/transactions/operationType/search
{

}

È possibile filtrare per un valore specifico:

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:

/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:

/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:

/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.