The intended audience of this article are Fabrick Platform producers. This article applies to the use case scenario in which Fabrick Platform is the unique touch point with the customer.
You may be alternatively looking for the use case scenario in which the customer subscribes contracts with both the producer and Fabrick Platform, that is addressed by the article "Sending new customer notifications".
Introduction
Whenever a new Fabrick Platform consumer (i.e., a subject that consumes APIs) subscribes to any of your services, Fabrick Platform will need to send you a proper notification to communicate the data related to the new customer. This is required since in this scenario Fabrick Platform is the unique point of contractualization with the customer.
We have a standard mechanism to smoothly handle this process.
Before delving into the technical aspects, let's overview the main steps required to expose your services as a Fabrick Platform API package:
- Agree beforehand, during the analysis of your services, the integration setup required to design the Fabrick Platform API package(s) that has to be exposed for you.
- The notification of the subscription of your package(s) by any of the Fabrick Platform consumers.
- The management of operational calls, that is, what happens whenever any single API call from the consumer is received and handled through Fabrick Platform.
The following paragraphs provide specific details related to point #2, i.e. the process through which Fabrick Platform provides to you the information related to the consumer that has newly subscribed your API package(s).
Notifying new consumers
As a platform, we are servicing multiple producers of services. In order to efficiently handle the data exchange with a multitude of counterparts, we have designed a simple standardized mechanism.
POST Notify New Customer
You have to expose a REST API that Fabrick Platform will call whenever a new consumer subscribes to any of your packages. The URL template is as follows:
https://<PRODUCER_BASEPATH>/customers/fabrick
The call will be handled as a http POST with the following request headers:
Content-Type: application/json
X-Api-Key: <FABRICK_MASTER_APIKEY>
This implies that the authentication model is as follows:
- Fabrick Platform identifies itself with
<FABRICK_MASTER_APIKEY>
(an APIKey that is issued by you for Fabrick Platform) - API calls are issued from a defined set of Fabrick Platform's IP addresses over https. Such IP addresses will be shared with you in the integration setup.
The request body is structured as follows:
{
"customerCode": "", // mandatory
"businessName" : "", // mandatory
"fiscalCode": "", // mandatory
"description": "",
"admin" : {
"name" : "",
"surname" : "",
"email" : ""
},
"reference": {
"name" : "",
"surname" : "",
"email" : ""
},
"billingInfo": {
"address": {
"street": "",
"city": "",
"postalCode": "",
"province: "",
"countryCode": ""
},
"email": "",
"certifiedEmail": "",
"phone": "",
"sdiCode": ""
}
}
Apart from the mandatory fields (i.e.: customerCode
, businessName
, and fiscalCode
), all the remaining fields are optional and can be agreed upon with Fabrick Platform in the integration setup.
Handling the incoming call from Fabrick Platform implies to properly register in your system the new customer and get ready to serve its API calls (i.e., step #3 of the process overview discussed above).
Once called and properly handled on your backend, Fabrick Platform will expect to receive the following response:
HTTP/1.x 200 OK
Content-Type: 'application/json'
{
"customerMetadata": [
{"key": "", "value": ""},
...
],
...
<DATA_FROM_INPUT_BODY>
}
The focal point here is the customerMetadata
element: this field contains a list of key-value couples that you should use to provide all the identification data that are required to correctly configure the new customer on Fabrick Platform. Please note that the list of elements that are passed must be agreed upon together with Fabrick Platform in the integration setup. An example of such element is the following:
{
"customerMetadata": [
{
"key": "customerId",
"value": "5e701d47-ad54-4462-a58e-7f793bbd4432"
}, {
"key": "client_secret",
"value": "E6zDOvfmZMhRoVS1nXjrid8kqm60SFmn"
}
],
...
}
In the example, two elements are provided back to Fabrick Platform: the customerId
and the client_secret
. Based on a previous agreed setup, Fabrick Platform will pair such data to the new customer, and provide the info while managing subsequent operational calls.
In brief
- In the integration setup, you agree with Fabrick Platform upon the following points:
- The set of IP addresses from which Fabrick Platform API calls will be issued
- The structure of the request body for POST Notify New Customer
- The
customerMetadata
list of key-value couples, and how such values should be used while handling operational calls from the customer
- You expose the POST Notify New Customer and wait for calls from Fabrick Platform
- You answer to POST Notify New Customer calls providing actual metadata for any new customer that will subscribe any of your services on Fabrick Platform.