Banking as a Service

Visualizza come Markdown

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:

https://api.fabrick.com/api/gbs/banking/v4.0/accounts

Esempio di richiesta

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

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

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:

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.

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)

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

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.