API Reference

Authentication

This section provides important information related to the authentication models that are currently enabled to access the Fabrick Platform APIs.

You should refer to the Direct Access authentication model if you are interested in accessing your own products/services (e.g., you are integrating into your ERP the access to your company cash account).

You should refer to the Personified Access authentication model if you are a system integrator and/or a technical third party that provides software on behalf of one or more customers.

Direct Access

The Direct Access authentication model is required whenever API calls are requested by the same subject that is the owner of the product/service on which operations should be executed.
For example, whenever a company develops a new software to access its own product/services, such as its cash accounts or its corporate credit cards, the Direct Access authentication model must be used.

In this scenario you will be required to manage a single security element:

API Key An application key, in the form of a base-64 alphanumeric string, like 4MSI5FGCXK5UVV2U487A08OZH4NHCHTKS.

APIs may be invoked directly since the authentication is implicitly provided by your APIKey and IP whitelist.
Each API request must be then issued by specifing the following common headers:

Content-Type: 'application/json'
Auth-Schema: 'S2S'
Api-Key: '{Your APIKey}'

Personified Access

This scenario requires the interaction of your system with the Fabrick Platform Authentication APIs before engaging any interaction with other APIs, in order to obtain an AuthToken that allows you to provide proof of authentication that you have been granted to the operation you are about to perform.

In this scenario you will be required to manage two security elements:

APIKey An application key, in the form of a 34-byte base-64 alphanumeric string, like 4MSI5FGCXK5UVV2U487A08OZH4NHCHTKS.
AuthToken A personification token, in the form of a 256-byte base-64 alphanumeric string, like 634a3b26dd4f...2cPWqcZVUfG01D2.

Each API request must be then issued by specifing the following common headers:

Content-Type: 'application/json'
Auth-Schema: 'S2S-AUTH'
Auth-Token: '{PersonificationToken}'

Please refer to the Affiliation section for more details.

Response Structure

This section provides important information about the common structure of each endpoint response that you will get by invoking Fabrick Platform APIs.

Please remember that in the technical documentation of each endpoint you will find only the specific information related to the structure of the response payload element; the general response structure is implicitly assumed as documented in this section.

The reference to the response structure distinguishes among the API version to document each version response structure: please be sure to refer to the correct version number.

API Version 5.x

{  
    "status": "OK",
    "errors": null,
    "warnings": null,
    "payload": {
        <resource-model>

        OR

        "list": [{<resource-model>}], // optional
        "pagination": { // optional with "list"
            "resultCount": <number>,
            "pageCount": <number>,
            "offset": <number>,
            "limit": <number>
        }
    }
}

The status field contains one of the following status codes:

OK If the response contains payload.
KO If the response contains one or more errors.

The errors array may contain info related to error handling (see below for details). The warnings array may contain info related to warning handling (see below for details).

The payload object typically contains the response data.

The payload.list array typically contains one or more result elements.

The payload.pagination object is optional and contains the following fields:

pageCount The total number of pages, assuming each page contains "limit" number of results.
resultCount The total number of results.
offset The positional index of the first element provided in the response.
limit The number of elements provided in the response.

{  
    "status": "KO",
    "errors": [
        {
            "code": "<string",
            "description": "<string>",
            "params": "<string>"
        }
    ],
    "warnings": [
        {
            "code": "<string",
            "description": "<string>",
            "params": "<string>"
        }
    ],
    "payload": null
}

Both the errors and warnings arrays contain one or more elements with the following structure.

The code field contains an error/warning unique code. The description field contains a textual description related to the error/warning. The params field is a string optionally containing the name of the input parameter affected by the reported error/warning.

API Version 4.x

{  
    "status": "OK",
    "errors": null,
    "payload": {
        <resource-model>

        OR

        "list": [{<resource-model>}], // optional
        "pagination": { // optional with "list"
            "resultCount": <number>,
            "pageCount": <number>,
            "offset": <number>,
            "limit": <number>
        }
    }
}

The status field contains one of the following status codes:

OK If the response contains payload.
KO If the response contains one or more errors.
PENDING If the response requires further interaction.

The errors array may contain info related to error handling (see below for details).

The payload object typically contains the response data.

The payload.list array typically contains one or more result elements.

The payload.pagination object is optional and contains the following fields:

pageCount The total number of pages, assuming each page contains "limit" number of results.
resultCount The total number of results.
offset The positional index of the first element provided in the response.
limit The number of elements provided in the response.

{  
    "status": "KO",
    "errors": [
        {
            "code": "<string",
            "description": "<string>",
            "params": "<string>"
        }
    ],
    "payload": null
}

The errors array contains one or more elements with the following structure.

The code field contains an error unique code. The description field contains a textual description related to the error. The params field is a string optionally containing the name of the input parameter affected by the reported error.

