Riferimento API

Autenticazione

Questa sezione fornisce informazioni importanti relative ai modelli di autenticazione attualmente abilitati per accedere alle API della Piattaforma Fabrick.

Fare riferimento al modello di autenticazione ad Accesso Diretto se si è interessati ad accedere ai propri prodotti/servizi (ad es., si sta integrando nel proprio ERP l'accesso al conto corrente aziendale).

Fare riferimento al modello di autenticazione ad Accesso Personificato se si è un system integrator e/o una terza parte tecnica che fornisce software per conto di uno o più clienti.

Accesso Diretto

Il modello di autenticazione ad Accesso Diretto è richiesto ogni volta che le chiamate API sono effettuate dallo stesso soggetto proprietario del prodotto/servizio su cui devono essere eseguite le operazioni.
Ad esempio, quando un'azienda sviluppa un nuovo software per accedere ai propri prodotti/servizi, come i conti correnti o le carte di credito aziendali, deve essere utilizzato il modello di autenticazione ad Accesso Diretto.

In questo scenario sarà necessario gestire un singolo elemento di sicurezza:

• API Key Una chiave applicativa, nella forma di una stringa alfanumerica in base 64, come 4MSI5FGCXK5UVV2U487A08OZH4NHCHTKS.

Le API possono essere invocate direttamente poiché l'autenticazione è implicitamente fornita dalla propria APIKey e dalla whitelist degli IP.
Ogni richiesta API deve quindi essere effettuata specificando i seguenti header comuni:

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

Accesso Personificato

Questo scenario richiede l'interazione del proprio sistema con le API di Autenticazione della Piattaforma Fabrick prima di avviare qualsiasi interazione con altre API, al fine di ottenere un AuthToken che consenta di fornire la prova di autenticazione necessaria per eseguire l'operazione desiderata.

In questo scenario sarà necessario gestire due elementi di sicurezza:

• APIKey Una chiave applicativa, nella forma di una stringa alfanumerica in base 64 di 34 byte, come 4MSI5FGCXK5UVV2U487A08OZH4NHCHTKS.
• AuthToken Un token di personificazione, nella forma di una stringa alfanumerica in base 64 di 256 byte, come 634a3b26dd4f...2cPWqcZVUfG01D2.

Ogni richiesta API deve quindi essere effettuata specificando i seguenti header comuni:

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

Per ulteriori dettagli, fare riferimento alla sezione Affiliazione.

Struttura della Risposta

Questa sezione fornisce informazioni importanti sulla struttura comune della risposta di ogni endpoint che si ottiene invocando le API della Piattaforma Fabrick.

Si ricorda che nella documentazione tecnica di ciascun endpoint si troverà solo le informazioni specifiche relative alla struttura dell'elemento payload della risposta; la struttura generale della risposta è implicitamente assunta come documentata in questa sezione.

Il riferimento alla struttura della risposta distingue in base alla versione delle API per documentare la struttura di risposta di ciascuna versione: assicurarsi di fare riferimento al numero di versione corretto.

API Versione 5.x

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

        OR

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

Il campo status contiene uno dei seguenti codici di stato:

• OK Se la risposta contiene payload.
• KO Se la risposta contiene uno o più errori.

L'array errors può contenere informazioni relative alla gestione degli errori (vedi sotto per i dettagli). L'array warnings può contenere informazioni relative alla gestione degli avvisi (vedi sotto per i dettagli).

L'oggetto payload contiene tipicamente i dati della risposta.

L'array payload.list contiene tipicamente uno o più elementi risultato.

L'oggetto payload.pagination è opzionale e contiene i seguenti campi:

• pageCount Il numero totale di pagine, assumendo che ogni pagina contenga un numero "limit" di risultati.
• resultCount Il numero totale di risultati.
• offset L'indice posizionale del primo elemento fornito nella risposta.
• limit Il numero di elementi forniti nella risposta.

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

Sia l'array errors che l'array warnings contengono uno o più elementi con la seguente struttura.

Il campo code contiene un codice univoco dell'errore/avviso. Il campo description contiene una descrizione testuale relativa all'errore/avviso. Il campo params è una stringa che contiene opzionalmente il nome del parametro di input interessato dall'errore/avviso segnalato.

API Versione 4.x

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

        OR

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

Il campo status contiene uno dei seguenti codici di stato:

• OK Se la risposta contiene payload.
• KO Se la risposta contiene uno o più errori.
• PENDING Se la risposta richiede ulteriore interazione.

L'array errors può contenere informazioni relative alla gestione degli errori (vedi sotto per i dettagli).

L'oggetto payload contiene tipicamente i dati della risposta.

L'array payload.list contiene tipicamente uno o più elementi risultato.

L'oggetto payload.pagination è opzionale e contiene i seguenti campi:

• pageCount Il numero totale di pagine, assumendo che ogni pagina contenga un numero "limit" di risultati.
• resultCount Il numero totale di risultati.
• offset L'indice posizionale del primo elemento fornito nella risposta.
• limit Il numero di elementi forniti nella risposta.

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

L'array errors contiene uno o più elementi con la seguente struttura.

Il campo code contiene un codice univoco dell'errore. Il campo description contiene una descrizione testuale relativa all'errore. Il campo params è una stringa che contiene opzionalmente il nome del parametro di input interessato dall'errore segnalato.

API Versione 3.x

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

        OR

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

Il campo status contiene uno dei seguenti codici di stato:

• OK Se la risposta contiene payload.
• KO Se la risposta contiene uno o più errori.
• PENDING Se la risposta richiede ulteriore interazione.

L'array errors può contenere informazioni relative alla gestione degli errori (vedi sotto per i dettagli).

L'oggetto payload contiene tipicamente i dati della risposta.

L'array payload.list contiene tipicamente uno o più elementi risultato.

La paginazione non è supportata.

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

L'array errors contiene uno o più elementi con la seguente struttura.

Il campo code contiene un codice univoco dell'errore. Il campo description contiene una descrizione testuale relativa all'errore. Il campo params è un array di stringhe che può contenere il nome o i nomi dei parametri di input interessati dagli errori segnalati.

API Versione 2.x

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

Il campo status.code contiene uno dei seguenti codici di stato:

• OK Se la risposta contiene payload.
• KO Se la risposta contiene uno o più errori.
• PENDING Se la risposta richiede ulteriore interazione.

Il campo status.description contiene una descrizione testuale del codice di risposta.

L'array errors può contenere informazioni relative alla gestione degli errori (vedi sotto per i dettagli).

L'array payload contiene tipicamente i dati della risposta.

Liste e paginazione non sono supportate.

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

L'array errors contiene uno o più elementi con la seguente struttura.

Il campo code contiene un codice univoco dell'errore. Il campo description contiene una descrizione testuale relativa all'errore. Il campo params è un array di stringhe che può contenere il nome o i nomi dei parametri di input interessati dagli errori segnalati.

API Versione 1.x

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

Il campo status.code contiene uno dei seguenti codici di stato:

• OK Se la risposta contiene payload.
• KO Se la risposta contiene uno o più errori.

Il campo status.description contiene una descrizione testuale del codice di risposta.

L'oggetto errors può contenere informazioni relative alla gestione degli errori (vedi sotto per i dettagli).

L'array payload contiene tipicamente i dati della risposta.

Liste e paginazione non sono supportate.

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

Il campo error.description contiene una descrizione testuale dell'errore.

Paginazione

La paginazione è disponibile per gli endpoint dalla versione 4.0 in poi.

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

Se disponibile, la richiesta di paginazione viene gestita tramite parametri query.

Il parametro offset è l'indice posizionale a base 0 del primo elemento da fornire nella risposta. È atteso un numero intero positivo; il valore predefinito è 0. Informazioni aggiuntive:

• Se offset >= resultCount la risposta è sempre vuota (si sta richiedendo oltre l'ultimo risultato disponibile).
• Se offset < 0 viene restituito un errore HTTP-400 Bad Request (è atteso un numero intero positivo).

Il parametro limit è il numero di elementi da fornire nella risposta. È atteso un numero intero positivo; il valore predefinito è 20. Informazioni aggiuntive:

• Se limit < 0 viene restituito un errore HTTP-400 Bad Request (è atteso un numero intero positivo).

Il parametro pagination è un flag booleano utilizzato per richiedere l'elemento pagination nella risposta. Il valore predefinito è true.

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

Il campo pageCount contiene il numero totale di pagine, assumendo che ogni pagina contenga limit elementi.

Il campo resultCount contiene il numero totale di elementi risultato.

Il campo offset contiene l'indice posizionale del primo elemento fornito nella risposta.

Il campo limit contiene il numero massimo di elementi attesi nella risposta.

Tipi di Dati

Le API della Piattaforma Fabrick adottano i seguenti tipi di dati e formati.

Tipo di Dato	Formato Predefinito	Esempio	Note
String	-	"Una stringa"	-
Number	#.#	12.56	-
Boolean	true - false	true	-
Object	{...}	{"stringField": "Una stringa"}	-
Array	[...]	["elem1", "elem2"]	-
Date	YYYY-MM-DD	2019-03-31	Segue lo standard ISO 8601, con header X-Time-Zone
Datetime	YYYY-MM-DDThh:mm:ss.sssZ	2019-03-31T12:49:25.451Z	Segue lo standard ISO 8601
Timestamp	[0-9]{13}	1550230023518	Millisecondi dall'epoca Unix (1 Gen 1970 00:00:00 UTC)
CountryCode	[A-Z]{2}	IT	Segue lo standard ISO 3166-1 alpha 2
CurrencyCode	[A-Z]{3}	EUR	Segue lo standard ISO 4217