API d'exportation : récupérer les données de la boutique via une requête GET

Les avis individuels de la page produit avec note par étoiles, titre, texte et réponse de la boutique pour chaque langue. Sans filtre, la liste ne fournit que les avis validés, c'est-à-dire les mêmes que ceux affichés sur la page produit. La requête individuelle /review/{id} fournit un avis même avant sa validation.

Exemple – synchronisation quotidienne, y compris les validations annulées :
GET /reviews?status=all&since=2026-10-05&limit=250&page=1

GET /Export/JSON/categories/128?language=de

{
  "success": true,
  "api_version": "2.122.12",
  "type": "categories",
  "data": [
    {
      "categories_id": 128,
      "parent_id": 97,
      "status": 1,
      "languages": {
        "de": {
          "categories_name": "xoPort REST API",
          "categories_description": "..."
        }
      },
      "restricted_customer_groups": []
    }
  ],
  "stats": {
    "total": 1,
    "count": 1,
    "timestamp": "2026-10-18 14:00:00"
  }
}

• stats indique le nombre de résultats, le nombre d’enregistrements et l’heure de la réponse ; en cas de pagination, il indique également la taille de la page et la position. Toutes les clés et les moments où la pagination s’effectue : voir la section « Pagination » ci-dessous.
• warnings[] N’apparaît que s’il y a des remarques, par exemple UNKNOWN_FILTER pour un paramètre inconnu.

Tous les points de terminaison d'exportation utilisent les mêmes paramètres de requête :

Sans limit, le défilement dépend du point de terminaison :

Exemple : GET /products?limit=50&offset=100

La réponse contient dans l'objet ` stats` :

• total — Nombre de résultats avant le défilement (toujours)
• count — Nombre d’enregistrements dans cette réponse (toujours)
• timestamp — Heure de la réponse, par exemple 2026-10-18 14:00:00 (toujours)
• limit, offset — la taille de page appliquée et la position de départ, uniquement en cas de défilement
• has_more — true, si d’autres résultats suivent cette page ; uniquement en cas de défilement
• page — uniquement après ?page=

Les documents justificatifs (/order_document/{id}) et le téléchargement d’une pièce jointe à un ticket (?file=) ne comportent pas de « stats » ; aucun des deux ne permet de faire défiler les pages.

• Lorsque la page est fournie sans « limit » et sans pagination, un « offset » seul ne fonctionne qu’à partir de plus de 250 résultats. Pour une pagination ciblée, il faut donc toujours envoyer « limit ».
• Si le chemin contient un ID ou une plage, ?page= renvoie un code HTTP 400 INVALID_PAGINATION, car le chemin désigne déjà les enregistrements. Seules les évaluations (y compris celles avec un ID) et les paniers contenant une plage {a}:{b} permettent de faire défiler la liste via page.
• La liste s'affiche dans son intégralité lorsque l'on fait défiler les pages via limit et page ou offset, jusqu'à ce que has_more devienne false.

L'exportation des produits peut être limitée côté serveur, au lieu de récupérer l'intégralité du catalogue page par page. Une virgule sépare une liste d'inclusion (100 valeurs au maximum) ; plusieurs filtres sont combinés par une opération « ET ».

Exemple – tous les articles disponibles à la vente avec un code EAN « livre » qui ne bénéficient pas d’un taux réduit :
GET /products?ean_prefix=978,979,977&tax_class_id=0,1&status=1&limit=250

stats.total indique le nombre de résultats du filtre, et non la taille du catalogue.

Depuis la v2.122.11, une valeur composée uniquement de virgules envoyée à products_model, products_ean ou seo_name (?products_model=,) génère une erreur HTTP 400 INVALID_FILTER_VALUE; auparavant, le filtre n’était pas appliqué à cet endroit et le catalogue non filtré était renvoyé. Les autres listes de filtres rejetaient déjà auparavant les valeurs composées uniquement de virgules. Un élément vide entre deux valeurs (A,,B) continue d’être ignoré ; une valeur entièrement vide signifie « non défini ». Filtres de la place de marché et sélection des champs en détail : Products.

GET /coupons fournit des bons d’achat et des coupons, dont l’un est accessible via GET /coupon/{id}. La portée est orders:read; il n’existe pas de portée spécifique. Les filtres multiples sont combinés par une opération « ET ».

