Terminal client

Paramètres de requête

Formes de chemin : /customer/{id}, /customers/{von}:{bis}, /customers/{von}: et /customers/new:{datum} (compte créé à partir de la date indiquée). Depuis la version v2.122.10, les formes de chemin permettent de parcourir la base de données par ordre croissant d'ID ; /customers/{von}: correspond à une plage ouverte à partir de l'ID (jusqu'à présent, un seul client). Outre une forme de chemin, seul ?last_modified= fonctionne ; les autres filtres renvoient une erreur HTTP 400 FILTER_NOT_APPLICABLE.

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 le fuseau horaire en option (Z ou ±HH:MM; envoyer le signe « + » sous la forme %2B ). Les valeurs non valides et les valeurs de liste telles que ?email[]= génèrent une erreur HTTP 400 INVALID_FILTER_VALUE sans données.

Depuis la version 2.122.11, une valeur composée uniquement de virgules envoyée à email, lastname, company ou customers_id_extern, par exemple une liste vide, génère une erreur HTTP 400 INVALID_FILTER_VALUE (« holds no value »). Auparavant, ce filtre n’existait pas et l’ensemble du fichier clients était renvoyé. Un élément vide entre deux valeurs continue d’être ignoré ; une valeur entièrement vide signifie « non défini ».

Champs de réponse

• customers_id, customers_email_address
• customers_firstname, customers_lastname
• customers_telephone, customers_fax
• customers_group_id - Groupe de clients
• addresses[] - Toutes les adresses du client
• Nouveautés de la version 2.122.10 order_stats - Références de commande : orders_count, orders_count_valid, first_order_date, last_order_date, first_valid_order_date, last_valid_order_date. Les valeurs avec valid ne tiennent pas compte des commandes annulées ni des devis ; sans commande, la valeur est 0 ou null. Les liaisons strictes en termes de type doivent connaître ce champ.

Champs d'adresse

• entry_company, entry_firstname, entry_lastname
• entry_street_address, entry_postcode, entry_city
• entry_country_id, entry_zone_id

Depuis la v2.122.1, l'export ne contient plus de données de mot de passe : customers_password, customers_password_request, customers_password_request_time et customers_hash sont supprimés sans remplacement ; dans la fiche client, iban et bic sont également supprimés.

Nouveautés de la version 2.122.10

Le panier d'achat par client, périmètre customers:read. Ce périmètre englobe ainsi les paniers d'achat et les indicateurs de commande : veuillez vérifier les autorisations des clients et votre propre politique de confidentialité.

Champs

• Par client : customers_id, basket_last_modified, last_activity, last_activity_source, positions_count et positions[].
• Pour chaque poste : products_id, uprid (code de variante), products_model, products_ean, quantity et final_price sous forme de texte ; basket_type, date_added ainsi que attributes[] avec les caractéristiques sélectionnées.

Filtres

• customer_id et since (modification du panier à partir de la date indiquée, sans marque de modification, au jour près par rapport à la date d'ajout).
• basket_type: N, B, F ou G, plusieurs éléments séparés par des virgules ; un type inconnu renvoie une erreur HTTP 400.
• new:{datum} et {von}: renvoient un code HTTP 400 ; INVALID_RANGE; customer_id et since, lorsqu’ils sont accompagnés d’un identifiant de chemin, renvoient un code HTTP 400 FILTER_NOT_APPLICABLE.

Un panier vide ne contient aucune ligne et n'apparaît pas. C'est pourquoi, lors de la synchronisation des stocks, il convient de procéder régulièrement à une synchronisation complète.

Exemple de requête

curl -X POST "https://shop.de/xpanel/xoport/import/json/customers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "customers",
    "data": [{
      "customers_email_address": "max@example.de",
      "customers_firstname": "Max",
      "customers_lastname": "Mustermann",
      "customers_group_id": 1,
      "addresses": [{
        "entry_company": "Musterfirma GmbH",
        "entry_street_address": "Musterstr. 1",
        "entry_postcode": "12345",
        "entry_city": "Musterstadt",
        "entry_country_id": 81
      }]
    }]
  }'

Modification partielle d’une adresse (PUT)

Corrigé dans la version 2.122.2

Pour modifier une adresse existante, utilisez addresses[] avec address_book_id. Seules les données présentes dans l’objet sont écrites : les champs manquants ou null restent inchangés, "" vide un champ. Le pays et la zone ne changent que si vous les transmettez. Un nouveau pays sans entry_zone_id définit la zone sur 0.

curl -X PUT "https://shop.de/xpanel/xoport/import/json/customers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "customers",
    "data": [{
      "customers_id": 42,
      "addresses": [{
        "address_book_id": 905,
        "entry_street_address": "Neue Straße 99",
        "entry_country": "AT"
      }]
    }]
  }'

