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 che dovrete copiare nell’interfaccia di creazione del connector.
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 |
| 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"
}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://rfmcube.com/campi-extra-e-filtri-rfmcube/
Potrebbero interessarti anche:
