Point final « Commandes » (Orders)

Remarque : l'importation et la suppression d'entrées d'historique nécessitent l'utilisation de orders:write. L'API ne supprime pas les commandes elles-mêmes : DELETE /Delete/JSON/orders renvoie un code HTTP 501 NOT_IMPLEMENTED. L'enregistrement en stock s'effectue automatiquement lors de la création. Seule l'API DELETE /Delete/JSON/order_status_history/{id} permet de supprimer une entrée d'historique : le statut de la commande est alors mis à jour, et la boutique rejette l'entrée la plus ancienne d'une commande (HTTP 409 FIRST_HISTORY_ENTRY). Détails : API de suppression.

Crée ou met à jour une commande. POST = Créer, PUT avec orders_id = Mettre à jour. Tous les champs sont vérifiés et enregistrés par le même service que celui utilisé pour créer les commandes lors des importations depuis les places de marché.

Charge utile minimale (Création)

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

Charge utile complète avec toutes les options

{
  "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"}
    ]
  }]
}

Le paramètre « totals_mode » permet de contrôler la manière dont les montants totaux des commandes sont calculés :

Si tax_flag n’est pas explicitement défini, il est dérivé du groupe de clients :

• customers_groups.show_tax = 1 + DISPLAY_PRICE_WITH_TAX = true → tax_flag = 1 (brut)
• customers_groups.show_tax = 0 → tax_flag = 0 (net)
• Groupes exonérés de taxe (par ex. numéro d'identification TVA UE) → tax_flag = 2 (exonéré de taxe)

Interprétation de « products_price » en fonction de tax_flag

⚠️ Important pour les importations depuis une place de marché : si la place de marché envoie des prix nets, la variable « tax_flag: 0 » DOIT être explicitement définie — sinon, les prix (pour un groupe de clients « brut ») seront interprétés comme des prix bruts.

Depuis la version v2.122.8, les lignes de commande présentant un montant de TVA négatif, comme les remboursements, se voient attribuer une ligne de TVA identique à celle de la page de paiement. Lors de l’ajout de lignes de commande via PUT, la TVA des lignes négatives est prise en compte. Les nouvelles lignes enregistrent, lors de leur création, s’il s’agit d’une marchandise ou d’un service ; les documents relatifs aux livraisons et prestations intracommunautaires restent ainsi inchangés.

Origine du prix

Le fait qu’un montant soit interprété comme net ou brut dépend de qui l’a déterminé : l’interface (Payload) ou la boutique (base de données, module d’expédition).

Depuis la v2.122.8, chaque article nouvellement créé (POST et PUT avec products_mode: "append") enregistre s’il s’agit d’une marchandise (0) ou d’un service (1). Cette valeur détermine, sur la facture et la facture électronique, la mention fiscale relative aux livraisons ou prestations intracommunautaires ainsi que l’exclusion du droit de rétractation.

En l’absence de ce champ, la boutique détermine la valeur à partir du produit, à l’instar de la caisse et de l’éditeur de commande :

Nouveauté de la version v2.122.11 : avec ce champ, la valeur envoyée s’applique, même si elle contredit les données du produit, par exemple pour un poste de service libre :

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}]}]}'

• Les valeurs autorisées sont 1, 0, true, false, "1" et "0". Aucune autre valeur n’est prise en compte : la réponse indique « service_invalid » dans « records[].warnings », et la valeur provient du produit.
• Uniquement lors de la création. Les lignes existantes conservent leur valeur : products_mode: "update" rejette service, l'enregistrement échoue avec FIELD_NOT_UPDATABLE, et rien n'est écrit, pas même les autres champs (réponse HTTP 200 comme pour toute importation groupée). Pour corriger cela, annulez la ligne et rajoutez-la avec service.
• Les boutiques jusqu’à la version 4.9.170 ne reconnaissent pas ce champ : il est ignoré sous la forme UNKNOWN_FIELD (avec ?_strict=true et un code HTTP 400), et un poste de service libre y est considéré comme une marchandise. Pour savoir si une boutique reconnaît ce champ, consultez api_version dans GET /me.
• L'exportation fournit la valeur par ligne dans products[].service: 0, 1 ou null pour les anciennes commandes sans valeur enregistrée.

Si language_id ne figure pas dans la charge utile, la résolution s'effectue en cascade :

1. valeur de la charge utile (si définie)
2. customers.language_id issu de la fiche client
3. DEFAULT_LANGUAGE issu de la configuration de la boutique (recherche de code dans la table « languages »)
4. Solution de secours : 1 (anglais)

Remarque : dans le contexte xoPort, « $_SESSION['languages_id'] » n’ est délibérément PAS une solution de secours — sinon, la langue de l’appelant de l’API d’administration serait transmise par inadvertance à la commande client.

En option, l’appelant peut envoyer le montant total attendu — la boutique effectue une comparaison et déclenche une alerte en cas d’écart :

• expected_total (décimal) : montant total attendu de l’ ot_total après calcul.
• strict_totals (booléen, par défaut false) :
  • false → L'écart est signalé sous forme d'avertissement dans la réponse, mais la commande est tout de même créée.
  • true → La commande est refusée si le total calculé ≠ expected_total (tolérance : 0,01 €).

Utilisation : importations depuis une place de marché où celle-ci connaît déjà le montant final — la boutique vérifie que le produit « prix × quantité × taxe + frais de port » donne le même montant localement.

Pour les intégrations qui ne connaissent que le numéro de client, une adresse de livraison différente et la référence/quantité — la commande est créée de manière à ce qu’elle reprenne exactement les prix, les caractéristiques, les frais de port et la confirmation d’une commande manuelle passée sur la boutique (parité dropshipping, par exemple SPV → SST).

