Endpoint dei clienti

Parametri di query

Formati di percorso: /customer/{id}, /customers/{von}:{bis}, /customers/{von}: e /customers/new:{datum} (account creato a partire dalla data). A partire dalla v2.122.10, i formati di percorso scorrono nel database in ordine crescente in base all'ID; /customers/{von}: è un intervallo aperto a partire dall'ID (finora solo quel cliente). Oltre a una forma di percorso, funziona solo ?last_modified=; altri filtri generano un errore HTTP 400 FILTER_NOT_APPLICABLE.

A partire dalla v2.122.10, le date e gli orari 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 ). Valori non validi e valori di elenco come ?email[]= generano un errore HTTP 400 INVALID_FILTER_VALUE senza dati.

A partire dalla v2.122.11, un valore composto esclusivamente da virgole inviato a email, lastname, company o customers_id_extern, ad esempio un elenco lasciato vuoto, genera un errore HTTP 400 INVALID_FILTER_VALUE (“holds no value”). In precedenza il filtro non era attivo e veniva restituito l’intero portafoglio clienti. Un elemento vuoto tra i valori viene ignorato; un valore completamente vuoto significa «non impostato».

Campi di risposta

• customers_id, customers_email_address
• customers_firstname, customers_lastname
• customers_telephone, customers_fax
• customers_group_id - Gruppo di clienti
• addresses[] - Tutti gli indirizzi del cliente
• Novità nella v2.122.10 order_stats - Codici ordine: orders_count, orders_count_valid, first_order_date, last_order_date, first_valid_order_date, last_valid_order_date. I valori con valid non includono gli ordini annullati né le offerte; senza ordine 0 o null. I collegamenti con verifica del tipo devono riconoscere il campo.

Campi indirizzo

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

A partire dalla v2.122.1 l'esportazione non contiene più i dati relativi alle password: customers_password, customers_password_request, customers_password_request_time e customers_hash vengono eliminati senza sostituzione; nel record cliente vengono inoltre eliminati iban e bic.

Novità nella v2.122.10

Il carrello per cliente, ambito customers:read. L’ambito comprende quindi i carrelli e gli indicatori relativi agli ordini: si prega di verificare le autorizzazioni dei clienti e la propria informativa sulla privacy.

Campi

• Per ogni cliente: customers_id, basket_last_modified, last_activity, last_activity_source, positions_count e positions[].
• Per ogni posizione: products_id, uprid (codice variante), products_model, products_ean, quantity e final_price come testo; basket_type, date_added e attributes[] con le caratteristiche selezionate.

Filtro

• customer_id e since (modifica del carrello a partire dal momento, senza indicazione di modifica, con precisione giornaliera rispetto alla data di aggiunta).
• basket_type: N, B, F o G, più elementi come elenco separato da virgole; un tipo sconosciuto genera un errore HTTP 400.
• new:{datum} e {von}: generano un errore HTTP 400; INVALID_RANGE; customer_id e since, se accompagnati da un ID percorso, generano un errore HTTP 400; FILTER_NOT_APPLICABLE.

Un carrello svuotato non contiene alcuna riga e non viene visualizzato. Chi esegue il sincronizzazione delle scorte, quindi, effettua regolarmente una sincronizzazione completa.

Richiesta di esempio

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

Modifica parziale dell’indirizzo (PUT)

Corretto nella v2.122.2

È possibile modificare un indirizzo esistente tramite addresses[] con address_book_id. Viene scritto solo ciò che è contenuto nell’oggetto: i campi mancanti o null rimangono invariati, mentre "" svuota un campo. Il Paese e la zona cambiano solo se vengono inviati. Un nuovo Paese senza entry_zone_id imposta la zona su 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"
      }]
    }]
  }'

• Se il Paese è sconosciuto, warnings[] genera l’avviso ADDRESS_COUNTRY. Durante l’aggiornamento, il Paese memorizzato rimane invariato, mentre il Paese del negozio riceve un nuovo indirizzo.
• I valori troppo lunghi vengono troncati in base al numero di caratteri fino alla lunghezza della colonna, con l’avviso ADDRESS_TRUNCATED.
• Se nell’oggetto sono presenti solo _set_default o _set_billing, vengono impostati rispettivamente l’indirizzo predefinito e l’indirizzo di fatturazione, senza modificare i campi dell’indirizzo.

