Integra il tuo ecommerce con le API di RFMcube

DISCLAMER:

Stiamo deprecando l’uso del metodo con le api per sincronizzare l’e-commerce con Rfmcube. E’ un metodo che può essere utile in prima battuta per provare Rfmcube, ma che in una fase successiva va sostituito con un webservice compliant con Rfmcube.

Perché non è il metodo consigliato?

L’integrazione tramite API rispetto alla creazione di un webservice compliant può sembrare più semplice ed immediata da realizzare ma ha molti svantaggi ed una serie di problemi di natura tecnica che a primo impatto non sono percettibili ma che la rendono meno affidabile:

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;

La modalità webservice ha tutta una serie di vantaggi che la rendono preferibile:

è 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;

Abbiamo seguito tante integrazioni custom e alla fine il webservice si e’ sempre rivelato il più efficace e meno soggetto a bug. Riusciamo oltretutto a dare un supporto tecnico dedicato. Nel caso delle integrazioni con le API non c’è supporto tecnico perché diventiamo un soggetto che riceve passivamente i dati e non abbiamo un controllo diretto su quello che accade.

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/v1

Le 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 50MB. Nel caso in cui questo limite venga superato, il server restituisce il codice http 416.

Request per minuto

E’ possibile effettuare 60 request al minuto. 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: [endpoint_url]/import
PAYLOAD:
{
     "overwriteDescriptors": false,
     "triggerIntegrations": false,
     "recalculateStats": false,
     "customers": [
         {
             "email": "1test@rfmcube.com",
             "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.

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: [endpoint_url]/merge_customer
PAYLOAD:
{
     "triggerIntegrations": false,
     "customer": {
         "id": "1",
         "email": "test@rfmcube.com",
         "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: [endpoint_url]/merge_order
PAYLOAD:
{
     "triggerIntegrations": false,
     "order": {
         "id": "1",
         "createdAt": "2020-01-01T13:30:39Z",
         "updatedAt": "2020-01-01T13:30:39Z",
         "amount": 85.85,
         "customerEmail": "1test@rfmcube.com",
         "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.

Impostando triggerIntegrations a true il contatto collegato all’ordine viene sincronizzato in tempo reale con i software terzi a cui il connector è integrato.

Informazioni sul processo di import

GET: [endpoint_url]/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

Potrebbero interessarti anche:

Tagged: Api

About the Author: Giacomo Baffa

I am a results-oriented full-stack web developer with over 10 years professional experience. I build web software solutions, taking a modular development approach to ensure an efficient, easily, maintainable and scalable product. More posts by Giacomo Baffa

Blog