API di esportazione: recuperare i dati del negozio tramite GET

Le singole recensioni della pagina del prodotto con valutazione a stelle, titolo, testo e risposta del negozio per ogni lingua. Senza filtri, l'elenco mostra solo le recensioni approvate, ovvero le stesse presenti sulla pagina del prodotto. La query singola /review/{id} fornisce una recensione anche prima dell'approvazione.

Esempio – sincronizzazione giornaliera, comprese le approvazioni revocate:
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 indica il numero di risultati, il numero di record e l’ora della risposta; durante la navigazione, anche la dimensione della pagina e la posizione. Tutte le chiavi e quando si naviga: sezione «Pagination» in fondo.
• warnings[] Viene visualizzato solo in presenza di avvisi, ad esempio UNKNOWN_FILTER per un parametro sconosciuto.

Tutti gli endpoint di esportazione utilizzano gli stessi parametri di query:

Senza limit, la possibilità di scorrere le pagine dipende dall'endpoint:

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

La risposta contiene nell’oggetto stats:

• total — Numero di risultati prima dello scorrimento (sempre)
• count — Numero di record in questa risposta (sempre)
• timestamp — Ora della risposta, ad esempio 2026-10-18 14:00:00 (sempre)
• limit, offset — dimensione della pagina applicata e posizione iniziale, solo in caso di scorrimento
• has_more — true, se dopo questa pagina seguono altri risultati; solo se si scorre la pagina
• page — solo dopo ?page=

Non presentano " stats " i documenti di riferimento (/order_document/{id}) e il recupero del file allegato a un ticket (?file=); in entrambi i casi non si effettua lo scorrimento.

• Laddove senza limit la risposta viene fornita senza scorrimento, un offset da solo ha effetto solo in presenza di più di 250 risultati. Per uno scorrimento mirato, inviare quindi sempre limit.
• Se nel percorso è presente un ID o un intervallo, ?page= restituisce un errore HTTP 400 INVALID_PAGINATION, poiché il percorso indica già i record. Solo le valutazioni (anche con ID) e i carrelli con intervallo {a}:{b} consentono la navigazione anche tramite page.
• L'elenco viene visualizzato per intero quando si continua a scorrere tramite limit e page o offset, fino a quando has_more diventa false.

L’esportazione dei prodotti può essere limitata a livello di server, invece di recuperare l’intero catalogo pagina per pagina. Una virgola separa un elenco di inclusioni (massimo 100 valori); più filtri vengono combinati con l’operatore “E”.

Esempio – tutti gli articoli acquistabili con EAN libro che non rientrano nell’aliquota ridotta:
GET /products?ean_prefix=978,979,977&tax_class_id=0,1&status=1&limit=250

stats.total indica il numero di risultati del filtro, non la dimensione del catalogo.

A partire dalla v2.122.11, un valore composto esclusivamente da virgole inviato a products_model, products_ean o seo_name (?products_model=,) genera un errore HTTP 400 INVALID_FILTER_VALUE; in precedenza il filtro veniva ignorato e veniva restituito il catalogo non filtrato. Gli altri elenchi di filtri rifiutavano già in precedenza i valori composti esclusivamente da virgole. Un elemento vuoto tra i valori (A,,B) continua a essere ignorato; un valore completamente vuoto significa «non impostato». Filtri del marketplace e selezione dei campi in dettaglio: Products.

GET /coupons fornisce buoni e coupon; GET /coupon/{id} ne fornisce uno. L’ambito è orders:read; non ne esiste uno specifico. I filtri multipli vengono combinati con l’operatore AND.

• last_modified accetta le forme fisse dei filtri delta: YYYY-MM-DD, YYYY-MM-DD HH:MM o YYYY-MM-DD HH:MM:SS (separatore: spazio, T o +), facoltativamente frazioni di secondo e, dopo l’ora, un fuso orario (Z, ±HH:MM, ±HHMM). Un coupon senza data di modifica e di creazione non compare in nessun delta. Un valore vuoto significa «non impostato».
• Un valore di elenco (?type[]=P, ?code[a]=…, anche vuoto) genera un errore HTTP 400 INVALID_FILTER_VALUE per ogni filtro delle cedole; più tipi possono essere specificati come elenco separato da virgole. Tutti gli errori di una richiesta sono raggruppati in details[]; la verifica avviene prima dell’invio della richiesta.
• Solo virgole su ?type= e una data senza contenuto su ?valid_on=: vedi «Solo separatori, UTF-8 non valido» e «Filtro data senza contenuto» più avanti.

Ogni parametro di query di ogni endpoint JSON ha una regola, per Export, Import e Delete. Il controllo avviene prima che l’endpoint legga, scriva o elimini qualcosa: un valore non valido genera un HTTP 400 INVALID_FILTER_VALUE, mentre details[] riporta rispettivamente gli errori param e message. Import e Delete rispondono nella stessa forma («… Nothing was written» o «… Nothing was deleted»). XML, CSV e TXT rimangono invariati.

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]=…). …" }
  ]
}

