Punto finale degli ordini (Orders)

Nota: l'importazione e l'eliminazione delle voci della cronologia richiedono orders:write. L'API non elimina l'ordine stesso: DELETE /Delete/JSON/orders restituisce HTTP 501 NOT_IMPLEMENTED. La registrazione in magazzino avviene automaticamente al momento della creazione. Solo DELETE /Delete/JSON/order_status_history/{id} elimina una voce della cronologia: lo stato dell’ordine viene aggiornato di conseguenza; il negozio rifiuta la voce più vecchia di un ordine (HTTP 409 FIRST_HISTORY_ENTRY). Dettagli: API di eliminazione.

Crea o aggiorna un ordine. POST = Create, PUT con orders_id = Update. Tutti i campi vengono verificati e salvati dallo stesso servizio utilizzato anche per la creazione degli ordini nelle importazioni dal marketplace.

Payload minimo (Create)

{
  "data": [{
    "customers_id": 51,
    "payment_method": "PayPal",
    "products": [
      {"products_id": 42, "quantity": 2, "products_price": "29.99"}
    ]
  }]
}

Payload completo con tutte le opzioni

{
  "data": [{
    "customers_id": 51,
    "language_id": 2,
    "payment_method": "Stripe",
    "shipping_method": "DHL",
    "tax_flag": 1,
    "totals_mode": "auto",
    "expected_total": "59.98",
    "strict_totals": true,
    "currency": "EUR",
    "products": [
      {
        "products_id": 42,
        "quantity": 2,
        "products_price": "29.99",
        "products_tax": "19.00",
        "attributes": [
          {"option_id": 1, "value_id": 5}
        ]
      }
    ],
    "external_reference": {
      "source": "amazon",
      "external_id": "AMZ-12345"
    },
    "tracking": [
      {"service_provider": "DHL", "code": "1234567890", "link": "https://nolp.dhl.de/?piececode=1234567890"}
    ]
  }]
}

L’impostazione « totals_mode » determina le modalità di calcolo dei totali degli ordini:

Se tax_flag non è impostato esplicitamente, viene ricavato dal gruppo clienti:

• customers_groups.show_tax = 1 + DISPLAY_PRICE_WITH_TAX = true → tax_flag = 1 (lordo)
• customers_groups.show_tax = 0 → tax_flag = 0 (netto)
• Gruppi esenti da imposta (ad es. partita IVA UE) → tax_flag = 2 (esente da imposta)

Interpretazione di products_price a seconda tax_flag

⚠️ Importante per le importazioni dal marketplace: se il marketplace invia prezzi netti, è NECESSARIO impostare esplicitamen tax_flag: 0; in caso contrario, i prezzi (per un gruppo di clienti lordi) verranno interpretati come lordi.

A partire dalla v2.122.8, le voci con importo fiscale negativo, come ad esempio i rimborsi, ricevono la riga fiscale come nel checkout. Quando si aggiungono voci tramite PUT, l’imposta delle voci negative viene conteggiata. Le nuove voci memorizzano al momento della creazione se si tratta di merce o di un servizio; i documenti relativi a forniture e prestazioni intracomunitarie rimangono così invariati.

Origine del prezzo

Il fatto che un importo venga letto al netto o al lordo dipende da chi lo ha determinato: l’integrazione (payload) o lo shop (database, modulo di spedizione).

A partire dalla v2.122.8 ogni voce appena creata (POST e PUT con products_mode: "append") memorizza se si tratta di merce (0) o di un servizio (1). Il valore determina, sulla fattura e sulla fattura elettronica, l’indicazione fiscale per le forniture o i servizi intracomunitari e l’esclusione del diritto di recesso.

In assenza di questo campo, il negozio online determina il valore in base al prodotto, così come il carrello e l’editor degli ordini:

Novità nella v2.122.11 Con questo campo, il valore inviato prevale anche sui dati del prodotto, ad esempio per una voce di servizio libera:

curl -X POST "https://shop.de/xpanel/xoport/Import/JSON/orders" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"orders","data":[{"customers_id":123,"products":[
       {"products_name":"Programmierung Schnittstelle","products_quantity":3,
        "products_price":150.00,"products_tax":0,"service":1}]}]}'

• Sono consentiti 1, 0, true, false, "1" e "0". Qualsiasi altro valore non viene accettato: la risposta segnala service_invalid in records[].warnings, e il valore proviene dal prodotto.
• Solo al momento della creazione. Le voci esistenti mantengono il loro valore: products_mode: "update" rifiuta service, il record fallisce con FIELD_NOT_UPDATABLE e non viene scritto nulla, nemmeno nei campi rimanenti (risposta HTTP 200 come in ogni importazione collettiva). Per correggere, annullare la voce e aggiungerla nuovamente con service.
• I negozi fino alla versione 4.9.170 non riconoscono questo campo: viene ignorato come UNKNOWN_FIELD (con ?_strict=true e codice di stato HTTP 400), e una voce di servizio libera viene interpretata come merce. Per verificare se un negozio riconosce il campo, consultare api_version in GET /me.
• L’esportazione fornisce il valore per ciascuna voce in products[].service: 0, 1 o null per gli ordini più vecchi senza valore memorizzato.

