---
agentTools:
  projectIndex: https://store360.readme.io/llms.txt
---

# Note preliminari per il formato JSON

## Benvenuti nella documentazione REST API di STORE360

Questa documentazione descrive le modalità di integrazione con le **REST API di STORE360**, fornendo indicazioni tecniche, regole di formato e best practice per lo scambio dei dati in formato JSON.

***

## Note preliminari sul formato JSON

### Campi obbligatori e opzionali

* Alcuni campi sono **obbligatori**, altri **opzionali**
* In fase di **importazione**:
  * Un campo presente con **valore nullo** (stringa vuota o numero uguale a `0`) **imposta esplicitamente** tale valore nel sistema
  * Un campo **omesso**:
    * in caso di **update**, **non viene aggiornato**
    * in caso di **insert**, viene impostato il **valore di default**
* In fase di **esportazione** da STORE360:
  * Se un campo ha valore nullo (stringa vuota o numero uguale a `0`), il relativo tag viene **comunque incluso** nella response

***

### Formato dei campi numerici (Prezzi)

* I campi di tipo **Prezzo** utilizzano il carattere `.` come **separatore decimale**
* Non è previsto il separatore delle migliaia

Esempio corretto:

```
1234.56
```

***

### Formato dei campi Data

* I campi di tipo **Data** sono espressi nel formato ISO:

```
YYYY-MM-DD HH:MM:SS
```

Esempio:

```
2020-02-28 15:21:15
```

***

## Codifica dei File

* I file JSON devono essere codificati in **UNICODE UTF-8**

***

## Caratteri Riservati

I seguenti caratteri sono riservati e devono essere opportunamente codificati:

| Carattere | Codifica |
| --------- | -------- |
| `&`       | `&`  |
| `<`       | `&lt;`   |
| `>`       | `&gt;`   |

### Esempio PHP

```php
$string = htmlspecialchars(
    "prova con caratteri riservati & < >",
    ENT_NOQUOTES,
    'Windows-1252'
);
```

***

## Simboli e Lettere Accentate

* La maggior parte dei file di testo creati su sistemi Windows utilizza la codifica **Windows-1252**
* Questa codifica differisce da **UTF-8** per i caratteri con codice ASCII > 127
* Esempi: `€ ò à ù é è ì`

### Conversione da Windows-1252 a UTF-8 (PHP)

```php
$string = mb_convert_encoding(
    "prova con caratteri €òàùéè",
    'UTF-8',
    'Windows-1252'
);
```

***

## Preparazione dei Dati per STORE360

Prima di inviare un file a STORE360, **ogni campo** deve essere codificato nel seguente modo:

```php
$string = mb_convert_encoding(
    htmlspecialchars($string, ENT_NOQUOTES, 'Windows-1252'),
    'UTF-8',
    'Windows-1252'
);
```

***

## Interpretazione dei Dati Ricevuti da STORE360

Per interpretare correttamente un file ricevuto da STORE360, è necessario eseguire l’operazione inversa:

```php
$string = html_entity_decode(
    mb_convert_encoding($string, 'Windows-1252', 'UTF-8'),
    ENT_NOQUOTES,
    'Windows-1252'
);
```