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.
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.mdper Claude Code,AGENTS.mdper Codex CLI,GEMINI.mdper Gemini CLI). Poi crea un.gitignoreche escluda.enve salva la mia chiave RFMcube in un file.envlocale comeRFMCUBE_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
.envnel.gitignoreprima 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
-
nel segmento [nome segmento], che percentuale 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.
# 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.:
```bash
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: <la tua chiave>
```
**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": "customer@test.com", "segmentIds": [35, 38] }
```
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):
```json
{
"customer": {
"id": "...", "externalId": "342", "email": "customer@test.com",
"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?")
1. Chiama `GET /advanced_segments` per individuare l'`ordinalId` corrispondente al nome del segmento.
2. Esegui uno script locale che chiama `POST /customers_by_segment` richiedendo solo `["id", "total", "aov", "recency"]`.
3. Lo script calcola in memoria: numero utenti, totale spesa, spesa media, AOV medio e recenza media.
4. 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?")
1. Ricava l'`ordinalId` da `GET /advanced_segments`.
2. Esegui uno script locale che scarica i dati chiedendo solo `["id", "total"]`.
3. Tramite librerie locali (es. numpy/pandas o funzioni JS), calcola mediana, varianza o percentili.
4. Stampa a video l'esito dei calcoli.
**Pattern C: Confronto tra Segmenti**
(Es. "Metti a confronto il segmento Campioni con i Nuovi Clienti")
1. Identifica i due `ordinalId` da `GET /advanced_segments`.
2. Esegui due chiamate a `POST /customers_by_segment` recuperando solo i campi numerici d'interesse.
3. 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?")
1. Chiama `GET /advanced_segments` e analizza l'array `predicateBlocks` estraendo le chiavi `meta_customer` e `meta_order`.
2. In alternativa, chiama `POST /customer_stats` per un ID specifico ed estrai le chiavi dell'oggetto `metaFields`.
3. 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?"
Potrebbero interessarti anche:
