Categoria: Integrazioni

Attraverso il Configuratore iniziale di Rfmcube potrai inserire la chiave API e i parametri necessari per creare il collegamento con il tuo E-commerce e avviare l’import dei dati. 

Siamo sicuri che non hai mai visto un sistema così semplice e alla portata di tutti, anche di chi è completamente a digiuno di programmazione!

Ecco i passaggi per la configurazione automatica: 

1. Effettua la registrazione gratuita a Rfmcube

 Se ancora non ti sei registrato, vai all’indirizzo https://app.rfmcube.com/register e inserisci i tuoi dati.

Ti arriverà una mail di conferma per accedere alla dashboard. 

2. Dai un nome al connector

Una volta effettuato il login con le tue credenziali, atterrerai sulla pagina di configurazione. Dai un nome al tuo Connector (può essere quello della tua azienda, o l’indirizzo del tuo sito web, come preferisci).

3. Imposta i parametri di connessione

Seleziona la tua piattaforma tra quelle disponibili e apri la guida a fianco per sapere dove recuperare i dati necessari alla sincronizzazione. 

Una volta inseriti, il pannello di destra ti dirà se la connessione è andata a buon fine o se ci sono stati eventuali errori da correggere.

4. Fai partire la tua Sync

Scegli quando Rfmcube dovrebbe passare a effettuare il primo Import dei dati, se subito oppure durante la notte.

A seconda delle dimensioni del tuo Storico clienti, potranno volerci dalle 2 alle 12 ore di tempo prima che l’import sia terminato, al termine del quale riceverai una email di notifica e potrai accedere ai tuoi dati!

Perfetto! Ora il tuo Ecommerce è correttamente integrato con Rfmcube.

Potrai ora costruire i tuoi segmenti di marketing in un modo sorprendentemente semplice ed efficace, aggiungendo ai parametri RFM (Recency, Frequency e Monetary) di base ulteriori dati su Clienti e Ordini, come provincia di spedizione, categorie e brand acquistati e molto altro!

Sia che tu usi una piattaforma standard sia che tu abbia un e-commerce custom potresti avere la necessità di creare dei filtri in Rfmcube per le tue strategie di marketing.

In generale è possibile passare tutti i campi che si vogliono, i quali poi verranno usati da Rfmcube per generare dei descrittori che serviranno a loro volta per creare i filtri da utilizzare su Rfmcube.

Per esempio se gli ordini hanno un campo ‘coupon’ che indica al suo interno il codice coupon utilizzato per effettuare l’ordine, è possibile inserirlo nella response mandata ad Rfmcube, il quale poi creerà automaticamente il filtro adatto per poter estrarre una lista di tutti i clienti che hanno fatto un ordine con un determinato coupon.

Un altro scenario molto comune è quello di avere nell’ordine tutte le item che lo compongono con all’interno il nome del prodotto e la/le categorie alle quali appartiene il prodotto acquistato. In questo modo sarà possibile creare dei filtri per prodotto o per categoria di prodotto.

Quali campi passare e come passarli è una scelta che va fatta in base alla tua strategia di marketing da adottare ed ai tipi di filtri che si vogliono avere su Rfmcube. Non ci sono specifiche per dare i nomi alle coppie chiave-valore, ne strutture preferite ad altre, basta che siano correttamente interpretate in formato JSON.

Esempio di struttura di un ordine

Vediamo adesso un esempio che chiarisce quale potrebbe essere la struttura di un ordine con dei campi aggiuntivi.

{
    "id": "1",
    "orderReference": "M000001",
    "status": "7",
    "statusLabel": "Completato",
    "createdAt": "2019-01-19T13:06:39Z",
    "updatedAt": "2019-01-22T20:03:39Z",
    "amount": "55.00",
    "customerId": "1",
    "customerEmail": "customer1@test.rfmcube.com",
    "items": [
        {
            "item_id": "607885",
            "product_id": "34",
            "amount": "55.00",
            "brand": "NIKE",
            "categories": [{
                    "tree": [1, 3, 2073],
                    "name": "Scarpe Ginnastica Verdi",
                    "id": 2073
                },
                {
                    "tree": [1, 3, 2591],
                    "name": "Pantaloni tuta slim",
                    "id": 2591
                }
            ]
        }
    ],
    "delivery_address": {
        "city": "Grosseto",
        "province": "GR"
    }
}

