Integra il tuo ecommerce con le API di RFMcube
DISCLAMER:
Perché non è il metodo consigliato?
- va reinventata una logica complessa e soggetta ad errori come paginazione, reinvio in caso di problemi di rete, aggiornamento della struttura dati delle entità;
- nel caso ci siano dei problemi inaspettati da parte dell’e-commerce nell’invio dei dati, dovrà essere rifatta la procedura di import per essere sicuri della consistenza dei dati;
- nel medio-lungo periodo richiede più ore di sviluppo da parte del programmatore che la implementa, perché se ad esempio si vuole aggiungere un campo per fare dei filtri, andrà eseguita da capo la procedura di import dei dati in modo manuale;
- è pensata sia per e-commerce molto piccoli che per e-commerce con grandi quantità di dati;
- le request che facciamo vanno a richiedere ordini e clienti in range molto ristretti proprio per non sovraccaricare entrambi i server;
- è possibile decidere quando vengono fatte le request (di notte di solito), creare delle viewport entro le quali è possibile farle e gestire in modo completamente automatico eventuali tentativi falliti;
- se c’è la necessita di aggiungere un campo per fare filtri basta esporlo nel webservice ed Rfmcube effettuerà automaticamente la sync di tutto lo storico senza necessità di interventi tecnici;
- è possibile interrompere la sync in qualunque momento e poi riattivarla successivamente, Rfmcube penserà a prendere i dati necessari mantenendo la consistenza dei dati;
Quando usare le API
Se la tua piattaforma e-commerce non ha delle API da chiamare per raccogliere i dati su clienti ed ordini, Rfmcube mette a disposizione la propria API attraverso la quale mandare i tuoi dati.
Per utilizzare le API di Rfmcube devi avere un account ed un connector creato selezionando come tipo di piattaforma Utilizza le API di Rfmcube. Se la piattaforma non è corretta il server restituisce il codice http 406.
L'API è accessibile creando delle request HTTPS al seguente endpoint:
https://api.rfmcube.com/v1Le request
Le request devono essere inviate su HTTPS ed il contenuto del payload deve essere JSON (application/json). Ogni request deve includere gli header content-type: application/json e api-key che verrà valorizzato con la chiave API del tuo connector.
La chiave API viene generata automaticamente e può essere trovata nelle impostazioni del tuo connector.
Limitazioni
Dimensione request
La dimensione massima di una request è di 200MB. Nel caso in cui questo limite venga superato, il server restituisce il codice http 416.
Limiti request per secondo
E' possibile effettuare 2 request per secondo. Superato questo limite il server restituisce il codice http 429.
Primi passi per l'integrazione
Per iniziare subito la sincronizzazione con RFMcube è necessario inviare i dati relativi alle due entità fondamentali che compongono l'analisi RFM, i clienti e gli ordini.
Sta interamente allo sviluppatore il dovere di integrare i dati in modo coerente, mettendo in atto tutti gli accorgimenti necessari a garantire la consistenza dei dati, anche in caso di errori. Va quindi sviluppata una procedura che fa la sincronizzazione iniziale dei dati e poi successivamente invia Clienti e Ordini modificati o appena creati.
Se hai dei dubbi non esitare a contattarci!
Importa Clienti e Ordini#
POST: /import
PAYLOAD:
{
"overwriteDescriptors": false,
"triggerIntegrations": false,
"recalculateStats": false,
"customers": [
{
"email": "[email protected]",
"createdAt": "2020-01-01T13:06:39Z",
"updatedAt": "2020-01-01T13:06:39Z",
"id": "1",
"orders": [
{
"id": "1",
"createdAt": "2020-01-01T13:30:39Z",
"updatedAt": "2020-01-01T13:30:39Z",
"amount": 85.85,
"status": "10",
"statusLabel": "Completato",
"delivery": {
"province": "MI"
},
"items": [
{
"item_id": 1342,
"product_id": 43421,
"brand": "nike"
},
{
"item_id": 1340,
"product_id": 43420,
"brand": "nike"
}
]
}
]
}
]
}
Descrizione: il processo di import non è sincrono e può richiedere molto tempo. Questa chiamata ritorna immediatamente un processId che può essere utilizzato per richiedere informazioni sull'operazione in corso, utilizzando la chiamata descritta in questa guida.
Il campo overwriteDescriptors determina se sovrascrivere la struttura dei metacampi creata in precedenza sul connector. Se questo valore è impostato a true deve essere presente almeno un ordine nella chiamata.
Impostando triggerIntegrations a true vengono avviate le sincronizzazioni con i software terzi a cui il connector è integrato.
Impostando recalculateStats a true vengono ricalcolate le statistiche del connector.
I campi in grassetto sono obbligatori ed essenziali per Rfmcube. Tutti gli altri campi possono essere definiti a piacere. Rfmcube penserà a creare i descrittori adeguati.
Il campo id del customer non è obbligatorio, nel caso sia un utente guest con solo l'email valorizzata, Rfmcube lo gestirà come tale.
I campi status e statusLabel non sono obbligatori, ma nel caso vengano importati ordini sia completati che non vanno specificati per riuscire a fare il mapping degli ordini. Nel caso in cui non vengono passati gli stati degli ordini va comunque creato il mapping nella configurazione del connector.
Aggiorna Cliente#
POST: /merge_customer
PAYLOAD:
{
"triggerIntegrations": false,
"customer": {
"id": "1",
"email": "[email protected]",
"createdAt": "2020-01-01T13:06:39Z",
"updatedAt": "2020-01-01T13:06:39Z"
}
}
Descrizione: Aggiunge un nuovo cliente o aggiorna un cliente già esistente. Questa chiamata aggiorna solo i dati del Cliente e non modifica gli ordini ad esso associati.
Impostando triggerIntegrations a true il contatto viene sincronizzato in tempo reale con i software terzi a cui il connector è integrato.
Aggiorna Ordine#
POST: /merge_order
PAYLOAD:
{
"triggerIntegrations": false,
"order": {
"id": "1",
"createdAt": "2020-01-01T13:30:39Z",
"updatedAt": "2020-01-01T13:30:39Z",
"amount": 85.85,
"customerEmail": "[email protected]",
"customerId": "1",
"status": "10",
"statusLabel": "Completato",
"delivery": {
"province": "MI"
},
"items": [
{
"item_id": 1342,
"product_id": 43421,
"brand": "nike"
},
{
"item_id": 1340,
"product_id": 43420,
"brand": "nike"
}
]
}
}
Descrizione: Aggiunge un nuovo ordine o aggiorna un ordine già esistente.
I campi status e statusLabel non sono obbligatori, ma nel caso vengano importati ordini sia completati che non vanno specificati per riuscire a fare il mapping degli ordini. Nel caso in cui non vengono passati gli stati degli ordini va comunque creato il mapping nella configurazione del connector.
Impostando triggerIntegrations a true il contatto collegato all'ordine viene sincronizzato in tempo reale con i software terzi a cui il connector è integrato.
Elimina Cliente#
POST: /delete_customer
PAYLOAD:
{
"id": "321",
"email": "[email protected]"
}
Descrizione: Elimina completamente il cliente e tutti i suoi ordini associati. Puoi passare solo l'id, solo l'email o entrambi. Nel caso siano passati entrambi viene cercato prima per id e poi per email.
Nota: se stai cancellando il cliente per questioni legate al suo consenso alla profilazione, potresti decidere di passare i dati del cliente anonimizzati, in questo modo non cambieranno le statistiche globali.
Informazioni sul processo di import#
GET: /processes/{processId}
RESPONSE:
{
"processId": 2,
"createdAt": "2020-10-16T22:01:05Z",
"updatedAt": "2020-10-16T22:01:16Z",
"status": "completed",
"type": "IMPORT_CUSTOMERS_API",
"data": {
"processedCustomers": 105,
"totalCustomers": 105
"processedOrders": 0
"totalOrders": 960
}
}
Descrizione: Richiedi informazioni su un processo creato con l'import dei contatti.
Soluzioni alternative
In alternativa è possibile creare un web service secondo le nostre specifiche al quale RFMCube effettua le chiamate.
Questa soluzione può sembrare più laboriosa ma in realtà è molto più semplice da implementare e lascia a Rfmcube l'onere di garantire la consistenza fra i dati presenti nelle due piattaforme.
La vostra API dovrà ricevere le request da Rfmcube, fare delle query su database secondo i filtri passati e restituire il risultato in formato JSON.
Per approfondire leggi l'articolo: Creazione di un web service Rfmcube compliant