Data Feeds

Panoramica #
Indipendentemente dalla tua piattaforma eCommerce e se abbiamo un’integrazione o meno, puoi sempre sincronizzare i dati con Clerk.io tramite uno o più feed in formato JSON.
Supportiamo due diverse varianti dei feed:
- File multipli per oggetti diversi
- Un singolo file contenente tutti gli oggetti
Le due soluzioni utilizzano la stessa struttura degli oggetti, ma hanno varie funzionalità disponibili per garantirne la sicurezza e l’importazione, che sono descritte in questa guida.
Tutti i tipi di oggetti eccetto gli ordini sono specchiati dai feed al database di Clerk.io. Se rimuovi un oggetto dal feed, Clerk.io lo rimuoverà dal database quando verrà importato. Gli ordini sono registrati e mantenuti nel database.
Consigliamo di generare il/ i feed JSON almeno una volta al giorno, ma idealmente più spesso. Possono anche essere generati su richiesta quando l’importatore di Clerk.io li richiede.
Il/i feed devono essere disponibili a un URL accessibile dai server di Clerk.io.
https://your-website.com/json-feed.json
Tipi di Dati #
Supportiamo attributi dei tipi: int
, float
, str
, array
, bool
.
Valori Nulli #
Valori null
non controllati sono un modo sicuro per far entrare errori nel tempo. Se un attributo non esiste per un dato prodotto, categoria o ordine, basta omettere l’attributo.
Tipi di Valore ID #
Consigliamo vivamente di utilizzare interi come ID, ma è possibile utilizzare anche stringhe. Devi sempre impegnarti a utilizzare 1 tipo nel tuo feed, il che significa che tutti gli ID per i tuoi oggetti devono essere dello stesso tipo.
Nomi degli Attributi #
Gli attributi degli oggetti possono contenere solo valori alfanumerici (A-Z, 0-9) e underscore.
Pertanto, un nome di attributo valido potrebbe essere brand_name
ma non läbel-mærke
.
L’uso di trattini o caratteri speciali nei nomi degli attributi farà sì che vengano ignorati nella sincronizzazione.
Struttura degli Oggetti #
I feed JSON consistono in un elenco di oggetti, con una serie di campi che compongono i loro dati.
Gli oggetti devono contenere come minimo i campi richiesti per il tipo affinché l’AI di Clerk.io funzioni correttamente e facoltativamente possono contenere qualsiasi attributo extra disponibile nella piattaforma eCommerce.
Prodotti #
Ogni oggetto rappresenta un singolo prodotto. Se hai prodotti configurabili, ti consigliamo di inviare solo il prodotto principale e includere attributi che descrivono i figli, come color
, size
, material
, ecc.
Di seguito puoi vedere i campi richiesti e esempi di quelli opzionali che sono spesso utilizzati dai negozi eCommerce.
Attributo | Importanza | Tipo | Descrizione |
---|---|---|---|
id | Richiesto | int/str | L’ID del prodotto, che dovrebbe essere unico per ogni prodotto |
name | Richiesto | str | Il nome del prodotto. |
description | Richiesto | str | La descrizione del prodotto. |
price | Richiesto | float | Il prezzo attuale di vendita del prodotto. |
list_price | Opzionale | float | Il prezzo di listino originale del prodotto. Utile per mostrare sconti. |
image | Richiesto | str | L’URL completo per l’immagine del prodotto. Quando utilizzato per le miniature, consigliamo una dimensione massima dell’immagine di 200x200px. |
url | Richiesto | str | L’URL del prodotto. |
categories | Richiesto | array | Un array di ID di categoria a cui appartiene il prodotto. |
created_at | Richiesto | int | Il timestamp UNIX di quando è stato creato il prodotto. |
brand | Opzionale | str | Il marchio del prodotto. |
color_names | Opzionale | array | Un array di nomi di colori per il prodotto. |
color_codes | Opzionale | array | Un array di codici colore per il prodotto. |
reviews_amount | Opzionale | int | Il numero di recensioni per il prodotto. |
reviews_avg | Opzionale | float | Il punteggio medio delle recensioni per il prodotto. |
Esempio JSON #
[
{
"id": 135,
"name": "Lightsaber",
"description": "Antique Rebel Lightsaber",
"price": 99995.95,
"image": "https://galactic-empire-merch.com/images/a-r-lightsaber.jpg",
"url": "https://galactic-empire-merch.com/antique-rebel-lightsaber",
"brand": "Je'daii",
"categories": [987, 654],
"created_at": 1199145600,
"color_names": ["Green","Red"],
"color_codes": ["#7CFC00","#FF3131"],
"reviews_amount": 164,
"reviews_avg": 4.8
},
{
"id": 261,
"name": "Death Star Deluxe",
"description": "Death Star - Guaranteed idiot proof",
"price": 99999999999999.95,
"image": "https://galactic-empire-merch.com/images/death-star.jpg",
"url": "https://galactic-empire-merch.com/death-star",
"brand": "Imperial Inc.",
"categories": [345678],
"created_at": 1197565600
}
]
Mantieni i Prodotti Senza Indicizzazione #
Per alcune configurazioni, potresti voler mantenere i prodotti nel database di Clerk.io senza mostrarli in alcun risultato.
Se vendi biglietti o articoli usati che saranno disponibili per un certo tempo prima di non tornare mai più, è una buona idea mantenere intatta la storia di questi prodotti, affinché Clerk possa utilizzarla per migliorare i risultati.
Per fare ciò, aggiungi l’attributo speciale index: false
agli oggetti prodotto che devono essere mantenuti senza essere indicizzati. Clerk utilizzerà quindi la storia delle loro vendite per mostrare i risultati, ma non verranno mai mostrati in alcuna chiamata API.
Per altri prodotti, basta omettere l’attributo o impostarlo su index: true
.
Categorie #
Ogni oggetto rappresenta una singola categoria. Clerk.io costruisce un albero di categorie interno basato sulle sottocategorie fornite per ogni categoria.
Di seguito puoi vedere i campi richiesti e esempi di quelli opzionali che sono spesso utilizzati dai negozi eCommerce.
Attributo | Importanza | Tipo | Descrizione |
---|---|---|---|
id | Richiesto | int/str | L’ID unico per la categoria. |
name | Richiesto | str | Il nome della categoria. |
url | Richiesto | str | L’URL della categoria. |
subcategories | Richiesto | array | Un array di ID di categoria che sono sottocategorie di questa categoria. Può essere un elenco vuoto per categorie senza sottocategorie. |
image | Opzionale | str | URL completo per l’immagine della categoria. |
description | Opzionale | str | La descrizione della categoria. |
Esempio JSON #
[
{
"id": 1,
"name": "Imperial Goods",
"subcategories": [42, 25],
"url": "https://galactic-empire-merch.com/imperial-goods"
},
{
"id": 42,
"name": "Tatooine",
"subcategories": [],
"url": "https://galactic-empire-merch.com/imperial-goods/tatooine"
},
{
"id": 25,
"name": "Coruscant",
"subcategories": [],
"url": "https://galactic-empire-merch.com/imperial-goods/coruscant"
}
]
Ordini #
Gli ordini sono registrati e non vengono eliminati quando rimossi dal feed. Devono generalmente essere inviati solo durante il primo import e possono poi essere rimossi di nuovo per risparmiare capacità del server. Possono essere eliminati tramite la nostra CRUD API.
I dati parcels
possono attualmente essere sincronizzati solo tramite CRUD API. Controlla la
documentazione qui.
Ogni oggetto rappresenta un singolo ordine. Clerk.io utilizza gli ID dei prodotti e l’indirizzo email/ID cliente all’interno degli ordini per analizzare il comportamento dei clienti e identificare tendenze. Insieme ai products
, è il tipo di oggetto più importante.
Di seguito puoi vedere i campi richiesti e i campi opzionali. Non è possibile inviare attributi aggiuntivi per gli ordini.
Attributo | Importanza | Tipo | Descrizione |
---|---|---|---|
id | Richiesto | int/str | L’ID dell’ordine, questo dovrebbe essere unico per ogni ordine. |
products | Richiesto | array | I prodotti nell’ordine. Ogni prodotto è un oggetto con un ID, quantità e prezzo unitario. |
time | Richiesto | unix timestamp | Il momento in cui è stato effettuato l’ordine come Timestamp Unix. |
customer | Opzionale | int/str | L’ID del cliente. |
email | Opzionale | str | L’email del cliente. Necessaria per utilizzare i nostri prodotti Auto-Email e Audience. |
Esempio JSON #
[
{
"id": 123458,
"customer": 789,
"email": "vader@the-death-star.com",
"products": [{"id":456,"quantity":1,"price":200.00}, {"id":789,"quantity":2,"price":120.00}],
"time": 1389871120
},
{
"id": 123456,
"customer": 456,
"email": "obi.wan@kenobi.me",
"products": [{"id":456,"quantity":1,"price":200.00}, {"id":789,"quantity":2,"price":120.00},{"id":123,"quantity":2,"price":60.00}],
"time": 1389870977
},
{
"id": 123457,
"customer": "",
"products": [{"id":789,"quantity":2,"price":120.00}],
"time": 1389871090
}
]
Clienti #
Ogni oggetto rappresenta un singolo Cliente. Gli attributi forniti vengono quindi fusi con l’email
o l’ID customer
dagli ordini per creare un unico profilo cliente da utilizzare con la segmentazione
Audience.
Di seguito puoi vedere i campi richiesti e esempi di quelli opzionali che sono spesso utilizzati dai negozi eCommerce.
Attributo | Importanza | Tipo | Descrizione |
---|---|---|---|
id | Richiesto | int/str | L’ID del cliente, questo dovrebbe essere unico per ogni cliente. |
name | Richiesto | str | Il nome completo del cliente. |
email | Richiesto | str | L’email del cliente. |
subscribed | Richiesto | bool | Booleano che indica se il cliente si è iscritto alle newsletter. Questo deve essere vero affinché Clerk.io possa inviare email di marketing a questo cliente. |
zip | Opzionale | str | Il codice postale del cliente. |
gender | Opzionale | str | Il genere del cliente |
age | Opzionale | int | L’età del cliente. |
is_b2b | Opzionale | bool | Booleano che indica se il cliente è un cliente aziendale. |
Esempio JSON #
[
{
"id": 135,
"name": "Luke Skywalker",
"email": "luke@rebels.com",
"subscribed": true,
"gender": "male",
"zip": "1134",
"is_b2b": "false"
},
{
"id": 165,
"name": "Leia Organa",
"email": "leia@royalty.org",
"subscribed": false,
"gender": "female",
"age": 19,
"interests": ["politics", "outlaws"],
"is_b2b": true
}
]
Pagine #
Ogni oggetto rappresenta una singola pagina. Le pagine sono generalmente tutti i tipi di contenuto eCommerce che non sono classificati come prodotto o categoria. Potrebbero essere articoli, post di blog, pagine di atterraggio, pagine di marca e altri tipi di contenuto scritto.
Di seguito puoi vedere i campi richiesti e esempi di quelli opzionali che sono spesso utilizzati dai negozi eCommerce.
Attributo | Importanza | Tipo | Descrizione |
---|---|---|---|
id | Richiesto | int/str | ID della pagina, questo dovrebbe essere unico per ogni pagina. |
type | Richiesto | str | Tipo del contenuto. Utilizzato per separare pagine come pagine CMS, post di blog e pagine di atterraggio. |
url | Richiesto | str | URL completo della pagina. |
title | Richiesto | str | Titolo della pagina. |
text | Richiesto | str | Corpo completo del testo per la pagina. |
image | Opzionale | str | L’URL completo per l’immagine della pagina. |
Esempio JSON #
[
{
"id": 135,
"type": "cms",
"url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
"title": "Orari di Apertura",
"text": "Il testo principale sui nostri orari di apertura..."
},
{
"id": 1354,
"type": "blog",
"url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
"title": "Nuovo Post del Blog",
"text": "Il testo principale sui nostri orari di apertura...",
"keywords": ["blog", "post", "nuovo"]
}
]
Multi-lingua #
Clerk.io funziona meglio quando crei negozi separati Stores per ogni lingua. Ogni Negozio può essere configurato con la lingua del contenuto, il che rende la ricerca in grado di comprendere molto meglio errori grammaticali e di ortografia.
Inoltre, i clienti di diverse regioni o paesi tendono ad avere preferenze e schemi di ricerca diversi, il che significa che funziona meglio separare i dati degli ordini in diversi Negozi.
Un’alternativa a questo è costruire feed JSON multi-lingua, dove tutti gli attributi di testo sono forniti come oggetti con codici lingua come chiavi e le loro traduzioni come valori.
Tutti gli attributi di testo devono avere chiavi di lingua anche se il contenuto al loro interno è lo stesso, per assicurarsi che siano ricercabili per la lingua.
Quando fai chiamate API, includi il parametro language
e la chiave di lingua corrispondente, per recuperare i dati corretti.
Esempio di JSON Multi-lingua #
[
{
"id": 135,
"name": {
"english":"Lightsaber",
"spanish":"Sable de luz",
"italian":"Spada laser"
},
"description": {
"english":"Antique Rebel Lightsaber",
"spanish":"Sable de luz rebelde antiguo",
"italian":"Antica spada laser ribelle"
},
"price": 99995.95,
"image": {
"english":"https://galactic-empire-merch.com/images/a-r-lightsaber.jpg",
"spanish":"https://galactic-empire-merch.com/es/images/a-r-lightsaber.jpg",
"italian":"https://galactic-empire-merch.com/it/images/a-r-lightsaber.jpg"
},
"url": {
"english":"https://galactic-empire-merch.com/antique-rebel-lightsaber",
"spanish":"https://galactic-empire-merch.com/es/antique-rebel-lightsaber",
"italian":"https://galactic-empire-merch.com/it/antique-rebel-lightsaber"
},
"brand": "Je'daii",
"categories": [987, 654],
"created_at": 1199145600,
"color_names": ["Green","Red"],
"color_codes": ["#7CFC00","#FF3131"],
"reviews_amount": 164,
"reviews_avg": 4.8
},
{
"id": 261,
"name": {
"english":"Death Star Deluxe",
"spanish":"Estrella de la Muerte de lujo",
"italian":"La Morte Nera Deluxe"
},
"description": {
"english":"Death Star - Guaranteed idiot proof",
"spanish":"Estrella de la Muerte: a prueba de idiotas garantizada",
"italian":"Morte Nera - A prova di idiota garantita"
},
"price": 99999999999999.95,
"image": {
"english":"https://galactic-empire-merch.com/images/death-star.jpg",
"spanish":"https://galactic-empire-merch.com/es/images/death-star.jpg",
"italian":"https://galactic-empire-merch.com/it/images/death-star.jpg"
},
"url": {
"english":"https://galactic-empire-merch.com/death-star",
"spanish":"https://galactic-empire-merch.com/es/death-star",
"italian":"https://galactic-empire-merch.com/it/death-star"
},
"brand": "Imperial Inc.",
"categories": [345678],
"created_at": 1197565600
}
]
Esempio di chiamata #
curl -X GET \
https://api.clerk.io/v2/recommendations/popular \
-H 'Content-Type: application/json' \
-d 'key=your_store_public_key&limit=10&language=italian'
Lingue Supportate #
La lingua deve essere specificata con il suo nome esatto. Se la tua lingua non è presente nell’elenco sottostante, scegli una lingua con la stessa radice, o semplicemente “english”. Funzionerà comunque, ma la neutralizzazione grammaticale nella ricerca sarà meno efficace.
- danese
- olandese
- inglese
- finlandese
- francese
- tedesco
- italiano
- norvegese
- portoghese
- russo
- spagnolo
- svedese
Feed Multipli #

