LimitRail - playbook per integratori esterni

Questo playbook spiega come un sistema esterno integra LimitRail per valutare prezzi, limiti, soglie cliente e consumo runtime. LimitRail non apre conti, non esegue pagamenti, non possiede il ledger e non calcola il saldo contabile. Il sistema chiamante esegue l'operazione finanziaria; LimitRail restituisce la decisione di policy.

1. Concetto base

L'integrazione ruota attorno a tre riferimenti.

externalOperationRef non decide la policy. Serve solo a correlare la decisione LimitRail con l'evento del sistema esterno.

2. Autenticazione e scope

Usa OAuth client credentials. Il client ottiene un bearer token con POST /connect/token e poi chiama le API v1.

3. Setup iniziale dell'integratore

Prima di inviare richieste runtime, l'integratore deve leggere il catalogo.

1. GET /v1/products?take=25 Recupera productId, productCode, stato e valuta. Il productId è il valore richiesto oggi dalla registrazione conto; il productCode è il codice business da mappare nel sistema chiamante.

2. GET /v1/operations?take=25 Recupera gli operation code accettati. Il campo code è il valore da inviare come operationCode.

3. GET /v1/policy-dimensions Recupera i dati che possono influenzare regole e contatori. Le dimensioni con source REQUEST_METADATA vanno inviate in metadata; quelle con source ACCOUNT_ATTRIBUTE vanno salvate sul conto.

4. Lifecycle conto

Quando un conto entra nel perimetro LimitRail, registra il contratto:

POST /v1/account-contracts

{
  "externalAccountRef": "ACC_7F3A92_001",
  "productId": "7b2d8b9f-1a4c-4f3b-9c10-35e4b7a98c21",
  "segmentCode": null,
  "openedAtUtc": "2026-07-05T10:00:00Z",
  "attributes": {
    "customer_tier": "STANDARD",
    "residency_country": "ITA"
  }
}

L'integratore non passa la versione del piano condizioni. LimitRail la risolve da prodotto, segmento o assegnazione account-level. Account deal e override di policy sono funzioni backoffice, non campi di onboarding pubblico.

Quando il conto cambia prodotto, segmento, stato o blocco operativo, aggiorna il contratto:

PUT /v1/account-contracts/{id}

Se status = BLOCKED, invia anche blockType e blockReasonCode. Se status = CLOSED, il runtime blocca le valutazioni e il contratto non viene riaperto.

5. Attributi conto

Gli attributi conto sono fatti stabili riutilizzati dalle regole senza inviarli in ogni richiesta. Esempi: customer_tier, residency_country, regulatory_status.

PUT /v1/account-contracts/{id}/attributes

{
  "code": "customer_tier",
  "value": "PREMIUM"
}

LimitRail accetta solo attributi registrati come ACCOUNT_ATTRIBUTE, attivi e compatibili con eventuali valori ammessi.

6. Soglie scelte dal cliente

Alcuni limiti possono essere configurabili dal cliente finale. Il cliente può solo ridurre la soglia entro i confini del prodotto; non può aumentarla oltre il massimo di prodotto.

Lettura soglie disponibili:

GET /v1/accounts/{externalAccountRef}/limit-settings

Impostazione soglia:

PUT /v1/accounts/{externalAccountRef}/limit-settings/{limitRuleCode}

{
  "limitAmount": 200.00,
  "source": "CUSTOMER",
  "reason": "Customer-selected ATM daily amount limit"
}

Per limiti a conteggio usa limitCount. Quando la soglia cliente è attiva, la risposta runtime mostra thresholdSource = CUSTOMER_SETTING.

Le soglie cliente non sono deroghe. Una deroga autorizza temporaneamente un superamento; una soglia cliente rende il conto più restrittivo.

7. Valutazione runtime

La chiamata principale e':

POST /v1/policy/evaluate

{
  "externalAccountRef": "ACC_7F3A92_001",
  "operationCode": "ATM_WITHDRAWAL",
  "amount": 120.00,
  "currencyCode": "EUR",
  "externalOperationRef": "OP_20260705_00001",
  "occurredAtUtc": "2026-07-05T10:05:00Z",
  "metadata": {
    "terminal_country": "ITA"
  },
  "mode": "PREVIEW",
  "idempotencyKey": null
}

metadata deve contenere solo fatti. Esempi corretti: destination_country, terminal_country, resulting_balance_after_operation, average_monthly_balance. Esempi da evitare: high_amount, discounted_fee, domestic_fee, limit_exceeded.

Modalità' runtime

Se la decisione è DENIED_BY_POLICY, il sistema chiamante non deve procedere. Se è ALLOWED, WARNING o FEE_CALCULATED, il chiamante prosegue secondo il proprio processo operativo.

8. Reserve, commit, cancel e reverse

Per flussi asincroni usa due fasi.

1. POST /v1/policy/evaluate con mode = RESERVE_CAPACITY. Se la policy consente l'operazione, LimitRail restituisce capacityReservationId.

2. Quando l'operazione esterna viene confermata:

POST /v1/usage/commit

{
  "capacityReservationId": "2b7e4f0c-6f2a-4d34-a76e-9d91f9a53112",
  "idempotencyKey": "COMMIT_OP_20260705_00001",
  "externalAccountRef": "ACC_7F3A92_001",
  "operationCode": "ATM_WITHDRAWAL",
  "amount": 120.00,
  "currencyCode": "EUR",
  "externalOperationRef": "OP_20260705_00001",
  "occurredAtUtc": "2026-07-05T10:05:00Z",
  "metadata": {
    "terminal_country": "ITA"
  }
}

3. Se l'operazione viene abbandonata prima del commit:

POST /v1/capacity-reservations/{id}/cancel

4. Se un consumo già applicato deve essere compensato:

POST /v1/usage/{id}/reverse

con reversalIdempotencyKey.

La stessa idempotency key con lo stesso payload deve restituire lo stesso esito. La stessa chiave con payload diverso è un errore di integrazione.

9. Come leggere la risposta evaluate

10. Letture utili

Le liste operative sono paginate e devono usare finestre temporali. Non usarle come export massivo.

11. Enum che l'integratore deve conoscere

Usare valori UPPER_SNAKE_CASE.

Gli enum di configurazione pricing e limiti appartengono al manuale operativo, non al payload standard dell'integratore.

12. Checklist integrazione

• Recuperare token con OAuth client credentials.
• Leggere prodotti, operazioni e policy inputs prima del runtime.
• Registrare ogni conto con riferimento opaco.
• Aggiornare stato conto, blocco, segmento e prodotto quando cambiano.
• Salvare come attributi solo fatti stabili.
• Inviare in metadata solo fatti della singola operazione.
• Usare operationCode diretto.
• Non inviare externalSystemCode o externalOperationCode.
• Non inviare conditionPlanVersionId.
• Usare idempotency key per ogni chiamata che scrive stato.
• Leggere decisione, fee, rule results e limit impacts prima di proseguire.