DISCLAMER:
Why is this not the recommended method?
Integration via API compared to the creation of a compliant webservice may seem simpler and more immediate to implement but it has many disadvantages and a series of technical problems which are not perceptible at first glance but which make it less reliable:
- complex and error-prone logic such as paging, resending in case of network problems, updating the entity data structure must be reinvented;
- if there are unexpected problems on the part of the e-commerce in sending the data, the import procedure will have to be redone to be sure of the consistency of the data;
- in the medium-long term it requires more hours of development on the part of the programmer who implements it, because for example if you want to add a field to make filters, the data import procedure will have to be carried out manually from scratch;
The webservice compliant mode has a whole series of advantages that make it preferable:
- it is designed both for very small e-commerce and for e-commerce with large amounts of data;
- the requests we make request orders and customers in very narrow ranges so as not to overload both servers;
- it is possible to decide when the requests are made (usually at night), create viewports within which it is possible to make them and manage any failed attempts completely automatically;
- if there is a need to add a field to create filters, just expose it in the webservice and Rfmcube will automatically sync the entire history without the need for technical interventions;
- it is possible to interrupt the sync at any time and then reactivate it later, Rfmcube will take care of taking the necessary data while maintaining the consistency of the data;
We followed many custom integrations and in the end the webservice complaint mode always proved to be the most effective and least prone to bugs. Furthermore, we are able to provide dedicated technical support. In the case of integrations with APIs there is no technical support because we become a subject who passively receives the data and we do not have direct control over what happens.
When to use APIs
If your e-commerce platform does not have APIs to call to collect data on customers and orders, Rfmcube provides its own API through which to send your data.
To use the Rfmcube API you must have an account and a connector created by selecting Use the Rfmcube API as the platform type. If the platform is incorrect the server returns the http code 406.
The API is accessible by creating HTTPS requests at the following endpoint:
https://api.rfmcube.com/v1The requests
Requests must be sent over HTTPS and the payload content must be JSON (application/json). Each request must include the headers content-type: application/json and api-key which will be populated with the API key of your connector.
The API key is automatically generated and can be found in your connector settings.
Limitations
Request size
The maximum size of a request is 200MB. If this limit is exceeded, the server returns the http code 416.
Request per minute
It is possible to make 60 requests per minute. Once this limit is exceeded, the server returns the http code 429.
First steps
To immediately start synchronizing with RFMcube it is necessary to send the data relating to the two fundamental entities that make up the RFM analysis, customers and orders.
The duty of integrating the data in a coherent manner is entirely up to the developer, implementing all the measures necessary to guarantee the consistency of the data, even in the event of errors. A procedure must therefore be developed that performs the initial synchronization of the data and then subsequently sends modified or newly created Customers and Orders.
If you have any doubts, don’t hesitate to contact us!
Import Customers and Orders#
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"
}
]
}
]
}
]
}
Description: The import process is not synchronous and can take a long time. This call immediately returns a processId that can be used to query information about the current operation.
The overwriteDescriptors field determines whether to overwrite the metafield structure previously created on the connector. If this value is set to true there must be at least one order in the call.
By setting triggerIntegrations to true, synchronizations with third-party software with which the connector is integrated are started.
Setting recalculateStats to true recalculates the connector statistics.
The fields in bold are mandatory and essential for Rfmcube. All other fields can be defined as desired. Rfmcube will take care of creating the appropriate descriptors.
The customer id field is not obligatory, in case it is a guest user with only the email filled in, Rfmcube will manage it as such.
The status and statusLabel fields are not mandatory, if they are not passed they will all be treated the same. In any case, the order mapping must be created in the connector configuration.
Customer update#
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"
}
}
Description: Adds a new customer or updates an existing customer. This call only updates the Customer’s data and does not modify the orders associated with it.
By setting triggerIntegrations to true, the contact is synchronized in real time with the third-party software to which the connector is integrated.
Order update#
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"
}
]
}
}
Description: Adds a new order or updates an existing order.
The status and statusLabel fields are not mandatory, if they are not passed they will all be treated the same. In any case, the order mapping must be created in the connector configuration.
By setting triggerIntegrations to true, the contact linked to the order is synchronized in real time with the third-party software to which the connector is integrated.
Delete customer#
POST: [endpoint_url]/delete_customer
PAYLOAD:
{
"id": "321",
"email": "test@example.com"
}
Description: Completely delete the customer and all of their associated orders. You can pass just the id, just the email or both. If both have passed, it is searched first by id and then by email.
Note: if you are deleting the customer for reasons related to their consent to profiling, you may decide to pass on the anonymized customer data, in this way the global statistics will not change.
Import process info#
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
}
}
Description: Request information about a process created with contact import.
Alternative solutions
Alternatively, it is possible to create a web service according to our specifications to which RFMCube makes calls.
This solution may seem more laborious but in reality it is much simpler to implement and leaves Rfmcube with the burden of guaranteeing consistency between the data present in the two platforms.
Your API will have to receive requests from Rfmcube, make database queries according to the passed filters and return the result in JSON format.
For further information, read the article: How to create an Rfmcube webservice compliant