• I valori di elenco (?param[]=…, ?param[key]=…) generano un errore per ogni parametro. È possibile inserire più valori come elenco separato da virgole, laddove un filtro li accetti (prodotti, clienti, delivery_country …).
• Un valore vuoto (?status=) significa «non impostato». A partire dalla versione v2.122.12, gli spazi vuoti ai margini non vengono conteggiati (vedi «Spazi vuoti ai margini» più sotto); nei negozi precedenti alla versione 4.9.173, inviare valori senza spazi vuoti ai margini e omettere i parametri vuoti. I valori validi senza spazi ai margini funzionano come prima, con lo stesso numero di risultati.
• Tutti gli errori di una richiesta sono riportati in un details[]. Lo scorrimento e l’ordinamento (limit, offset, page, sort, order) segnalano INVALID_PAGINATION, ora anche per le forme di percorso e gli endpoint che non supportano lo scorrimento.
• Segnalare i nomi di parametri sconosciuti in fase di esportazione come in precedenza con l'avviso UNKNOWN_FILTER, mentre con ?_strict=true viene restituito un HTTP 400. In fase di importazione e cancellazione, i nomi sconosciuti vengono ignorati silenziosamente.
• /orders Accetta più valori solo in delivery_country: ?status=3,4 genera un errore HTTP 400; inviare una richiesta separata per ogni stato.

Regole

L'ora è valida per last_modified su /tickets, /projects, /project_tasks e /appointments: finora il database interpretava le forme libere come yesterday come data nulla e la risposta non veniva filtrata. Inviate le ore nel formato 2026-10-01 06:00:00.

Parametri per ciascun endpoint

• Il singolare di un endpoint (/ticket/{id}, /order/{id} …) viene verificato con le stesse regole del plurale.
• /categories/productlist dispone di filtri propri: ?categories_id= e ?include_inactive_products= funzionavano già in quel contesto, ma fino alla v2.122.9 segnalavano UNKNOWN_FILTER. Al contrario, ?parent_id= e ?recursive= ora segnalano UNKNOWN_FILTER (con ?_strict=true HTTP 400), poiché non hanno mai funzionato.
• /categories?id= è inattivo dalla versione v2.23.0; un numero valido continua a essere ignorato. È possibile recuperare una singola categoria tramite /categories/{id}.

Il formato di percorso new:{datum} viene valutato solo da /customer(s) e /order(s), sia nell’esportazione JSON che in quella XML. Qualsiasi altro endpoint di esportazione risponde con un errore HTTP 400 INVALID_RANGE e il messaggio indica il filtro di data dell’endpoint, se presente.

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

Nell’esportazione JSON, il segmento successivo all’endpoint (/Export/JSON/{endpunkt}/{segment}) è un ID, un’area, il formato della data o una sottorota. Ciò vale per ogni endpoint di esportazione, compresi ticket, appuntamenti e contratti.

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

• Lo spazio vuoto ai margini di un ID o al confine di un intervallo non conta (spazio %20, tabulazione %09, interruzione di riga %0A/%0D, %00, %0B): /product/42%20 è l’articolo 42, così come ?customers_id=42%20 indica il cliente 42. Un segmento composto esclusivamente da spazio vuoto genera un errore HTTP 400. Un + nel percorso non è uno spazio.
• Dopo un ID o un intervallo può seguire al massimo la sottoruta: /categories/{id}/productlist. Qualsiasi altro segmento o segmento aggiuntivo genera un errore HTTP 400. A partire dalla versione v2.122.13, l’ID o l’intervallo che precede funge da filtro di categoria: /categories/5/productlist restituisce la categoria 5, /categories/5:10/productlist le categorie da 5 a 10, /categories/5:/productlist le categorie a partire dalla 5 (riquadro «Modificato nella v2.122.13» in basso, dettagli alla voce Categories).
• Invariato: esportazione in formato XML, CSV e TXT (in questo caso un segmento senza numero corrisponde al nome di un modello, ad esempio /Export/XML/order/{id}/opentrans), importazione ed eliminazione. Anche in questi casi, inviate gli ID come numeri interi senza caratteri residui.

• Chi invia un ID con caratteri residui e ha accettato l’elenco, ora riceve un HTTP 400. L’elenco non è mai stato la risposta prevista: correggere la codifica o il valore troncato nella connessione.
• ⚠️ Anche le connessioni che finora ricevevano il record di dati previsto ricevono ora un codice HTTP 400 (righe contrassegnate con ⚠️). Inviare l’ID come numero intero senza decimali e senza segno, come nei parametri di query a partire dalla v2.122.10; i valori provenienti dalle tabelle sono spesso del tipo 42.0.
• La segnalazione avviene dopo la verifica dell’endpoint: un endpoint sconosciuto restituisce un codice HTTP 501.