Se language_id non è presente nel payload, viene risolto in cascata:

1. Valore del payload (se impostato)
2. customers.language_id dalla scheda cliente
3. DEFAULT_LANGUAGE dalla configurazione del negozio (ricerca del codice nella tabella languages)
4. Fallback: 1 (inglese)

Nota: nel contesto di xoPort, $_SESSION['languages_id'] NON è intenzionalmente un’opzione di fallback — altrimenti la lingua di chi effettua la chiamata all’API di amministrazione verrebbe trasferita involontariamente all’ordine del cliente.

Facoltativamente, il chiamante può inviare anche l’importo totale previsto — il negozio effettua un confronto e segnala un allarme in caso di discrepanza:

• expected_total (decimale): importo ot_total previsto dopo il calcolo.
• strict_totals (booleano, predefinito false):
  • false → La discrepanza viene segnalata come avviso nella risposta, ma l’ordine viene comunque creato.
  • true → L’ordine viene rifiutato se il totale calcolato ≠ expected_total (tolleranza: 0,01 €).

Utilizzo: importazioni dal marketplace, dove il marketplace conosce già l’importo finale — il negozio verifica che prezzo × quantità × imposta + spese di spedizione diano lo stesso importo anche a livello locale.

Per le integrazioni che conoscono solo il numero cliente, un indirizzo di consegna diverso e SKU/quantità — l’ordine viene creato in modo tale da riportare prezzi, caratteristiche, spedizione e conferma esattamente come un ordine manuale del negozio (parità dropship, ad es. SPV → SST).

Riga fiscale per ogni voce (v2.32.0): ot_tax viene inserita per ogni aliquota con una dicitura che specifica l’aliquota esatta nel formato frontend — «più IVA al 19%» (netto) oppure «IVA al 19% inclusa» (lordo), a condizione che MODULE_ORDER_TOTAL_PREFIX=true.

external_reference — Integrazione con il marketplace

Collega l’ordine a una fonte esterna. Campi consentiti:

• source (stringa, obbligatorio): ad es. amazon, ebay, otto, kaufland.
• external_id (stringa, obbligatorio): ID/numero sul Marketplace.
• marketplace_id (int, facoltativo): ID interno del Marketplace XONIC.

tracking — Tracciamento delle spedizioni

Array di voci di tracciamento. Per ogni voce è consentito:

• service_provider (alias: method): nome del corriere (DHL, DPD, UPS, …).
• code (alias: tracking_number): numero di spedizione.
• link: URL di tracciamento.
• label_link: URL dell’etichetta di spedizione (PDF).
• external_id: ID presso il corriere.
• is_retoure (bool): spedizione di reso anziché spedizione in uscita.

status_history — Cronologia degli stati

Log di audit di sola aggiunta. Per ogni voce: orders_status_id, comments, customer_notified (0/1), date_added.

customer_notified A livello di ordine

Booleano, controlla se, in caso di cambiamento di stato, viene attivato l’invio dell’e-mail di conferma.

curl -X POST "https://shop.de/xpanel/xoport/Import/JSON/orders" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [{
      "customers_id": 51,
      "payment_method": "PayPal",
      "tax_flag": 0,
      "expected_total": "71.38",
      "products": [{"products_id": 42, "quantity": 2, "products_price": "29.99", "products_tax": "19.00"}]
    }]
  }'

Risposta di esempio (Successo)

{
  "success": true,
  "api_version": "2.32.0",
  "type": "orders",
  "operation": "create",
  "data": [{
    "orders_id": 46482,
    "customers_id": 51,
    "ot_subtotal": "59.98",
    "ot_tax": "11.40",
    "ot_total": "71.38",
    "totals_mode": "auto",
    "tax_flag": 0,
    "language_id": 2
  }],
  "warnings": []
}

Risposta di esempio (controllo della deriva fallito, strict_totals=true)

{
  "success": false,
  "api_version": "2.32.0",
  "error": {
    "code": "TOTAL_DRIFT",
    "message": "Calculated ot_total 71.38 differs from expected_total 70.00 (diff: 1.38).",
    "details": {"expected": "70.00", "calculated": "71.38", "tolerance": "0.01"}
  }
}

