3 settembre 2026Integrazioni

Rfmcube + coding agent: estendi la portata delle tue analisi con l'AI

Negli ultimi tempi l’AI ha rivoluzionato il modo con cui ci approcciamo ai software, e Rfmcube non fa eccezione.

Se hai già un coding agent come Claude Code, OpenAI Codex CLI o Gemini CLI, puoi interrogare i dati del tuo connector in linguaggio naturale, estendendo così le possibilità di analisi sui segmenti.

La particolarità dei coding agent è infatti quella di eseguire comandi sul tuo computer ed effettuare chiamate di rete autenticate, cosa che non potresti fare con una semplice chat AI.

RFMcube offre anche un connector MCP remoto (mcp.rfmcube.com), aggiungibile in Claude.ai/Desktop o altri client compatibili senza installare nulla in locale — utile per domande dirette e puntuali (“dammi il profilo di questo cliente”, “che segmenti ho configurato”), da qualunque dispositivo, anche senza un coding agent.

Questa guida resta la strada giusta per un’altra cosa: analisi statistiche vere su segmenti grandi (media, mediana, percentili, distribuzioni, confronti multi-segmento), ovvero quel tipo di domande a cui il solo tool-calling non può rispondere in modo affidabile, perché richiede eseguire calcoli su migliaia di record, non solo leggerli.

Cosa ti serve

Un account RFMcube con connector configurato
Un abbonamento o account per uno dei tre coding agent elencati sotto
Il documento di contesto rfmcube-api-context.md (copia-incolla il codice sotto)

Ovviamente non serve saper programmare: una volta avviato l'agente, tutto quello che ti serve lo chiedi in chat, in italiano.

1. Recupera la tua chiave API

Vai nelle impostazioni del tuo connector RFMcube, sezione Chiave API, e copiala.

Trattala come una password: chi la ottiene può leggere tutti i dati clienti del tuo account. Non condividerla via email o chat non protette e non incollarla in pagine web o repository pubblici.

2. Installa un coding agent

Scegli quello per cui hai già un account: per questo scopo funzionano allo stesso modo.

Agente	Avvio da terminale	File di contesto letto automaticamente
Claude Code	`claude`	`CLAUDE.md` nella cartella del progetto
OpenAI Codex CLI	`codex`	`AGENTS.md` nella cartella del progetto
Gemini CLI	`gemini`	`GEMINI.md` nella cartella del progetto

Per l'installazione segui la documentazione ufficiale dell'agente che hai scelto: le istruzioni cambiano nel tempo e variano tra Windows, macOS e Linux.

3. Apri una cartella nell'agente

L'agente lavora sempre "dentro" una cartella del tuo computer: è lì che leggerà il file di contesto ed è lì che custodirà la tua chiave. Avvia l'agente — dall'app desktop o dall'estensione per VS Code è un click — e indicagli una cartella dedicata a queste analisi. Il nome non conta: quello che conta è che sia una cartella riservata a questo uso.

Se usi lo stesso agente anche per altri progetti, non riutilizzare una cartella che contiene già un file di contesto (CLAUDE.md, AGENTS.md o GEMINI.md): il contesto RFMcube finirebbe per sovrascriverlo. Una cartella a parte ti evita anche di avere le istruzioni RFMcube caricate quando stai lavorando a qualcos'altro.

Da qui in avanti non tocchi più né file né comandi: creare il file di contesto, salvare la chiave in modo sicuro, tutto il resto lo chiedi all'agente in linguaggio naturale ed è lui a eseguirlo al posto tuo.

4. Fornisci contesto e chiave, in chat

Incolla nella chat dell'agente il contenuto del documento rfmcube-api-context.md che trovi in fondo a questo articolo.

Poi, nello stesso messaggio o subito dopo (va bene in entrambi i modi), aggiungi questa richiesta — sostituendo <incolla qui la tua chiave> con la tua vera api-key:

Salva questo come file di contesto del progetto (CLAUDE.md per Claude Code, AGENTS.md per Codex CLI, GEMINI.md per Gemini CLI). Poi crea un .gitignore che escluda .env e salva la mia chiave RFMcube in un file .env locale come RFMCUBE_API_KEY — mai nel file di contesto: incolla qui la tua chiave

Premi invio e aspetta: l'agente ti risponderà elencando cosa ha creato (es. "ho creato CLAUDE.md, .gitignore e .env").