• last_modified accepte les formats fixes des filtres Delta : YYYY-MM-DD, YYYY-MM-DD HH:MM ou YYYY-MM-DD HH:MM:SS (séparateur : espace, T ou +), éventuellement des fractions de seconde et, après l’heure, un fuseau horaire (Z, ±HH:MM, ±HHMM). Un coupon sans date de modification ni de création n’apparaît dans aucun Delta. Une valeur vide signifie « non défini ».
• Une valeur de liste (?type[]=P, ?code[a]=…, y compris vide) génère une erreur HTTP 400 « INVALID_FILTER_VALUE » pour chaque filtre de coupon ; plusieurs types peuvent être indiqués sous forme de liste séparée par des virgules. Toutes les erreurs d’une requête sont regroupées dans details[]; la validation s’effectue avant l’interrogation.
• Uniquement des virgules à l'adresse ?type= et une date vide à l'adresse ?valid_on=: voir « Uniquement des séparateurs, UTF-8 non valide » et « Filtre de date vide » ci-dessous.

Chaque paramètre de requête de chaque point de terminaison JSON est soumis à une règle, qu’il s’agisse d’exportation, d’importation ou de suppression. La vérification s’effectue avant que le point de terminaison ne lise, n’écrive ou ne supprime quoi que ce soit : une valeur invalide renvoie un code HTTP 400 « INVALID_FILTER_VALUE », et « details[] » renvoie respectivement les codes d’erreur « param » et « message ». Les opérations d’importation et de suppression renvoient la même réponse (« … Nothing was written » ou « … Nothing was deleted »). Les formats XML, CSV et TXT restent inchangés.

GET /Export/JSON/tickets?status=abc&priority[]=2

HTTP 400
{
  "success": false,
  "error": {
    "code": "INVALID_FILTER_VALUE",
    "message": "One or more filter values could not be used. No data was returned — see \"details\"."
  },
  "details": [
    { "param": "status", "message": "Value \"abc\" is not an integer." },
    { "param": "priority",
      "message": "Value must be a single value, not a list (param[]=… or param[key]=…). …" }
  ]
}

• Les valeurs de liste (?param[]=…, ?param[key]=…) génèrent une erreur pour chaque paramètre. Les valeurs multiples sont acceptées sous forme de liste séparée par des virgules lorsqu’un filtre les prend en charge (produits, clients, delivery_country …).
• Une valeur vide (?status=) signifie « non défini ». Depuis la version 2.122.12, les espaces en bordure ne sont plus pris en compte (voir « Espaces en bordure » ci-dessous) ; dans les boutiques antérieures à la version 4.9.173, envoyez les valeurs sans espaces en bordure et omettez les paramètres vides. Les valeurs valides sans espace en bordure fonctionnent comme auparavant, avec le même nombre de résultats.
• Toutes les erreurs d’une requête sont répertoriées dans un details[]. Le défilement et le tri (limit, offset, page, sort, order) signalent INVALID_PAGINATION, désormais également pour les formes de chemin et les points de terminaison qui ne permettent pas le défilement.
• Signaler les noms de paramètres inconnus lors de l’exportation comme auparavant avec l’avertissement UNKNOWN_FILTER, et avec ?_strict=true, renvoyer une erreur HTTP 400. Lors de l’importation et de la suppression, les noms inconnus sont ignorés sans message.
• /orders N'accepte plusieurs valeurs que pour « delivery_country » : « ?status=3,4 » renvoie un code HTTP 400 ; il faut envoyer une requête distincte pour chaque statut.

Règles

L'heure s'applique à last_modified vers /tickets, /projects, /project_tasks et /appointments: jusqu'à présent, la base de données interprétait les formats libres tels que yesterday comme une date nulle, et la réponse n'était pas filtrée. Envoyez les heures sous la forme 2026-10-01 06:00:00.

Paramètres par point d'extrémité

• La forme au singulier d’un point de terminaison (/ticket/{id}, /order/{id} …) est vérifiée selon les mêmes règles que la forme au pluriel.
• /categories/productlist dispose de ses propres filtres : ?categories_id= et ?include_inactive_products= y fonctionnaient déjà, mais renvoyaient jusqu’à la version v2.122.9 le message « UNKNOWN_FILTER ». À l’inverse, ?parent_id= et ?recursive= renvoient désormais « UNKNOWN_FILTER » (avec « ?_strict=true HTTP 400 »), car ils n’ont jamais fonctionné.
• /categories?id= est sans effet depuis la v2.23.0 ; un nombre valide continue d'être ignoré. Vous pouvez récupérer une seule catégorie via /categories/{id}.