API Version 3.x

{  
    "status": "OK",
    "errors": null,
    "payload": {
        <resource-model>

        OR

        "list": [{<resource-model>}]
    }
}

The status field contains one of the following status codes:

OK If the response contains payload.
KO If the response contains one or more errors.
PENDING If the response requires further interaction.

The errors array may contain info related to error handling (see below for details).

The payload object typically contains the response data.

The payload.list array typically contains one or more result elements.

Pagination is not supported.

{  
    "status": "KO",
    "errors": [
        {
            "code": "<string",
            "description": "<string>",
            "params": ["<string>"]
        }
    ],
    "payload": null
}

The errors array contains one or more elements with the following structure.

The code field contains an error unique code. The description field contains a textual description related to the error. The params field is an array of strings eventually containing the name(s) of the input parameters affected by the reported errors.

API Version 2.x

{  
    "status": {
        "code": "OK",
        "description": ""
    },
    "errors": null,
    "payload": [<resource-model>, ...]
}

The status.code field contains one of the following status codes:

OK If the response contains payload.
KO If the response contains one or more errors.
PENDING If the response requires further interaction.

The status.description field contains a textual description of the response code.

The errors array may contain info related to error handling (see below for details).

The payload array typically contains the response data.

Lists and pagination are not supported.

{  
    "status": {
        "code": "KO",
        "description": ""
    },
    "errors": [
        {
            "code": "<string",
            "description": "<string>",
            "params": ["<string>"]
        }
    ],
    "payload": null
}

The errors array contains one or more elements with the following structure.

API Version 1.x

{  
    "status": {
        "code": "OK",
        "description": ""
    },
    "error": null,
    "payload": [<resource-model>, ...]
}

The status.code field contains one of the following status codes:

OK If the response contains payload.
KO If the response contains one or more errors.

The status.description field contains a textual description of the response code.

The errors object may contain info related to error handling (see below for details).

The payload array typically contains the response data.

Lists and pagination are not supported.

{  
    "status": {
        "code": "KO",
        "description": ""
    },
    "error": {
        "description": "<string>"
    },
    "payload": null
}

The error.description field contains a textual description of the error.

Pagination

Pagination is available for endpoints in v4.0+.

<HTTP VERB> <URI>?offset={offset}&limit={limit}&pagination={pagination}

If available, the request for pagination is managed through query parameters.

The offset parameter is the 0-based positional index of the first element to be provided in the response. A positive integer is expected; default value is 0. Additional information:

If offset >= resultCount the response is always empty (fetching over last available result).
If offset < 0 an HTTP-400 Bad Request error is returned (a positive integer is expected).

The limit parameter is the number of elements to be provided in the response. A positive integer is expected; default value is 20. Additional information:

If limit < 0 an HTTP-400 Bad Request error is returned (a positive integer is expected).

The pagination parameter is a boolean flag used to request the pagination element in the response. Default value is true.

{  
    ...  
    "pagination": {  
        "pageCount": 50,  
        "resultCount": 495,  
        "offset": 0,  
        "limit": 10  
    }  
}

The pageCount field contains the total number of pages, assuming each page contains limit number of elements.

The resultCount field contains the total number of result elements.

The offset field contains the positional index of the first element provided in the response.

The limit field contains the maximum number of elements to be expected in the response.

Data Types

The Fabrick Platform APIs assume the following data types and formats.

Data Type	Default Format	Example	Notes
String	-	`"A string"`	-
Number	`#.#`	`12.56`	-
Boolean	`true` - `false`	`true`	-
Object	`{...}`	`{"stringField": "A string"}`	-
Array	`[...]`	`["elem1", "elem2"]`	-
Date	`YYYY-MM-DD`	`2019-03-31`	Follows ISO 8601 standard, with `X-Time-Zone` header
Datetime	`YYYY-MM-DDThh:mm:ss.sssZ`	`2019-03-31T12:49:25.451Z`	Follows ISO 8601 standard
Timestamp	`[0-9]{13}`	`1550230023518`	Milliseconds since Unix epoch (Jan 1, 1970 00:00:00 UTC)
CountryCode	`[A-Z]{2}`	`IT`	Follows ISO 3166-1 alpha 2 standard
CurrencyCode	`[A-Z]{3}`	`EUR`	Follows ISO 4217 standard

Authentication​

Direct Access​

Personified Access​

Response Structure​

API Version 5.x​

API Version 4.x​

API Version 3.x​

API Version 2.x​

API Version 1.x​

Pagination​

Data Types​

Authentication

Direct Access

Personified Access

Response Structure

API Version 5.x

API Version 4.x

API Version 3.x

API Version 2.x

API Version 1.x

Pagination

Data Types