How to create an Rfmcube webservice compliant
This guide will help you to create a webservice compliant with Rfmcube specs, which will allow you to synchronize data from your custom platform.
Requests
The requests will be POST, made to an HTTPS endpoint and the data format will be JSON.
Each request includes headers Content-Type: application/json, Accept: application/json and api-key which will be filled with an alphanumeric key created by you and which you will set on Rfmcube frontend when you create your connector.
Format and fields of data exchanged
The data exchanged will essentially be customers and orders. The fields and their format that RFMCube accepts are described below;
Customer
| Field | Description |
| Mandatory: the customer's email. It's the primary key. | |
| id | Optional: it represents a unique id for the customer. Usually the database id is used. It is not mandatory because the primary key is represented by the email field. |
| createdAt | Mandatory: it's the creation date of the customer. The date is represented in the format ISO-8601 in UTC. Example: 2011-12-03T10:15:30Z |
| updatedAt | Mandatory: the date of the last modification of the customer. The date is represented in the format ISO-8601 in UTC. Example: 2011-12-03T10:15:30Z |
Example in JSON:
{
"email" : "[email protected]"
"id" : "1",
"createdAt" : "2019-01-19T13:06:39Z",
"updatedAt" : "2019-01-22T12:16:19Z"
}Order
| Field | Description |
| id | Mandatory: it represents a unique id for the order. Usually the database id is used. |
| orderReference | Optional: Orders are often associated with a unique identifier other than the id. If you have one you can submit it, otherwise the id field will be used |
| status | Mandatory: it represents the order status according to your status management logic. Subsequently, an order mapping procedure allows the association of the states according to the Rfmcube logic. |
| statusLabel | Optional: a label associated with the order status. It can be useful in cases where you manage states with numerical ids, which are difficult to read. |
| createdAt | Mandatory: the order creation date. The date is represented in the ISO-8601 format in UTC. Example: 2011-12-03T10:15:30Z |
| updatedAt | Mandatory: the date of the last update of the order. The date is represented in the ISO-8601 format in UTC. Example: 2011-12-03T10:15:30Z |
| amount | Mandatory: it represents the total of the order, expressed with two decimals, with the point as separator between integers and decimals and without the currency symbol. Example: 1099.99 |
| customerId | Optional: the unique id of a customer. It is optional because in some cases customers can place orders without being registered so this id doesn''t exists. In fact, the field that discriminates against customers is the email field. |
| customerEmail | Mandatory: the email of the customer who placed the order. This is the field that actually serves as the primary key to the customer entity. |
Example in JSON:
{
"id" : "1",
"orderReference" : "M000001",
"status" : "7",
"statusLabel" : "Completed",
"createdAt" : "2019-01-19T13:06:39Z",
"updatedAt" : "2019-01-19T20:03:39Z",
"amount" : "55.00",
"customerId" : "1",
"customerEmail" : "[email protected]"
}Web service interface
The calls made by RFMCube are listed below:
Customer by id
POST: /customer
PAYLOAD:
{
"id" : "342"
}
Description: returns the customer for the id specified in the payload.
First created customer
POST: /first_customer
Description: returns the first customer created. It is used to know the date from which to start looking for customers in the first synchronization phase.
List of customers with creation date in the date range
POST: /customers_by_creation
PAYLOAD:
{
"from" : "2019-01-01T00:00:00Z",
"to" : "2019-01-02T00:00:00Z"
}
Description: returns an array of customers whose creation date is between the two dates specified in the payload.
List of customers with date of last modification in the range
POST: /customers_by_update
PAYLOAD:
{
"from" : "2019-01-01T00:00:00Z",
"to" : "2019-01-02T00:00:00Z"
}
Description: returns an array of customers whose last modification date is between the two dates specified in the payload.
Orders by id
POST: /order
PAYLOAD:
{
"id" : "342"
}
Description: returns the order for the id specified in the payload.
First order created
POST: /first_order
Description: returns the first order created. It is used to know the date from which to start to search for orders in the initial synchronization phase.
List of orders with creation date in range
POST: /orders_by_creation
PAYLOAD:
{
"from" : "2019-01-01T00:00:00Z",
"to" : "2019-01-02T00:00:00Z"
}
Description: returns an array of orders for which the creation date is between the two dates specified in the payload.
List of orders with last modification date in the range
POST: /orders_by_update
PAYLOAD:
{
"from" : "2019-01-01T00:00:00Z",
"to" : "2019-01-02T00:00:00Z"
}
Description: returns an array of orders for which the last modification date is between the two dates specified in the payload.
Lista of orders by id
POST: /orders_by_id
PAYLOAD:
{
"ids" : [ "45", "32", "34" ]
}
Description: returns an array of orders associated with the ids specified in the payload. It is used to request orders that are in transitory states, for which Rfmcube checks the change again.