Le format de chemin new:{datum} n'évalue que /customer(s) et /order(s), tant dans l'exportation JSON que dans l'exportation XML. Tout autre point de terminaison d'exportation répond par un code HTTP 400 INVALID_RANGE, et le message indique le filtre de date du point de terminaison, s'il en existe un.

GET /Export/JSON/products/new:2026-10-01

HTTP 400
{
  "success": false,
  "api_version": "2.122.10",
  "error": {
    "code": "INVALID_RANGE",
    "message": "The new:{date} path form is not supported on /products. It is available on /customer, /customers, /order, /orders only. Filter by date with ?last_modified= instead."
  }
}

# stattdessen
GET /Export/JSON/products?last_modified=2026-10-01

Dans l’exportation JSON, le segment suivant le point de terminaison (/Export/JSON/{endpunkt}/{segment}) est un ID, une plage, le format de date ou une sous-route. Cela s’applique à chaque point de terminaison d’exportation, y compris aux tickets, aux rendez-vous et aux contrats.

GET /Export/JSON/product/42x

HTTP 400
{
  "success": false,
  "api_version": "2.122.12",
  "error": {
    "code": "INVALID_RANGE",
    "message": "Malformed path segment \"42x\": not an id. Valid: {id}, {int}:{int}, {int}: or new:{date}."
  }
}

• Les espaces à la fin d’un identifiant ou à la limite d’une plage ne comptent pas (espace %20, tabulation %09, saut de ligne %0A/%0D, %00, %0B) : /product/42%20 correspond à l’article 42, tout comme ?customers_id=42%20 désigne le client 42. Un segment composé uniquement d’espaces génère une erreur HTTP 400. Un + dans le chemin d’accès n’est pas un espace.
• Un identifiant ou une plage est suivi au maximum de la sous-route : /categories/{id}/productlist. Tout autre segment ou segment supplémentaire génère un code HTTP 400. Depuis la version v2.122.13, l'identifiant ou la plage précédant le filtre de catégorie est : /categories/5/productlist renvoie la catégorie 5, /categories/5:10/productlist les catégories 5 à 10, /categories/5:/productlist les catégories à partir de 5 (encadré « Modifié dans la v2.122.13 » ci-dessous, détails sous Catégories).
• Inchangé : exportation au format XML, CSV et TXT (dans ce cas, un segment sans chiffre correspond au nom d’un modèle, par exemple /Export/XML/order/{id}/opentrans), importation et suppression. Envoyez également les identifiants sous forme de nombres entiers, sans caractères supplémentaires.

• Quiconque envoie un identifiant comportant des caractères restants et a accepté la liste reçoit désormais un HTTP 400. La liste n’a jamais été la réponse attendue : corrigez l’encodage ou la valeur tronquée dans la connexion.
• ⚠️ Même les connexions qui recevaient jusqu’à présent l’enregistrement souhaité reçoivent désormais un code HTTP 400 (lignes marquées d’un ⚠️). Envoyez l'ID sous forme de nombre entier sans décimales et sans signe, comme indiqué dans les paramètres de requête depuis la version v2.122.10 ; les valeurs issues des tableaux se présentent souvent sous la forme 42.0.
• La notification est envoyée après vérification du point de terminaison : un point de terminaison inconnu renvoie toujours un code HTTP 501.

Pour une adresse connue de la boutique (Search Console, ancien plan du site, e-mail client), trois filtres précis permettent d’obtenir la catégorie, l’article ou la destination d’une redirection. Jusqu’à la version v2.122.10, les noms « UNKNOWN_FILTER » étaient indiqués et la liste s’affichait sans filtrage.

• Exact : pas de préfixe ni de modèle, « % » et « _ » font partie de l'adresse. La casse n'a pas d'importance.
• Siplusieurs résultats correspondent, ils sont tous affichés, par exemple deux catégories sous la même adresse ou le même slug sur deux articles. Si deux catégories partagent une adresse, la boutique effectue une sélection sans ordre défini : le premier résultat n’est pas nécessairement la page qui sera affichée.
• Les filtres ne déterminent passi la boutique affiche la page : le statut, le blocage par groupe de clients ou l’affectation à la boutique figurent comme auparavant dans les champs de l’enregistrement.
• /categories?seo_string= Cela fonctionne également avec ?parent_id=, ?status= et ?language=, /products?seo_name= avec tous les filtres de produits, ainsi qu’avec ?fields=, /seohistorys?seo_string= avec ?type= et ?base_id=.

