LimitRail - manuale operativo di configurazione

Questo manuale spiega come trasformare requisiti di prodotto in configurazione LimitRail. È pensato per chi configura prodotti, operazioni, dati per le regole, prezzi, limiti, condizioni, soglie cliente, segmenti ed eccezioni.

Il principio guida è semplice: il sistema chiamante invia fatti, LimitRail decide la policy. Ogni regola deve quindi rispondere a una domanda business chiara: quale operazione sto governando, quale dato serve, quale limite o prezzo deve applicarsi, quando la regola deve scattare e come voglio spiegare il risultato.

1. Percorso corretto di configurazione

Segui sempre questo ordine.

1. Crea o verifica il prodotto in Prodotti.
2. Crea gli operation code in Catalogo operazioni.
3. Crea i dati mancanti in Dati per le regole.
4. Crea il piano in Piani condizioni.
5. Configura pricing e limiti in Editor regole.
6. Aggiungi condizioni solo quando una regola non vale sempre.
7. Pubblica la versione quando la bozza è coerente.
8. Collega conti, segmenti o account deal alla versione pubblicata.
9. Verifica il comportamento in Validazione scenari.

Non partire dalle regole se non hai prima chiarito operation code e dati. La regola più pulita diventa ingestibile se il dato che la guida non è stato definito bene.

2. Operation code: il contratto operativo

Una operation è il codice che il sistema chiamante invia a runtime. Se il core manda ATM_WITHDRAWAL, LimitRail deve configurare ATM_WITHDRAWAL. Non serve un layer di mapping.

Quando crei una operation, chiarisci:

• se è in ingresso, in uscita o neutra;
• se richiede importo;
• se deve avere copertura prezzo;
• se deve avere copertura limite;
• quale canale/famiglia usa per raggruppare regole o contatori.

Usa operation code distinti quando il prodotto vuole regole distinte. Usa invece lo stesso canale quando più operation devono condividere un limite. Esempio: SEPA_OUT e SEPA_INSTANT_OUT possono avere prezzi diversi ma condividere un limite del canale SEPA_OUTGOING.

3. Dati per le regole

Un dato per le regole non è un campo descrittivo qualunque. Deve poter cambiare almeno una di queste cose:

• quale regola si applica;
• quale soglia si usa;
• quale contatore viene consumato;
• cosa viene spiegato in audit o nei report.

Tre origini sono importanti.

Non chiedere al chiamante di inviare decisioni già calcolate come high_amount, discounted_fee, domestic_fee o limit_exceeded. Questi sono risultati di policy, non fatti di business.

4. Prezzi: scegli il pattern giusto

I pricing method supportati in V1 sono:

BUNDLE, MINIMUM e MAXIMUM non sono metodi pricing supportati. Il minimo e il massimo sono campi applicabili a una fee calcolata, non metodi autonomi.

4.1 Operazione gratuita esplicita

Usa WAIVER quando vuoi dire: questa operazione è inclusa nel prodotto e deve apparire come fee zero.

Esempio: pagamento carta gratuito.

Configurazione:

• tipo regola: prezzo;
• operation scope: operation code;
• operation code: CARD_PURCHASE;
• calculation method: WAIVER;
• gruppo prezzo: normalmente BASE;
• priorità': coerente con le altre regole dell'operazione.

Effetto runtime: LimitRail restituisce una fee pari a zero. Questo è diverso dal non configurare nessuna pricing rule: con WAIVER rendi esplicita l'inclusione.

4.2 Fee fissa

Usa FIXED quando ogni operazione genera lo stesso importo.

Esempio: bonifico istantaneo da 0,80 EUR.

Configurazione:

• calculation method: FIXED;
• fixed amount: 0.80;
• currency: EUR;
• fee base: OPERATION_AMOUNT o FIXED, secondo l'impostazione disponibile;
• operation code: SEPA_INSTANT_OUT.

Effetto runtime: se la regola matcha, LimitRail restituisce quella fee.

4.3 Fee percentuale con minimo e massimo

Usa PERCENTAGE quando la fee dipende dall'importo.

Esempio: bonifico internazionale allo 0,35%, minimo 1,50 EUR, massimo 12,00 EUR.

Configurazione:

• calculation method: PERCENTAGE;
• percentage rate: 0.0035;
• min amount: 1.50;
• max amount: 12.00;
• currency: EUR;
• operation code: INTERNATIONAL_TRANSFER.