Struttura delle categorie

Nell’esempio riportato sopra va data particolare attenzione alla struttura delle categorie in ogni item dell’ordine. Questo dipende un pò da come sono strutturate le categorie all’interno del tuo e-commerce e dal fatto che un singolo prodotto possa essere associato ad una o più categorie. In questo esempio un prodotto può essere associato a più categorie contemporaneamente.

Solitamente le categorie sono rappresentate da un albero, dove al primo posto sta la categoria radice e via via vengono rappresentate categorie sempre più specifiche. Il consiglio è di usare una lista di id che rappresentano le categorie dalla più generica alla più specifica (del tipo [1,2,45,654] dove la categoria 1 è la root di tutto l’albero e 654 è la categoria a cui è associato effettivamente il prodotto, nonché la più specifica). In questo modo diventa molto facile creare dei filtri che prendono gli ordini di una determinata categoria, a qualunque livello essa sia.

Questa guida ti aiuterà a creare un webservice compatibile con RFMCube e che sarà usato da RFMCube stesso per sincronizzare i dati tra le due piattaforme.

Le request

Le  chiamate vengono fatte ad un endpoint HTTPS, saranno tutte POST e il formato dei dati sarà da entrambi i lati in JSON.

Ogni request include gli header Content-Type: application/json, Accept: application/json e api-key che verrà valorizzato con una chiave alfanumerica creata da voi e che ci comunicherete a lavoro ultimato.

Formato e campi dei dati scambiati

I dati scambiati saranno essenzialmente i clienti e gli ordini. Di seguito vengono descritti i campi ed il loro formato che RFMCube accetta;

Customer

Campo	Descrizione
email	Obbligatorio: rappresenta l’email del customer. Rappresenta la chiave primaria
id	Facoltativo: rappresenta un id univoco per il customer. Di solito viene utilizzato l’id del database. Non è obbligatorio perchè la chiave primaria è rappresentata dal campo email.
createdAt	Obbligatorio: rappresenta la data di creazione del customer. La data è rappresentata nel formato ISO-8601 in UTC. Esempio: 2011-12-03T10:15:30Z
updatedAt	Obbligatorio: rappresenta la data di ultima modifica del customer. La data è rappresentata nel formato ISO-8601 in UTC. Esempio: 2011-12-03T10:15:30Z
firstname	Facoltativo: rappresenta il nome del cliente
lastname	Facoltativo: rappresenta il cognome del cliente

Esempio in JSON:

{
  "email" : "customer1@test.rfmcube.com"
  "id" : "1",
  "createdAt" : "2019-01-19T13:06:39Z",
  "updatedAt" : "2019-01-22T12:16:19Z",
  "firstname" : "Paolo",
  "lastname" : "Rossi"  
}

Order

Campo	Descrizione
id	Obbligatorio: rappresenta un id univoco per l’ordine. Di solito viene utilizzato l’id del database.
orderReference	Facoltativo: Spesso agli ordini viene associato un identificativo univoco diverso dall’id. Se ne hai uno lo puoi inviare, altrimenti verrà utilizzato il campo id
status	Obbligatorio: rappresenta lo stato dell’ordine secondo la tua logica di gestione degli stati. Successivamente una procedura di mappatura degli ordini permette l’associazione degli stati secondo la logica di RFMcube con la tua.
statusLabel	Facoltativo: rappresenta una etichetta associata allo stato dell’ordine. Può essere utile nei casi in cui gestisci gli stati con degli id numerici, difficilmente leggibili.
createdAt	Obbligatorio: rappresenta la data di creazione dell’ordine. La data è rappresentata nel formato ISO-8601 in UTC. Esempio: 2011-12-03T10:15:30Z
updatedAt	Obbligatorio: rappresenta la data di ultima modifica dell’ordine. La data è rappresentata nel formato ISO-8601 in UTC. Esempio: 2011-12-03T10:15:30Z
amount	Obbligatorio: rappresenta il totale dell’ordine, espresso con due decimali, con il punto come separatore tra interi e decimali e senza il simbolo della valuta. Esempio: 1099.99
customerId	Facoltativo: rappresenta l’id univoco di un cliente. E’ facoltativo perchè in alcuni casi i clienti possono fare degli ordini senza essere registrato quindi questo id non è presente. Di fatto il campo che discrimina i clienti è il campo email.
customerEmail	Obbligatorio: rappresenta l’email del cliente che ha effettuato l’ordine. Questo è il campo che effettivamente fa da chiave primaria all’entità cliente.

Esempio in JSON:

{
  "id" : "1",
  "orderReference" : "M000001",
  "status" : "7",
  "statusLabel" : "Completato",
  "createdAt" : "2019-01-19T13:06:39Z",
  "updatedAt" : "2019-01-19T20:03:39Z",
  "amount" : "55.00",
  "customerId" : "1",
  "customerEmail" : "customer1@test.rfmcube.com"
}

Interfaccia del web service

Di seguito vengono elencata le chiamate che vengono effettuate da RFMCube:

Customer per id

POST: [endpoint_url]/customer
PAYLOAD:
{
   "id" : "342"
}

Descrizione: ritorna il customer per l’id specificato nel payload.

Primo customer creato

POST: [endpoint_url]/first_customer

Descrizione: ritorna il primo customer creato. Viene utilizzato per sapere da che data si parte per cercare i customer in fase di sincronizzazione iniziale.

Lista di customer con data di creazione nel range

POST: [endpoint_url]/customers_by_creation
PAYLOAD:
{
   "from" : "2019-01-01T00:00:00Z",
   "to" : "2019-01-02T00:00:00Z"
}

Descrizione: ritorna un array di customer per i quali la data di creazione è compresa tra le due date specificate nel payload.

Lista di customer con data di ultima modifica nel range

POST: [endpoint_url]/customers_by_update
PAYLOAD:
{
   "from" : "2019-01-01T00:00:00Z",
   "to" : "2019-01-02T00:00:00Z"
}

Descrizione: ritorna un array di customer per i quali la data di ultima modifica è compresa tra le due date specificate nel payload.

Ordine per id

POST: [endpoint_url]/order
PAYLOAD:
{
   "id" : "342"
}

Descrizione: ritorna l’ordine per l’id specificato nel payload.

Primo ordine creato

POST: [endpoint_url]/first_order

Descrizione: ritorna il primo ordine creato. Viene utilizzato per sapere da che data si parte per cercare gli ordini in fase di sincronizzazione iniziale.

Lista di ordini con data di creazione nel range

POST: [endpoint_url]/orders_by_creation
PAYLOAD:
{
   "from" : "2019-01-01T00:00:00Z",
   "to" : "2019-01-02T00:00:00Z"
}

Descrizione: ritorna un array di ordini per i quali la data di creazione è compresa tra le due date specificate nel payload.

Lista di ordini con data di ultima modifica nel range

POST: [endpoint_url]/orders_by_update
PAYLOAD:
{
   "from" : "2019-01-01T00:00:00Z",
   "to" : "2019-01-02T00:00:00Z"
}

Descrizione: ritorna un array di ordini per i quali la data di ultima modifica è compresa tra le due date specificate nel payload.

Lista di ordini per id

POST: [endpoint_url]/orders_by_id
PAYLOAD:
{
   "ids" : [ "45", "32", "34" ]
}

Descrizione: ritorna un array di ordini associati agli id specificati nel payload. Viene utilizzato per chiedere ordini che sono in stati transitori, per i quali RFMCube ricontrolla il cambiamento.

PARTE 2: scopri anche come passare addizionali di ordini e clienti nel tuo WebService: https://www.rfmcube.com/campi-extra-e-filtri-rfmcube/