⚠️ Prima di andare avanti, verifica una cosa sola: chiedi conferma che l'agente abbia messo .env nel .gitignore prima di scriverci la chiave. Basta chiedergli "hai escluso .env dal git prima di salvarci la chiave?" — così la credenziale non rischia di finire per sbaglio in un repository condiviso in futuro.

5. Fai le tue domande

Qualche esempio con cui partire:

"Dammi i 5 clienti più profittevoli di un segmento"
"Quanti clienti ho nel segmento Champions e qual è la spesa media?"
"Confronta i segmenti X e Y"
"Quali segmenti avanzati ho configurato?"

L'agente legge il contesto, capisce come chiamare le API RFMcube e usa la tua RFMCUBE_API_KEY per interrogarle davvero, sui tuoi dati.

Una volta presa dimestichezza con le domande semplici e verificata la correttezza delle risposte, puoi iniziare ad utilizzare l'AI per generare analisi avanzate sui tuoi dati:

crea un grafico che mostra la curva di distribuzione dei valori frequency e latency per i clienti di un dato segmento
qual'è la % di clienti ha effettuato il primo acquisto lo stesso giorno della registrazione? Mostrami la distribuzione giorno per giorno (giorno 0, giorno 1, ... fino al giorno 9), con un'ultima fascia aggregata per chi ha aspettato più di 10 giorni.

e molto altro in base a quali sono i tuoi obiettivi di business.

Cosa non aspettarti

Non funziona incollando il contesto in una chat web semplice. Interfacce come claude.ai, chatgpt.com o gemini.google.com, senza strumenti di esecuzione o connettori attivi, non possono effettuare una chiamata HTTP autenticata verso un servizio esterno. Serve un coding agent con esecuzione locale, come descritto sopra.

Non condividere la chiave API. Vale quanto detto al punto 1: è l'equivalente di una password sui tuoi dati clienti.

Una risposta incompleta non è necessariamente un errore dell'agente. Se un campo risulta sempre vuoto, alcuni comportamenti dipendono dalla configurazione del tuo specifico connector: scrivi al supporto RFMcube per una verifica.

Scopri sul tuo connector se anche i tuoi clienti confermano questo trend! ➡️ Recupera la chiave api dal tuo connector

# Contesto API RFMcube — Istruzioni per Coding Agent (Claude Code / Codex CLI / Gemini CLI)
Incolla questo file all’inizio di una sessione del tuo coding agent insieme alla tua api-key del connector RFMcube. Da quel momento l’agente saprà come interrogare, aggregare e analizzare i tuoi dati RFM in tempo reale.
Prerequisito: Serve un agente che possa eseguire codice/comandi con accesso di rete (Claude Code, OpenAI Codex CLI, Gemini CLI, o equivalenti). Un normale chat web (claude.ai, chatgpt.com, gemini.google.com senza strumenti di esecuzione) NON può eseguire queste chiamate: leggerà questo documento ma non avrà modo di contattare davvero api.rfmcube.com.
La tua chiave
La tua api-key del connector si trova nelle impostazioni RFMcube, voce “Chiave Api”. Non scriverla mai in un file che finisce in un repository o in una chat pubblica. Passala al tuo agente come variabile d’ambiente, es.:
export RFMCUBE_API_KEY="la-tua-chiave"
e chiedigli di leggerla da lì (process.env.RFMCUBE_API_KEY in Node, os.environ["RFMCUBE_API_KEY"] in Python, $RFMCUBE_API_KEY in bash), mai di incollarla nel codice.
? REGOLE CRITICHE PER L’AGENTE (PRIVACY & PERFORMANCE)
1. Privacy & GDPR (Data Minimization alla fonte):

Quando analizzi o aggreghi un intero segmento, evita di richiedere email nell’array fields della richiesta API POST /customers_by_segment — è un campo tecnicamente valido (vedi lista sotto), ma includerlo di default in un’analisi aggregata espone PII non necessaria al contesto dell’LLM. Richiedila solo se l’utente chiede esplicitamente un export/elenco nominativo (es. per un invio email o un export verso un CRM).
Attenzione ai metaFields: l’oggetto può contenere dati anagrafici (es. telefono, indirizzo). Non scaricare o stampare mai l’intero oggetto senza averne prima verificate le chiavi.
Identificazione sicura: Se l’utente chiede una lista esplicita dei migliori clienti (es. “i 5 top spender”) senza scopo di export/contatto, restituisci solo il loro externalId o l’id interno di RFMcube, evitando la stampa a schermo di email o nominativi.

