The intended audience of this article are Fabrick Platform producers. This article applies to the use case scenario in which the customer subscribes contracts with both the producer and Fabrick Platform.

You may be alternatively looking for the use case scenario in which Fabrick Platform is the unique touch point with the customer, that is addressed by the article "Receiving new customer notifications".

Introduction

Whenever a new Fabrick Platform consumer (i.e., a subject that consumes APIs) subscribes to any of your services, a proper exchange of data must be ensured between you and the platform, in order to align both systems to get ready to serve the new customer.

Before delving into the technical aspects, let's overview the main steps required to expose your services as a Fabrick Platform API package:

1. The integration setup, to be agreed once during the analysis of your services required to design the Fabrick Platform API package(s) that has to be exposed for you.
2. The data exchange to enable the service usage to new Fabrick Platform consumers.
3. The management of operational calls, that 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 you can exchange data with Fabrick Platform for new consumers.

Notifying new consumers

Generally, such process could be initiated by either Fabrick Platform or you, depending on the specific case. 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

Whenever a new consumer subscribes to any of your packages, you have to call a REST API that Fabrick Platform exposes. The URL is as follows:

https://api.fabrick.com/api/fabrick/platform/v4.0/{producerId}/customers

The authentication model requires that:

• You identify yourself with <PRODUCER_APIKEY> (an APIKey that is issued by Fabrick Platform for you)
• You issue API calls over https from a defined set of IP addresses (that you can configure on your Fabrick Platform reserved area).

Fabrick Platform expects a http POST call with the following request headers:

Content-Type: application/json
Auth-Schema: S2S
Api-Key: <PRODUCER_APIKEY>

The request body is structured as follows:

{
    "customerMetadata": [ // mandatory
        {"key": "", "value": ""},
        ...
    ],
    "businessName" : "", // mandatory
    "fiscalCode": "", // mandatory
    "description": "",
    "admin" : {
        "name" : "",
        "surname" : "",
        "email" : "" 
    },
    "reference": {
         "name" : "",
         "surname" : "",
         "email" : ""
     },
    "billingInfo": {
         "address": {
             "street": "",
             "city": "",
             "postalCode": "",
             "province: "",
             "countryCode": ""
         },
         "email": "",
         "certifiedEmail": "",
         "phone": "",
         "sdiCode": ""
     }
}

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"
        }
     ],
     ...
}

Apart from the mandatory fields (i.e.: businessName, and fiscalCode), all the remaining fields are optional and can be agreed upon with Fabrick Platform in the integration setup. 

Fabrick Platform will provide the following response:

HTTP/1.x 201 Created

Content-Type: 'application/json'

(no body)

In brief

1. In the integration setup, you agree with Fabrick Platform upon the following points:
   • 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.
2. You must call the POST Notify New Customer.