Inserimento ordini

Inserisce uno o più ordini in Store360, oppure aggiorna o annulla ordini già inviati.

Metodo HTTP

POST

Endpoint

https://MIOSERVER/store360_api/orders

Header Richiesti

Content-Type: application/json
Authorization: Bearer {access_token}

Il body è solo JSON.

JSON di Richiesta

{
  "Ordini": [
    {
      "Provenienza": "MOBILE",
      "external_orderid": "APP-10045",
      "DataOrdine": "2026-11-11 15:30:00",
      "Stato": "PAGATO",
      "Cliente": "Mario Rossi",
      "Email": "[email protected]",
      "Telefono": "3331234567",
      "Indirizzo": "Via Roma 1",
      "Citta": "Genova",
      "Cap": "16100",
      "Provincia": "GE",
      "Nazione_ISO2": "IT",
      "IndirizzoSpedizione": "Via Milano 5",
      "CittaSpedizione": "Genova",
      "CapSpedizione": "16121",
      "ProvinciaSpedizione": "GE",
      "MetodoPagamento": "Carta di credito",
      "MetodoSpedizione": "Corriere espresso",
      "CostoSpedizione": 5.00,
      "Note": "Consegnare dopo le 15",
      "Prodotti": [
        { "Codice": "SKU123", "Qta": 2, "Prezzo": 9.90 },
        { "Codice": "SKU456", "Qta": 1, "Prezzo": 15.50 }
      ]
    }
  ]
}

Esempio minimo (solo i campi obbligatori)

{ "Ordini": [ { "Provenienza": "MOBILE", "external_orderid": "APP-10046", "Cliente": "Laura Bianchi",
                "Prodotti": [ { "Codice": "SKU123", "Qta": 1, "Prezzo": 9.90 } ] } ] }

Campi dell'oggetto Ordine

Campo	Tipo	Obbligatorio	Descrizione
Provenienza	string	sì	Tipo d'ordine, come il campo `Provenienza` del GET /orders (maiuscole e minuscole indifferenti). Deve essere un tipo d'ordine attivo della vostra installazione
external_orderid	string	sì	Id dell'ordine nel vostro sistema (massimo 64 caratteri). Serve a riconoscere un ordine già inviato
Cliente	string	sì	Nome e cognome, o ragione sociale
Prodotti	array	sì	Almeno una riga (vedi sotto)
DataOrdine	string	no	Formato `AAAA-MM-GG HH:MM:SS`. Se manca, la data della chiamata
Stato	string	no	`NUOVO` (predefinito), `PAGATO`, `SPEDITO`, `PAGATOESPEDITO`, `ANNULLATO` (solo su un ordine già inviato)
Email	string	no	Se presente il cliente viene cercato per email e creato se non esiste
Telefono	string	no
Azienda, PartitaIva, CodiceFiscale	string	no	Dati di fatturazione
Indirizzo, Citta, Cap, Provincia	string	no	Indirizzo del cliente
Nazione_ISO2	string	no	Codice ISO a 2 lettere, predefinito `IT`
ClienteSpedizione, AziendaSpedizione, IndirizzoSpedizione, CittaSpedizione, CapSpedizione, ProvinciaSpedizione, NazioneSpedizione_ISO2	string	no	Indirizzo di spedizione. I campi non indicati prendono il valore di quelli del cliente
MetodoPagamento	string	no	Predefinito: la Provenienza
MetodoSpedizione	string	no
CostoSpedizione	number	no	IVA inclusa, predefinito 0
Valuta	string	no	Codice a 3 lettere, predefinito `EUR`
Note	string	no	Salvate nello storico dell'ordine

Campi della riga Prodotti

Campo	Tipo	Obbligatorio	Descrizione
Codice	string	sì	Codice (SKU) del prodotto in Store360. Se non esiste, la riga viene inserita lo stesso senza prodotto collegato e senza movimenti di magazzino; la risposta lo segnala in `Messaggio`
Qta	integer	sì	Numero intero maggiore di zero
Prezzo	number	sì	Prezzo unitario IVA inclusa
Nome	string	no	Se manca, il nome del prodotto in Store360 (o il Codice, se il prodotto non esiste)
Iva	number	no	Aliquota in percentuale (es. 22), usata solo se il Codice non esiste in Store360; se manca si usa l'aliquota ordinaria. Per i prodotti esistenti vale l'aliquota del prodotto

Comportamento

Ogni ordine viene elaborato in modo indipendente: un ordine non valido viene scartato e segnalato nella risposta, senza bloccare gli altri.
Subtotale, IVA e totale vengono calcolati dalle righe più il costo di spedizione.
Ordine già inviato (stesso external_orderid e stessa Provenienza): non viene inserito di nuovo, quindi una chiamata ripetuta (per esempio dopo un timeout) non crea doppioni. Invece:
- lo Stato viene aggiornato solo se avanza (NUOVO → PAGATO → SPEDITO → PAGATOESPEDITO), mai all'indietro; Note viene aggiunta allo storico;
- dati del cliente e indirizzi vengono aggiornati solo per i campi inviati e solo finché l'ordine non è spedito;
- righe e totali non vengono modificati.
Annullamento: inviare l'ordine con "Stato": "ANNULLATO". L'ordine viene annullato e non compare più nel GET /orders. Non si può inviare un ordine nuovo già annullato, e un ordine annullato non viene più modificato.

{ "Ordini": [ { "Provenienza": "MOBILE", "external_orderid": "APP-10046", "Cliente": "Laura Bianchi",
                "Stato": "ANNULLATO", "Note": "Annullato dal cliente",
                "Prodotti": [ { "Codice": "SKU123", "Qta": 1, "Prezzo": 9.90 } ] } ] }

JSON di Risposta

{
  "ResponseTo": "Orders",
  "Timestamp": "1794410919",
  "Ack": "OK",
  "MessaggioErrore": "",
  "CodiceErrore": "0",
  "Output": {
    "TotaleOrdini": "2",
    "Inseriti": "1",
    "Aggiornati": "0",
    "Annullati": "0",
    "Esistenti": "0",
    "Scartati": "1",
    "Ordini": {
      "Ordine": [
        { "Posizione": "1", "external_orderid": "APP-10045", "Esito": "INSERITO", "OrdineId": "6061", "Messaggio": "Ordine inserito" },
        { "Posizione": "2", "external_orderid": "APP-10046", "Esito": "SCARTATO", "OrdineId": "", "Messaggio": "Riga 1 (SKU123): Prezzo obbligatorio" }
      ]
    }
  }
}

Esito	Significato
INSERITO	Ordine creato; `OrdineId` è l'id in Store360
AGGIORNATO	Ordine già presente: aggiornati stato e/o dati del cliente
ANNULLATO	Ordine già presente, annullato
ESISTENTE	Ordine già presente, nessuna modifica (il motivo è in `Messaggio`)
SCARTATO	Ordine non valido, nessun dato salvato (il motivo è in `Messaggio`)

Se tutti gli ordini sono scartati Ack è KO con CodiceErrore 700. Con un solo ordine Ordine è un oggetto, con più ordini una lista.