Questo è l’approccio raccomandato poiché è efficiente per il tuo server e offre il massimo grado di controllo,
Con questo approccio, costruisci file di feed individuali per ciascuno dei tuoi oggetti. Questo utilizza il metodo di sincronizzazione chiamato Clerk.io JSON Feed V2.
Questi supportano content-type
: application/x-ndjson
o application/json
.
Ogni feed dovrebbe contenere un array di oggetti.
URL #
https://awsumstuff.com/feed/products.json
Output #
[
{
"id": 135,
"name": "Lightsaber",
"description": "Antique Rebel Lightsaber",
"price": 99995.95,
},
...
]
Paginazione #
Questa è una funzionalità opzionale che ti consente di paginare i risultati codificando il tuo feed per accettare i seguenti parametri di query:
limit
: Il numero di oggetti da restituire per pagina.offset
: L’indice del primo oggetto da restituire in una pagina.
L’importatore di Clerk.io può essere configurato per inviare questi parametri al tuo codice feed. Devi semplicemente selezionare la quantità di oggetti che desideri recuperare per pagina.
Quando configuri l’URL del tuo feed, puoi quindi utilizzare {{limit}}
e {{offset}}
per aggiungere i dati come parametri di query.
{{limit}}
conterrà il numero che configuri nelle impostazioni dell’importatore. {{offset}}
inizierà da 0 nella prima chiamata e crescerà continuamente in base al limit
.
Esempio:
- Chiamata 1:
limit=100&offset=0
- Chiamata 2:
limit=100&offset=100
- Chiamata 3:
limit=100&offset=200
La condizione di arresto è quando il tuo feed restituisce un array vuoto.
URL #
https://awsumstuff.com/feed/products.json?limit={{limit}}&offset={{offset}}
Incrementi #
Utilizzare questa funzionalità significa che Clerk.io smetterà di eliminare oggetti durante l’importazione, quindi è necessario utilizzare le chiamate CRUD API per rimuovere oggetti dal database di Clerk.io.
La soluzione multi-feed supporta la funzionalità opzionale di inviare solo i dati che sono cambiati da un numero scelto di giorni, piuttosto che inviare tutti i dati ogni volta.
Per fare ciò, inizia assicurandoti che il tuo feed sia configurato per restituire solo oggetti che sono stati modificati in un determinato numero di giorni, quando la richiesta include il parametro di query modified_after
.
Quindi, aggiungi un numero di giorni nel campo etichettato Incremental time {{modified_after}} trovato nelle impostazioni dell’importatore di Clerk.io.
Questo farà sì che l’importatore di Clerk.io mantenga tutti i dati nel database e aggiorni solo gli oggetti inclusi nei feed.
Per utilizzare il numero di giorni che hai configurato, aggiungi il parametro di query modified_after
al tuo feed e includi il tag che inserirà il numero di giorni che hai configurato. Ad esempio:
https://awsumstuff.com/feed/products.json?modified_after={{modified_after}}&limit={{limit}}&offset={{offset}}
Sicurezza #
Consigliamo che il feed JSON accetti solo una connessione crittografata SSL e utilizzi HTTP Authentication se possibile.
Inoltre, dalle impostazioni dell’importatore, puoi attivare Token Authentication. Clerk.io includerà quindi un header di autorizzazione su ogni richiesta HTTP, che devi verificare prima di restituire i dati:
X-Clerk-Authorization: Bearer THE_TOKEN
Puoi verificare il token con una richiesta POST all’endpoint token/verify:
curl -X POST \
https://api.clerk.io/v2/token/verify \
-H 'Content-Type: application/json' \
-d '{"token": "THE_TOKEN", "key": "your_store_public_key"}'
Feed Singolo #