Étape par étape, de l'adresse à l'identifiant, avec des exemples : SEO History.

Erreur

{
  "success": false,
  "api_version": "2.122.11",
  "error": {
    "code": "INVALID_FILTER_VALUE",
    "message": "One or more filter values could not be used. No data was returned — see \"details\"."
  },
  "details": [
    { "param": "seo_string", "message": "Value \"lng/en/fishing-rods/\" starts with the language segment \"lng/en/\". Drop it and pass ?language=en instead." }
  ]
}

• Une valeur composée uniquement de virgules est considérée comme une erreur dans toutes les listes de filtres, et non jamais comme « non définie ». Un élément vide entre les valeurs (P,,F, P,) est ignoré ; un élément entièrement vide (?type=) signifie « non défini ». La sélection de champ, qui n’est pas un filtre, constitue une exception : ?fields=, ne sélectionne aucune clé et renvoie l’ensemble complet des données.
• Seuls le nom ou la valeur répétés dans l’avertissement et le message sont remplacés, jamais un champ de données.
• Les requêtes valides renvoient une réponse inchangée. Réponse vide malgré un code HTTP 200 sur une boutique en ligne plus ancienne : vérifiez d’abord si les noms de paramètres de la requête contiennent des caractères mal codés.

Les filtres de date qui lisent des entrées libres telles que yesterday ou 01.10.2026 ne considéraient jusqu’à présent qu’une valeur provenant d’un signe de ponctuation comme « maintenant ». Le filtre était ainsi activé, mais ne comportait pas de date.

• « Vide » signifie ici : ni lettre ni chiffre. Les formats libres restent valides et fonctionnent comme auparavant (yesterday, -1 day, 01.10.2026).
• Un « + » dans l'adresse correspond à un espace ; pour envoyer un signe « + », utilisez « %2B ».
• Message : Value "," holds no value, only punctuation and white space (no letter or digit). Leave the parameter out (or empty) for no filter.
• Les filtres avec des horaires fixes, par exemple last_modified vers /customers et /orders, rejetaient déjà ce type de valeurs auparavant.

La validation des valeurs évalue chaque valeur de requête sans espace en bordure : espace (y compris dans l’adresse +), tabulation %09, saut de ligne %0A/%0D, %00 et %0B. Depuis la version v2.122.12, le point de terminaison reçoit exactement cette valeur validée, pour les opérations d’exportation, d’importation et de suppression. Une valeur vide ou un simple espace signifie « non défini » pour tout paramètre soumis à une règle fixe (nombre, ID, bouton, valeur de sélection, date, heure, langue, nom de fichier, lettres et chiffres), même dans les cas où le point de terminaison se contentait jusqu’à présent de vérifier si le paramètre existait.

• Reste inchangé : le texte libre (mots-clés, noms, codes tels que name ou rubric), les filtres avec vérification de valeur propre (les filtres de produits, de clients et de bons de réduction, ainsi que la date et le pays de livraison pour les commandes ; dans ce cas, la valeur vérifiée était déjà en vigueur), ainsi que le défilement et le tri (limit, offset, page, sort, order). Le point final tronque lui-même le texte libre avant de vérifier s’il contient une valeur : un espace vide signifie également « non défini » à l’adresse /wallet_logs?source= depuis la v2.122.13 (dernière ligne du tableau). Depuis lors, ?source=0 y filtre également, et ce sur une source « 0 » qui n’existe pas : une liste vide. Jusqu’à la v2.122.12, 0 était ignoré en silence (toutes les sources). Dans les boutiques antérieures à la version 4.9.174, omettez ce paramètre si vous ne souhaitez pas filtrer.
• Les valeurs non vides sans espace à la fin répondent comme auparavant ; exception depuis la v2.122.13 : /wallet_logs?source=0 (voir ci-dessus).
• Import (_strict) et Delete (ce qui est désormais supprimé) : voir l’API d’importation et l’API de suppression.
• Les boutiques antérieures à la version 4.9.173 continuent de lire la valeur non tronquée : dans ce cas, envoyez des valeurs sans espace à la fin et omettez les paramètres vides (/faqs?language= renvoie alors une liste vide).