• Si le pays est inconnu, warnings[] renvoie l'avertissement ADDRESS_COUNTRY. Lors de la mise à jour, le pays enregistré est conservé, et le pays de la boutique reçoit la nouvelle adresse.
• Les valeurs trop longues sont tronquées caractère par caractère à la longueur de la colonne, avec l'avertissement « ADDRESS_TRUNCATED ».
• Si l'objet ne contient que « _set_default » ou « _set_billing », l'adresse par défaut ou l'adresse de facturation est définie, sans modification des champs d'adresse.

Activer le blocage des newsletters (customers_nl_lock)

Nouveauté de la version v2.122.11

curl -X PUT "https://shop.de/xpanel/xoport/import/json/customers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "customers", "data": [{"customers_id": 42, "customers_nl_lock": 1}]}'

• Valeurs 0/1, true/false ou "0"/"1", pour POST et PUT. La valeur d’exportation peut être renvoyée telle quelle, y compris avec ?_strict=true. Si le champ est manquant, s’il contient null ou s’il est vide, le blocage reste inchangé. Toute autre valeur génère l’avertissement INVALID_FIELD_VALUE; le champ est ignoré et le reste de l’enregistrement est écrit.
• 1 Cela fonctionne comme l’enregistrement du formulaire client : après l’importation, chaque abonnement du compte est résilié, tant dans la boutique que chez le fournisseur de newsletter. Tant que le blocage est en vigueur, POST /newsletter_subscribers rejette l’adresse (NEWSLETTER_LOCKED pour les clients utilisant customers:read, sinon NOT_SUBSCRIBABLE). La désinscription est considérée comme une opposition à la publicité et reste valable même après 0 (OPTED_OUT) : les importations ultérieures rejettent l’adresse, et une nouvelle inscription n’est possible qu’après confirmation par la personne concernée.
• ⚠️ Les e-mails publicitaires issus du marketing et des automatisations (xoMarketing) ne sont pas encore bloqués dans Shop 4.9 ; cette fonctionnalité sera disponible à partir de Shop 4.10.
• Si le prestataire échoue, l’abonnement reste actif et warnings[] renvoie le message NEWSLETTER_UNSUBSCRIBE_FAILED; le blocage est enregistré. Les abonnements liés au compte seront supprimés lors de la prochaine synchronisation des newsletters ; pour les abonnements associés uniquement à l’adresse e-mail, renvoyez la demande de blocage.
• 0 Cette opération ne fait que lever le blocage et ne réinscrit personne.
• Dans le CSV-Porter (colonne « customers newsletter lock ») et dans l’importation de clients au format XML (colonne « customers_nl_lock », uniquement avec votre propre XSL), « 1 » supprime également le verrouillage. Contrairement à l’API, une cellule vide et toute autre valeur lèvent le verrouillage dans ces cas-là.

Nouveauté de la version 2.57.0

Le champ « discounts[] » vous permet de gérer les remises client (champ « Remises » dans la gestion des clients, table customers_discount). Une ligne de remise signifie : x % de remise sur la catégorie N.

Exemple de requête

curl -X PUT "https://shop.de/xpanel/xoport/import/json/customers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "customers",
    "data": [{
      "customers_id_extern": "20050",
      "discounts": [
        {"category_id": 0, "value": 10},
        {"category_id": 22, "value": "12,5", "subcategories": 0, "special": 1}
      ]
    }]
  }'

Champs par ligne de remise

Sémantique « Replace-on-present »

• discounts avec des entrées existantes → l'ensemble des remises du client est remplacé
• "discounts": [] (vide) → toutes les remises du client sont supprimées
• Champ manquant → les réductions restent inchangées (les connexions existantes n’ont aucune incidence)

Le drapeau d’activation interne du client est automatiquement mis à jour – les remises s’appliquent immédiatement dans la boutique. La même logique s’applique également à l’importation de clients au format XML (nœud<discounts>).

Exportation : l’exportation des clients (GET) fournit les discounts sous forme de lignes brutes – compatible avec les allers-retours.

Nouveauté de la v2.57.0

• customers_id_extern (numéro de client WaWi) et customers_group_id sont désormais modifiables dans l’importation JSON ; customers_group_id est validé par rapport aux groupes de clients existants.
• La méthode PUT permet désormais d’adresser le client même sans e-mail, via customers_id ou customers_id_extern (gestion des remises et des données de base uniquement). customers_id_extern doit être unique.
• La méthode POST continue d'exiger une adresse e-mail et une adresse postale.

Le client est identifié par son ID dans le chemin d’accès : DELETE /xpanel/xoport/delete/json/customers/{ID}. En l’absence d’ID, par exemple avec ?customers_id=, l’API renvoie une réponse HTTP 400 MISSING_ID.

curl -X DELETE "https://shop.de/xpanel/xoport/delete/json/customers/123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Remarque : données relevant du RGPD ! Respectez les délais de conservation des commandes.

Depuis la version v2.122.8, la boutique anonymise l'historique des produits consultés par le client avant de le supprimer.