Per un indirizzo noto del negozio (Search Console, vecchia Sitemap, e-mail del cliente), tre filtri precisi restituiscono la categoria, l’articolo o la destinazione di un reindirizzamento. Fino alla versione v2.122.10 venivano riportati i nomi UNKNOWN_FILTER e l’elenco veniva fornito senza filtri.

• Esatto: nessun prefisso e nessun modello, % e _ sono caratteri dell’indirizzo. Non si fa distinzione tra maiuscole e minuscole.
• Se ci sono più risultati, vengono visualizzati tutti, ad esempio due categorie con lo stesso indirizzo o lo stesso slug su due articoli. Se due categorie condividono un indirizzo, il negozio effettua la selezione senza un ordine prestabilito: il primo risultato non è necessariamente la pagina che viene visualizzata.
• I filtri non determinanose il negozio visualizzi o meno la pagina: lo stato, il blocco per gruppi di clienti o l’assegnazione al negozio rimangono, come in precedenza, nei campi del record.
• /categories?seo_string= Funziona anche con ?parent_id=, ?status= e ?language=, /products?seo_name= con tutti i filtri di prodotto e ?fields=, /seohistorys?seo_string= con ?type= e ?base_id=.

Passo dopo passo dall’indirizzo all’ID, con esempi: SEO History.

Errore

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

• Un valore composto esclusivamente da virgole è considerato un errore in ogni lista di filtri, mai come "non impostato". Un elemento vuoto tra i valori (P,,F, P,) viene ignorato; se completamente vuoto (?type=) significa "non impostato". Fa eccezione la selezione del campo, che non è un filtro: ?fields=, non seleziona alcuna chiave e restituisce il record completo.
• Viene sostituito solo il nome o il valore ripetuto nell’avviso e nel messaggio, mai un campo dati.
• Le richieste valide restituiscono una risposta invariata. Risposta vuota nonostante un codice di stato HTTP 200 su un negozio online meno recente: verificare innanzitutto che i nomi dei parametri della richiesta non contengano caratteri codificati in modo errato.

I filtri data che leggono input liberi come yesterday o 01.10.2026 finora interpretavano come “ora” solo un valore ricavato dai segni di punteggiatura. Il filtro veniva così impostato, ma non conteneva una data.

• Per «vuoto» si intende qui: né lettere né cifre. Le forme libere rimangono valide e funzionano come prima (yesterday, -1 day, 01.10.2026).
• Un + nell'indirizzo è uno spazio; per inviare il segno più come carattere, utilizzare %2B.
• Messaggio: Value "," holds no value, only punctuation and white space (no letter or digit). Leave the parameter out (or empty) for no filter.
• I filtri con orari fissi, ad esempio last_modified a /customers e /orders, hanno sempre rifiutato tali valori.

La verifica dei valori valuta ogni valore di query senza spazi ai margini: spazi (nell'indirizzo anche +), tabulazione %09, interruzioni di riga %0A/%0D, %00 e %0B. A partire dalla v2.122.12, l'endpoint riceve esattamente questo valore verificato per le operazioni di esportazione, importazione ed eliminazione. Un valore vuoto o solo spazi vuoti indica «non impostato» per ogni parametro con regola fissa (numero, ID, pulsante, valore di selezione, data, ora, lingua, nome file, lettere e cifre), anche nei casi in cui l’endpoint finora verificava solo la presenza del parametro.

• Rimangono invariati il testo libero (termini di ricerca, nomi, codici come name o rubric), i filtri con verifica autonoma del valore (i filtri per prodotto, cliente e buono sconto; per gli ordini, la data e il paese di consegna; in questi casi il valore verificato era già valido), nonché lo scorrimento e l’ordinamento (limit, offset, page, sort, order). Il testo libero viene troncato dall’endpoint stesso prima di verificare se è presente un valore: anche in questo caso, solo spazi vuoti significano «non impostato», su /wallet_logs?source= a partire dalla v2.122.13 (ultima riga della tabella). Da allora, anche ?source=0 applica un filtro su una fonte «0» che non esiste: una lista vuota. Fino alla v2.122.12, 0 veniva silenziosamente ignorato (tutte le fonti). Nei negozi precedenti alla versione 4.9.174, omettete il parametro se non volete applicare alcun filtro.
• I valori non vuoti senza spazi ai margini rispondono come prima; eccezione a partire dalla v2.122.13: /wallet_logs?source=0 (vedi sopra).
• Importa (_strict) ed Elimina (ciò che ora viene eliminato): si vedano l’API di importazione e l’API di eliminazione.
• I negozi precedenti alla versione 4.9.173 continuano a leggere il valore non troncato: in tal caso, inviare valori senza spazi ai margini e omettere i parametri vuoti (/faqs?language= fornisce in questo caso un elenco vuoto).