---
title: "Riferimento API"
description: "Questa sezione fornisce informazioni importanti relative ai modelli di autenticazione attualmente abilitati per accedere alle API della Piattaforma Fabrick."
url: "https://docs.fabrick.com/fabrick-platform/introduction/fabrick-platform-api-reference/"
language: "it"
---

# 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:

```html
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:

```html
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

```json
{  
    "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.

```json
{  
    "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

```json
{  
    "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.

```json
{  
    "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

```json
{  
    "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.

```json
{  
    "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

```json
{  
    "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.

```json
{  
    "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

```json
{  
    "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.

```json
{  
    "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
<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`.

```json
{  
    ...  
    "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                             |