Ligne fiscale par enregistrement (v2.32.0) : ot_tax est généré pour chaque taux d’imposition avec une libellé précis au format front-end — « TVA de 19 % en sus » (net) ou « TVA de 19 % incluse » (brut), à condition que MODULE_ORDER_TOTAL_PREFIX=true.

external_reference — Connexion à la place de marché

Relie la commande à une source externe. Champs autorisés :

• source (chaîne de caractères, obligatoire) : par exemple amazon, ebay, otto, kaufland.
• external_id (chaîne de caractères, obligatoire) : identifiant/numéro sur la place de marché.
• marketplace_id (int, facultatif) : identifiant interne de la place de marché XONIC.

tracking — Suivi d'expédition

Tableau d’entrées de suivi. Autorisé par entrée :

• service_provider (alias : method) : nom du transporteur (DHL, DPD, UPS, …).
• code (alias : tracking_number) : numéro d'envoi.
• link: URL de suivi.
• label_link: URL de l'étiquette d'expédition (PDF).
• external_id: ID auprès du prestataire de services d'expédition.
• is_retoure (bool) : envoi de retour au lieu d’un envoi initial.

status_history — Historique des statuts

Journal d'audit en mode « append-only ». Par entrée : orders_status_id, comments, customer_notified (0/1), date_added.

customer_notified Au niveau de la commande

Booléen, détermine si l’envoi d’un e-mail de confirmation est déclenché lors d’un changement de statut.

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"}]
    }]
  }'

Exemple de réponse (succès)

{
  "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": []
}

Exemple de réponse (vérification de dérive échouée, 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"}
  }
}

Avertissements non critiques (la commande est tout de même créée, retour dans warnings[]) : PRODUCT_MODEL_NOT_FOUND, RECALC_PRODUCT_NOT_FOUND, CATEGORY_DISCOUNT_UNAVAILABLE, SHIPPING_AUTO_FAILED, SHIPPING_AUTO_EMPTY, TOTAL_DRIFT (sauf pour strict_totals=true), UNKNOWN_FIELD.

Lecture des commandes avec GET /orders, Scope orders:read.

Formes de sentiers

• /order/{id}, /orders/{von}:{bis}, /orders/{von}: et /orders/new:{datum} (classés par date).
• Depuis la version 2.122.9, les filtres s'appliquent en plus de la forme de chemin. Jusqu'à la version 2.122.8, un filtre remplaçait la forme de chemin : /order/{id}?status=3 renvoyait toutes les commandes ayant le statut 3.
• Depuis la v2.122.10, les formes de chemin parcourent la base de données par ordre croissant d’ID. Sans ?limit=, la réponse reste non triée jusqu’à la limite maximale ; au-delà, elle est renvoyée en taille standard avec has_more. new:{datum} est vérifié (YYYY-MM-DD, YYYY-MM-DD HH:MM ou YYYY-MM-DD HH:MM:SS), sinon une erreur HTTP 400 est renvoyée INVALID_RANGE.
• v2.122.12 Le segment suivant /order ou /orders est un nombre entier comportant au maximum 18 chiffres, une plage délimitée par des nombres entiers ou new:{datum} suivi d’un deux-points non codé ; toute autre valeur génère une erreur HTTP 400 INVALID_RANGE. Les espaces en bordure ne sont pas pris en compte : /order/42%20 correspond à la commande n° 42.

Valeurs non valides

• Depuis la v2.122.10, les dates et heures doivent être exprimées sous des formats fixes : YYYY-MM-DD, YYYY-MM-DD HH:MM ou YYYY-MM-DD HH:MM:SS, avec ou sans fuseau horaire (Z ou ±HH:MM; envoyer le signe « + » sous la forme %2B ). Les entrées telles que yesterday ou 01.10.2026 renvoient une erreur HTTP 400 INVALID_FILTER_VALUE.
• Depuis la version v2.122.10, les valeurs sous forme de liste telles que ?customer_id[]=5, ainsi qu’une liste séparée par des virgules, un texte ou un nombre décimal envoyés à status, customer_id, marketplace_id, products_id et categories_id, génèrent une erreur HTTP 400 INVALID_FILTER_VALUE avec details[]. Auparavant, un tel filtre était ignoré et la réponse contenait toutes les commandes. Seul delivery_country accepte plusieurs valeurs.
• Une valeur vide est considérée comme non définie. Les paramètres inconnus sont signalés par warnings[] sous la forme UNKNOWN_FILTER, tandis que ?_strict=true renvoie une erreur HTTP 400.

Nouveauté de la v2.122.10: tous les statuts de commande avec leur nom dans chaque langue et leur signification, portée orders:read. Jusqu’à présent, un statut n’apparaissait que sur la commande, sous forme d’ID et avec son nom dans une seule langue.

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" }
}

Indicateurs

Les indicateurs suivent les paramètres de statut de la boutique. Un paramètre vide n'indique aucun statut. Absents de l'enregistrement : « retourné », « clôturé » et paiement partiel.

Formats de chemin et paramètres

• /order_statuses: tous les statuts, classés par ordre croissant selon orders_status_id.
• /order_status/{id} et /order_statuses/{id}: exactement ce statut, sans résultat (HTTP 404 NOT_FOUND).
• /order_statuses/{von}:{bis} et /order_statuses/{von}:: plage, vide = HTTP 200 avec data vide.
• Pas de filtres ; ?language= ne change rien, toutes les langues s’affichent systématiquement. new:{datum} renvoie un HTTP 400 INVALID_RANGE.

orders_status_label correspond à la classe de couleur de la liste du backend (custom = couleurs personnalisées issues de orders_status_label_bg et orders_status_label_color), orders_status_sort_order à l'ordre des listes de sélection. La ligne correspondant à la langue « Allemand » est renvoyée, comme sur /orders.