2. Gestione dei Grandi Numeri (Evita il Token Overflow):

I segmenti possono contenere decine di migliaia di clienti. NON stampare mai l’array JSON grezzo nello standard output.
Scrivi sempre uno script locale (Python/Node.js) che chiama l’API e manipola l’array in memoria.
Fai stampare allo script SOLO la sintesi finale (es. tabelle riassuntive, medie, percentili).

3. Calcolo Locale Obbligatorio:

L’API non restituisce un oggetto con le medie o le somme pre-calcolate dell’intero segmento: restituisce l’elenco dei singoli clienti con le rispettive metriche individuali (aov, total, recency, ecc.).
Per rispondere a domande su medie, somme o distribuzioni di un segmento, scarica i soli campi numerici strettamente necessari e calcola le metriche localmente tramite codice. Questo ti permette anche di calcolare indicatori avanzati non presenti nell’interfaccia web (es. mediana, deviazione standard, percentili).

Endpoint e Rate Limit
Endpoint Base: https://api.rfmcube.com/v1
Ogni richiesta: HTTPS, POST o GET a seconda dell’endpoint, header obbligatori:
content-type: application/json
api-key: &lt;la tua chiave&gt;
Rate limit: 2 richieste/secondo. Oltre, il server risponde HTTP 429 — aspetta e riprova con backoff, non ignorare l’errore.
I 6 Endpoint Supportati
1. Profilo RFM di un cliente
POST /customer_stats
{ "id": "342", "email": "[email protected]", "segmentIds":  }
Passa id oppure email, non serve entrambi. segmentIds è opzionale: se presente, verifica l’appartenenza solo a quei segmenti (risposta più veloce).
Risposta reale (nota: nidificata, non piatta):
{
  "customer": {
    "id": "...", "externalId": "342", "email": "[email protected]",
    "createdAt": "...", "updatedAt": "...",
    "firstTransaction": "...", "lastTransaction": "...",
    "totalTransactions": 11, "total": 344.06, "aov": 31.28,
    "recencyRank": 2, "frequencyRank": 5, "monetaryRank": 4, "rfmScore": 254,
    "longevity": 1237, "recency": 108, "latency": 113,
    "metaFields": { "newsletter": "1" },
    "orders": [],
    "segments": [{ "id": 1, "name": "Adv Segment A" }],
    "lastStatsUpdate": "...", "notes": null
  },
  "segments": [{ "id": 1, "name": "Adv Segment A" }]
}
Attenzione ai metacampi: metaFields contiene i campi extra a livello CLIENTE configurati sul tuo connector (variano da connector a connector). I metacampi a livello ORDINE non sono esposti da questa API: l’array orders è sempre vuoto.
2. Lista clienti di un segmento
POST /customers_by_segment
{ "id": 2, "fields": ["id", "rfmScore", "total", "aov"] }
Importante: Il parametro id deve contenere l’ordinalId del segmento avanzato (ricavabile dall’endpoint 5).
Nomi di campo validi per fields (usarne altri causa HTTP 500, non un errore “morbido”): email, id, externalId, createdAt, updatedAt, firstTransaction, lastTransaction, totalTransactions, total, aov, recencyRank, frequencyRank, monetaryRank, rfmScore, longevity, recency, latency, metaFields, orders, segments, lastStatsUpdate, notes. email è valido ma va richiesto solo quando serve davvero un export nominativo — vedi regola privacy sopra.
Non esistono come nomi diretti frequency e monetary (danno 500): il vero “frequency” è totalTransactions, il vero “monetary” è total.
3. Clienti aggiornati da una data in poi
POST /customers_stats_updated_same_or_after
{ "updateDate": "2024-04-04", "fields": ["id", "rfmScore", "total"] }
updateDate in formato YYYY-MM-DD, senza ora né fuso. Stessi nomi di fields del punto 2.
4. Statistiche dei segmenti base (funnel)
GET /stats/segmentsfunnel
Restituisce { total, recency: [{name, score, value}], frequency: [...], monetary: [...] } — i numeri del funnel RFM classico.
5. Lista segmenti avanzati (Mappatura Nomi → ID)
GET /advanced_segments
Restituisce un array di { ordinalId, name, filter: { baseSegments: { recency, frequency, monetary }, predicateBlocks: [...] } }. Usa ordinalId (non id) per riferirti a un segmento negli altri endpoint. Utile anche per scoprire quali metacampi esistono su questo connector: guarda dentro predicateBlocks le chiavi con context: "meta_customer" o "meta_order".
6. Lista segmenti base (fasce RFM)
GET /base_segments
Restituisce un oggetto diretto (non un array) { time, recency: {reverse, items: [...]}, frequency: {...}, monetary: {...} } — le fasce (di solito 4 per asse) su cui si basano tutti i segmenti avanzati. Verificato contro due connector reali distinti: entrambi rispondono con un oggetto, non con un array — se un’altra fonte mostra [{...}] con parentesi quadre, non è la forma osservata realmente.
Pattern di Ragionamento per l’Agente
Pattern A: Analisi Aggregata di un Segmento
(Es. “Qual è la spesa media e la recenza del segmento Clienti VIP?”)