Avvisi non critici (l’ordine viene comunque creato, restituzione in warnings[]): PRODUCT_MODEL_NOT_FOUND, RECALC_PRODUCT_NOT_FOUND, CATEGORY_DISCOUNT_UNAVAILABLE, SHIPPING_AUTO_FAILED, SHIPPING_AUTO_EMPTY, TOTAL_DRIFT (tranne nel caso di strict_totals=true), UNKNOWN_FIELD.

Lettura degli ordini con GET /orders, ambito orders:read.

Tipi di percorso

• /order/{id}, /orders/{von}:{bis}, /orders/{von}: e /orders/new:{datum} (ordinati in base alla data).
• A partire dalla v2.122.9 i filtri agiscono in aggiunta alla forma del percorso. Fino alla versione 2.122.8 un filtro sostituiva la forma del percorso: /order/{id}?status=3 restituiva tutti gli ordini con stato 3.
• A partire dalla v2.122.10, le forme di percorso scorrono il database in ordine crescente per ID. Senza ?limit=, la risposta rimane non ordinata fino al limite massimo; oltre tale limite, viene restituita in formato standard con has_more. new:{datum} viene verificato (YYYY-MM-DD, YYYY-MM-DD HH:MM o YYYY-MM-DD HH:MM:SS); in caso contrario, viene restituito un errore HTTP 400 INVALID_RANGE.
• v2.122.12 Il segmento successivo a /order o /orders è un numero intero con un massimo di 18 cifre, un intervallo con limiti interi oppure new:{datum} con due punti non codificati; in caso contrario viene restituito un errore HTTP 400 INVALID_RANGE. Gli spazi vuoti ai margini non vengono conteggiati: /order/42%20 corrisponde all'ordine 42.

Valori non validi

• A partire dalla v2.122.10, le date sono ammesse solo in formati fissi: YYYY-MM-DD, YYYY-MM-DD HH:MM o YYYY-MM-DD HH:MM:SS, facoltativamente con fuso orario (Z o ±HH:MM; inviare il segno più come %2B ). Indicazioni come yesterday o 01.10.2026 restituiscono un errore HTTP 400 INVALID_FILTER_VALUE.
• A partire dalla versione v2.122.10, valori sotto forma di elenco come ?customer_id[]=5, nonché un elenco separato da virgole, un testo o un numero decimale inviati a status, customer_id, marketplace_id, products_id e categories_id generano un errore HTTP 400 INVALID_FILTER_VALUE con details[]. In precedenza, un filtro di questo tipo veniva ignorato e la risposta conteneva tutti gli ordini. Solo delivery_country accetta valori multipli.
• Un valore vuoto è considerato come non impostato. I parametri sconosciuti vengono segnalati da warnings[] come UNKNOWN_FILTER, mentre con ?_strict=true viene restituito un errore HTTP 400.

Novità nella v2.122.10: tutti gli stati dell’ordine con il nome per ciascuna lingua e il relativo significato, ambito orders:read. Finora uno stato veniva indicato solo nell’ordine, come ID e con il nome in una sola lingua.

curl "https://shop.de/xpanel/xoport/Export/JSON/order_statuses" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "success": true,
  "api_version": "2.122.10",
  "type": "order_statuses",
  "data": [
    {
      "orders_status_id": 5,
      "orders_status_label": "secondary",
      "orders_status_label_bg": "#000000",
      "orders_status_label_color": "#ffffff",
      "orders_status_sort_order": 0,
      "is_default": false,
      "is_cancelled": true,
      "is_offer": false,
      "counts_as_revenue": false,
      "is_paid": false,
      "is_shipped": false,
      "languages": {
        "en": { "language_id": 1, "language_code": "en", "orders_status_name": "Returned/Cancelled" },
        "de": { "language_id": 2, "language_code": "de", "orders_status_name": "Retoure/Storniert" }
      }
    }
  ],
  "stats": { "total": 1, "count": 1, "timestamp": "2026-10-15 10:00:00" }
}

Indicatori

I contrassegni seguono le impostazioni di stato del negozio. Un’impostazione vuota non indica alcuno stato. Non presenti nel record: «restituito», «completato» e pagamento parziale.

Formati dei percorsi e parametri

• /order_statuses: tutti gli stati, in ordine crescente secondo orders_status_id.
• /order_status/{id} e /order_statuses/{id}: esattamente questo stato; in caso di mancata corrispondenza, HTTP 404 NOT_FOUND.
• /order_statuses/{von}:{bis} e /order_statuses/{von}:: intervallo; vuoto = HTTP 200 con data vuoto.
• Nessun filtro; ?language= non cambia nulla, vengono sempre visualizzate tutte le lingue. new:{datum} restituisce HTTP 400 INVALID_RANGE.

orders_status_label è la classe di colori dell’elenco del backend (custom = colori personalizzati da orders_status_label_bg e orders_status_label_color), orders_status_sort_order è l’ordine degli elenchi di selezione. Viene restituita la riga della lingua tedesca, come su /orders.