Parametri #
Oltre agli oggetti stessi, questo approccio supporta due parametri aggiuntivi:
created
: Un timestamp unix di quando il feed è stato aggiornato per l’ultima volta. L’importatore di Clerk.io utilizza questo per identificare se i nuovi dati devono essere recuperati.strict
: Quandotrue
tutti i dati verranno importati così come sono. Quandofalse
Clerk.io tenterà di pulire i dati, ad esempio rimuovendo prodotti o categorie duplicati e convertendo numeri in formato stringa in interi o float.
Esempio di Feed #
{
"products": [ ... ],
"categories": [ ... ],
"orders": [ ... ],
"customers": [ ... ],
"pages": [ ... ],
"config": {
"created": 1567069830,
"strict": false
}
}
Sicurezza #
I tuoi dati sono estremamente sensibili per il business, quindi la sicurezza è di massima priorità!
Consigliamo che il feed JSON accetti solo una connessione crittografata SSL e utilizzi HTTP Authentication se possibile.
Inoltre, Clerk fornisce un ulteriore livello di sicurezza consentendoti di verificare che la richiesta del feed provenga da una fonte fidata (cioè noi).
Il sistema si basa su un segreto condiviso; una chiave API privata che può essere creata in my.clerk.io sotto Settings > API Keys.
Tutte le richieste Clerk.io tramite HTTP o HTTPS includono due parametri di query hash
e salt
.
salt
è semplicemente una stringa casuale utilizzata per salare la funzione hash mentre hash
è un hash SHA512 calcolato dalla chiave API privata nel seguente modo:
hash = SHA512(salt + private_key + str(int(floor(unix_timestamp() / 100))))
Un esempio di richiesta potrebbe essere il seguente URL:
https://example.com/clerk-product-feed.php?salt=f4Ke...A02X&hash=4DFF...340F
Recuperando sia i parametri salt
che hash
dalla richiesta, puoi fare lo stesso calcolo sul tuo server e confrontare i valori hash
per confermare che siano gli stessi, il che significa che la richiesta proviene da Clerk.io.
Questa pagina è stata tradotta da un'utile intelligenza artificiale, quindi potrebbero esserci errori linguistici. Grazie per la comprensione.