Effetto runtime: LimitRail calcola la percentuale su amount, poi applica minimo e massimo.

4.4 Prime N operazioni incluse, poi fee

Usa TIERED con metrica COUNT.

Esempio: primi 6 prelievi ATM mensili inclusi, dal settimo 0,90 EUR.

Configurazione:

• calculation method: TIERED;
• metric type: COUNT;
• period type: MONTHLY;
• tier application mode: SINGLE_MATCHED_TIER;
• tier charge base: OPERATION_AMOUNT;
• fascia 1: upTo = 6, calculation WAIVER;
• fascia 2: upTo = vuoto, calculation FIXED, amount 0.90;
• operation code: ATM_WITHDRAWAL.

Effetto runtime: LimitRail guarda il consumo già confermato e le reservation attive. Se la chiamata è dentro la quota inclusa, restituisce fee zero; oltre quota restituisce la fee configurata.

4.5 Volume incluso, poi fee

Usa TIERED con metrica AMOUNT quando la soglia dipende dal volume.

Esempio: primi 1.000 EUR mensili di una famiglia operativa inclusi, poi fee fissa per operazione.

Configurazione:

• calculation method: TIERED;
• metric type: AMOUNT;
• period type: MONTHLY;
• fascia 1: upTo = 1000, calculation WAIVER;
• fascia 2: upTo = vuoto, calculation FIXED, amount configurato.

Nota: in V1 questo non calcola automaticamente una fee solo sulla parte eccedente. Decide quale fascia applicare alla nuova operazione.

4.6 Fee sopra soglia di importo

Quando la fee cambia in base all'importo della singola operazione, usa condizioni su amount.

Esempio: P2P gratuito fino a 75 EUR, poi 0,40 EUR.

Configurazione:

• regola 1: WAIVER, condizione amount <= 75;
• regola 2: FIXED 0.40, condizione amount > 75;
• stesso operation code: P2P_PAYMENT.

Effetto runtime: il chiamante invia solo amount; LimitRail sceglie la regola.

5. Composizione prezzi: quando più regole matchano

Se più pricing rule matchano la stessa richiesta, devi decidere se sommarle o sceglierne una.

Usa PricingGroupCode per mettere regole nello stesso gruppo e PricingGroupMode per decidere la selezione.

StopAfterGroup serve quando, dopo aver scelto una fee in un gruppo, non vuoi che gruppi successivi aggiungano altre fee.

Esempio promo premium:

• gruppo SEPA_PRICE;
• regola standard: FIXED 0.60;
• regola premium: WAIVER con condizione customer_tier = PREMIUM;
• modalità' gruppo: BEST_PRICE.

Se il cliente è premium, il motore vede 0,00 e 0,60 e sceglie 0,00.

6. Limiti: scegli metrica, periodo e perimetro

Una limit rule controlla capacità' o soglie.

6.1 Limite su singola operazione

Esempio: bonifico massimo 1.250 EUR.

Configurazione:

• metric type: AMOUNT;
• period type: SINGLE;
• limit amount: 1250;
• operation scope: OPERATION_CODE;
• operation code: SEPA_OUT;
• blocking: true.

Non serve un contatore storico: la regola confronta l'importo della richiesta.

6.2 Limite periodico per operazione

Esempio: massimo 450 EUR ATM al giorno.

Configurazione:

• metric type: AMOUNT;
• period type: DAILY;
• limit amount: 450;
• operation scope: OPERATION_CODE;
• counter scope: ACCOUNT_OPERATION;
• operation code: ATM_WITHDRAWAL;
• blocking: true.

Ogni commit consuma il contatore giornaliero del conto per quell'operazione.

6.3 Limite su numero operazioni

Esempio: massimo 4 prelievi ATM al giorno.

Configurazione:

• metric type: COUNT;
• period type: DAILY;
• limit count: 4;
• counter scope: ACCOUNT_OPERATION.

Il motore conta le operazioni, non il loro importo.

6.4 Limite condiviso per canale

Esempio: SEPA_OUT e SEPA_INSTANT_OUT condividono il limite giornaliero del canale bonifici.

Configurazione:

• operation scope: OPERATION_CHANNEL;
• channel code: SEPA_OUTGOING;
• counter scope: ACCOUNT_CHANNEL;
• metric type e periodo secondo la soglia.

Questo evita due plafond separati quando il business vuole un solo plafond.

6.5 Limite globale conto

Esempio: massimo 10.000 EUR mensili complessivi su tutte le operazioni governate.

Configurazione:

• operation scope: GLOBAL;
• counter scope: ACCOUNT_GLOBAL;
• metric type: AMOUNT;
• period type: MONTHLY.

Usalo per esposizioni complessive di conto, non per una singola operazione.

6.6 Limite separato per dimensione

Esempio: massimo 5.000 EUR mensili per paese destinazione.

Configurazione:

• crea dimensione destination_country;
• abilita la dimensione per separare contatori;
• counter scope: CUSTOM_DIMENSIONS;
• aggiungi destination_country come dimensione dello scope;
• metric type: AMOUNT;
• period type: MONTHLY.

Attenzione: usa questa opzione solo per valori controllati e a bassa cardinalita'. Paese, valuta o profilo sono adatti. Transaction id, merchant id o descrizioni libere non sono adatti.

7. Condizioni: quando una regola deve scattare

Una regola senza condizioni vale sempre nel proprio perimetro. Aggiungi condizioni quando la regola deve valere solo in un caso.

Esempi:

• amount > 75 per applicare una fee sopra soglia;
• destination_country != ITA per fee internazionale;
• customer_tier = PREMIUM per esenzione premium;
• regulatory_status IN [UNDER_REVIEW, RESTRICTED] per blocco cautelativo;
• average_monthly_balance < 200 per applicare canone.

Operatori supportati:

8. Soglie scelte dal cliente

Una soglia cliente rende il prodotto più restrittivo per un conto. Non è una deroga e non può superare il limite standard.

Esempio: il prodotto consente 450 EUR ATM al giorno, ma il cliente sceglie 200 EUR.

Configurazione sulla limit rule:

• abilita "cliente può scegliere questo limite";
• imposta minimo cliente;
• imposta massimo cliente;
• salva la regola e pubblica la versione.

Operatività':

• il canale o l'integratore legge i limiti configurabili del conto;
• imposta la soglia scelta dal cliente;
• il runtime usa CUSTOMER_SETTING prima del default prodotto.

9. Segmenti, account deal e policy exception

Usa il segmento quando una categoria di conti deve avere una policy diversa: RETAIL, PREMIUM, BUSINESS.

Usa l'account deal quando un singolo conto ha condizioni negoziate o eccezionali. L'account deal è un'assegnazione account-level di policy e batte segmento e prodotto.

Usa la policy exception quando devi consentire o tracciare il superamento temporaneo di una regola bloccante senza cambiare la policy standard.

10. Validazione scenari

La validazione temporale serve a controllare comportamento e contatori nel tempo. Non limitarti a provare una singola chiamata.

Per ogni policy importante verifica:

• prima operazione dentro soglia;
• operazione che consuma l'ultimo spazio disponibile;
• operazione che supera la soglia;
• caso con soglia cliente;
• caso con metadata mancante;
• caso con eccezione;
• caso dopo cambio periodo, per esempio giorno o mese successivo.

La policy è pronta quando riesci a spiegare per ogni step:

• quale regola ha deciso;
• quale fee è stata calcolata;
• quale contatore è stato consumato;
• perché una richiesta è stata bloccata o consentita.

11. Cose da non configurare in V1

Non usare questi pattern come se fossero supportati:

• pricing method BUNDLE;
• pricing method MINIMUM o MAXIMUM;
• fee automatica solo al commit;
• fee automatica al reverse tecnico;
• fee calcolata solo sulla parte eccedente con REMAINING_AMOUNT;
• contatori separati per dati ad alta cardinalita';
• operation mapping tra codice esterno e codice interno.

Alternative corrette:

• per quote incluse usa TIERED;
• per minimo/massimo usa i campi MinAmount e MaxAmount;
• per storni con fee usa una operation dedicata, per esempio TRANSFER_RETURN;
• per varianti operative usa operation code e canali coerenti;
• per promozioni usa condizioni e pricing group.

12. Checklist finale prima della pubblicazione

Prima di pubblicare una versione, controlla:

• tutte le operation richieste dal prodotto esistono;
• le operation con copertura obbligatoria hanno almeno una regola prezzo o limite;
• i dati richiesti dalle condizioni sono registrati e attivi;
• i limiti a contatore hanno periodo e scope corretti;
• le fee tiered hanno almeno due fasce e fascia finale aperta;
• le soglie cliente hanno min/max coerenti;
• i gruppi prezzo non sommano fee per errore;
• la validazione temporale copre casi positivi e negativi;
• il calling system non deve inviare decisioni già calcolate.