Chiama GET /advanced_segments per individuare l’ordinalId corrispondente al nome del segmento.
Esegui uno script locale che chiama POST /customers_by_segment richiedendo solo ["id", "total", "aov", "recency"].
Lo script calcola in memoria: numero utenti, totale spesa, spesa media, AOV medio e recenza media.
Lo script stampa a video unicamente la tabella riassuntiva finale.

Pattern B: Calcoli Avanzati Fuori Piattaforma
(Es. “Qual è la mediana di spesa e la distribuzione dei percentili dei Dormienti?”)

Ricava l’ordinalId da GET /advanced_segments.
Esegui uno script locale che scarica i dati chiedendo solo ["id", "total"].
Tramite librerie locali (es. numpy/pandas o funzioni JS), calcola mediana, varianza o percentili.
Stampa a video l’esito dei calcoli.

Pattern C: Confronto tra Segmenti
(Es. “Metti a confronto il segmento Campioni con i Nuovi Clienti”)

Identifica i due ordinalId da GET /advanced_segments.
Esegui due chiamate a POST /customers_by_segment recuperando solo i campi numerici d’interesse.
Genera ed emetti a schermo una tabella comparativa affiancata dei KPI principali.

Pattern D: Discovery dei Metacampi Personalizzati
(Es. “Quali campi o tag extra abbiamo sui nostri clienti?”)

Chiama GET /advanced_segments e analizza l’array predicateBlocks estraendo le chiavi meta_customer e meta_order.
In alternativa, chiama POST /customer_stats per un ID specifico ed estrai le chiavi dell’oggetto metaFields.
Elenca all’utente la lista delle variabili personalizzate rilevate.

Esempi di domande supportate da rivolgere all’Agente
Puoi rivolgere all’agente domande in linguaggio naturale come:

“Dammi il profilo completo e il punteggio RFM del cliente con externalId X”
“Qual è il segmento avanzato con il maggior valore economico e quanti clienti contiene?”
“Esegui un confronto tra il segmento X e il segmento Y su spesa media, frequenza d’acquisto e recenza.”
“Quali metacampi e dati personalizzati sono disponibili sul mio connector?”
“Quanti clienti sono stati aggiornati a partire dal 2024-01-01 e qual è il loro rfmScore medio?”

Rfmcube + coding agent: estendi la portata delle tue analisi con l'AI

Cosa ti serve

1. Recupera la tua chiave API

2. Installa un coding agent

3. Apri una cartella nell'agente

4. Fornisci contesto e chiave, in chat

5. Fai le tue domande

Cosa non aspettarti

La tua chiave

? REGOLE CRITICHE PER L’AGENTE (PRIVACY & PERFORMANCE)

Endpoint e Rate Limit

I 6 Endpoint Supportati

1. Profilo RFM di un cliente

2. Lista clienti di un segmento

3. Clienti aggiornati da una data in poi

4. Statistiche dei segmenti base (funnel)

5. Lista segmenti avanzati (Mappatura Nomi → ID)

6. Lista segmenti base (fasce RFM)

Pattern di Ragionamento per l’Agente

Esempi di domande supportate da rivolgere all’Agente

Articoli correlati