Impostare il blocco della newsletter (customers_nl_lock)

Novità nella 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}]}'

• Valori 0/1, true/false o "0"/"1", per POST e PUT. Il valore esportato può essere restituito invariato, anche con ?_strict=true. Se il campo manca o è null o vuoto, il blocco rimane invariato. Qualsiasi altro valore genera l’avviso INVALID_FIELD_VALUE; il campo viene ignorato e il resto del record viene scritto.
• 1 Ha lo stesso effetto del salvataggio della scheda cliente: dopo l’importazione, ogni abbonamento dell’account viene cancellato, sia nel negozio online che presso il fornitore della newsletter. Finché il blocco è attivo, POST /newsletter_subscribers rifiuta l’indirizzo (NEWSLETTER_LOCKED per i client con customers:read, altrimenti NOT_SUBSCRIBABLE). La cancellazione è considerata un'opposizione alla pubblicità e rimane valida anche dopo 0 (OPTED_OUT): le importazioni successive rifiuteranno l'indirizzo; una nuova registrazione è possibile solo previa conferma da parte dell'interessato.
• ⚠️ Le e-mail pubblicitarie provenienti da Marketing & Automazioni (xoMarketing) non vengono ancora bloccate nella versione 4.9 di Shop; questa funzionalità sarà disponibile con la versione 4.10.
• Se il fornitore non riesce a eseguire l’operazione, l’abbonamento rimane attivo e warnings[] segnala NEWSLETTER_UNSUBSCRIBE_FAILED; il blocco viene salvato. Gli abbonamenti collegati all’account vengono gestiti dalla successiva sincronizzazione delle newsletter; per gli abbonamenti associati solo tramite l’indirizzo e-mail, inviare nuovamente il blocco.
• 0 Questo comando revoca solo il blocco e non reinserisce nessuno.
• Nel CSV-Porter (colonna «customers newsletter lock») e nell’importazione clienti XML (colonna « customers_nl_lock », solo con XSL personalizzato) « 1 » comporta lo stesso risultato. A differenza di quanto avviene tramite API, in questi casi una cella vuota e qualsiasi altro valore revocano il blocco.

Novità nella v2.57.0

Tramite il campo discounts[] è possibile gestire gli sconti del cliente (campo «Sconti» nella gestione clienti, tabella customers_discount). Una riga di sconto significa: x % di sconto sulla categoria N.

Richiesta di esempio

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

Campi per ogni riga di sconto

Semantica "Replace-on-present"

• discounts se sono presenti voci → l'intero elenco degli sconti del cliente viene sostituito
• "discounts": [] (vuoto) → tutti gli sconti del cliente vengono rimossi
• Campo mancante → gli sconti rimangono invariati (i collegamenti esistenti non modificano nulla)

Il flag di attivazione interno del cliente viene aggiornato automaticamente – gli sconti hanno effetto immediato nel negozio. La stessa semantica si applica anche all’importazione clienti tramite XML (nodo<discounts>).

Esportazione: l’esportazione dei clienti (GET) fornisce discounts come righe grezze – compatibile con il round-trip.

Novità nella v2.57.0

• customers_id_extern (numero cliente WaWi) e customers_group_id sono ora modificabili nell’importazione JSON; customers_group_id viene convalidato rispetto ai gruppi di clienti esistenti.
• PUT ora può indirizzare il cliente anche senza e-mail tramite customers_id o customers_id_extern (pura gestione degli sconti/dei dati anagrafici). customers_id_extern deve essere univoco.
• Il metodo POST richiede ancora l'indirizzo e-mail e l'indirizzo postale.

Il cliente viene identificato tramite il proprio ID nel percorso: DELETE /xpanel/xoport/delete/json/customers/{ID}. Senza ID, ad esempio con ?customers_id=, l’API risponde con codice di stato HTTP 400 MISSING_ID.

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

Nota: dati rilevanti ai fini del GDPR! Rispettare i termini di conservazione previsti per gli ordini.

A partire dalla versione v2.122.8, prima della cancellazione, il negozio online rende anonima la cronologia dei prodotti visualizzati dal cliente.