Invio ordini

Con POST /orders il tuo gestionale invia gli ordini alla piattaforma senza file CSV. Gli ordini compaiono nel pannello in Importa ordini → Ordini da API, come se fossero stati importati da un file, e da lì si spediscono come gli altri.

Usa questo endpoint quando vuoi che la spedizione sia creata da un operatore dal pannello. Se invece il tuo software deve ottenere subito l’etichetta, usa POST /shipments.

Richiesta


{
  "saveToAddressBook": false,
  "orders": [
    {
      "orderNumber": "ERP-1002",
      "orderDate": "2026-09-20",
      "recipient": {
        "name": "Giulia Russo",
        "address": { "street": "Via Appia 10", "city": "Roma", "province": "RM", "postalCode": "00183", "countryCode": "IT" },
        "phone": "+39 333 1234567",
        "email": "giulia@example.com",
        "reference": "CLI-77"
      },
      "senderReference": "MAG-A",
      "parcels": 1,
      "weight": { "value": 1.2, "units": "KG" },
      "cod": { "amount": 49.90 },
      "total": 49.90,
      "contentDescription": "Abbigliamento",
      "notes": "Citofonare Russo",
      "items": [
        { "sku": "TS-001", "quantity": 2, "unitPrice": 19.95 },
        { "sku": "BAG-9", "quantity": 1, "name": "Tote bag" }
      ]
    }
  ]
}

Campi

Campo	Obbligatorio	Valore predefinito
`recipient.name`	Sì
`recipient.address.street`, `city`, `postalCode`	Sì
`recipient.address.countryCode`	No	`IT`
`recipient.address.province`	No	Sigla o nome per esteso
`orderNumber`	No, ma consigliato	Numero dell’ordine nel tuo gestionale
`orderDate`	No	Data odierna
`parcels`	No	1 collo (massimo 50)
`weight`	No	1 kg
`senderReference`	No	Ragione sociale del cliente
`cod`, `insurance`, `total`	No	Contrassegno, assicurazione, totale dell’ordine
`items[]`	No	Fino a 200 righe, ognuna con `sku` e `quantity`
`saveToAddressBook`	No	`false`; con `true` i destinatari vengono salvati in rubrica

Dettagli utili:

Un CAP italiano inviato senza zeri iniziali (185) viene completato.
Una riga senza name prende il titolo del prodotto con lo stesso SKU nel catalogo.

Regole del lotto

Una chiamata contiene da 1 a 100 ordini.
Il lotto è validato per intero: un solo ordine non valido respinge tutta la chiamata con 422. Le chiavi di details indicano quale ordine e quale campo, ad esempio orders.1.recipient.address.postalCode (gli ordini sono numerati da 0).
Due ordini con lo stesso orderNumber nella stessa chiamata sono un errore.

orderNumber rende la chiamata ripetibile: un numero già inviato non crea un secondo ordine, ma viene elencato in skipped. Se una chiamata fallisce per un problema di rete puoi rinviare lo stesso lotto senza creare doppioni.

Risposta

201 se almeno un ordine è stato creato, 200 se erano tutti già presenti:


{
  "created": [
    { "id": 5120, "orderNumber": "ERP-1002", "itemsCount": 3, "shipped": false }
  ],
  "skipped": [
    { "index": 1, "orderNumber": "ERP-1001", "id": 5087 }
  ]
}

Campo	Significato
`created[]`	Gli ordini creati, con l’`id` assegnato dalla piattaforma
`skipped[].index`	Posizione dell’ordine nell’array `orders` della richiesta
`skipped[].id`	`id` dell’ordine già presente

Nel pannello

Gli ordini inviati hanno origine API. In Importa ordini → Ordini da API li selezioni, scegli il contratto (o l’assegnazione automatica al prezzo minore) e crei le spedizioni, come per gli ordini importati da file.