Data Feeds

Introduzione #

Questa guida spiega come impostare i feed JSON per sincronizzare i dati con Clerk.io.

> Se si utilizza uno dei nostri piattaforma supportata, non è necessario impostare un feed JSON.

Il nostro vecchio Feed JSON è ancora supportato, ma si consiglia di utilizzare il nuovo Feed JSON per le nuove integrazioni.

Il nuovo Feed JSON rende più semplice ed efficiente la sincronizzazione dei dati con Clerk.io.

Ciò avviene grazie alla possibilità di sincronizzare i dati in file/endpoint separati.

E supporta la paginazione e gli aggiornamenti incrementali per i set di dati di grandi dimensioni.

Impostazione #

Per iniziare, accedere a my.clerk.io e fare clic su “Data” nel menu di sinistra.

Scorrere fino a “Impostazioni di sincronizzazione dei dati” e scegliere “Clerk.io JSON Feed V2” dal menu a tendina “Metodo di sincronizzazione” nell’angolo in alto a destra.

Inserire gli URL dei feed JSON per i prodotti, le categorie, gli ordini, i clienti e le pagine in Impostazioni di sincronizzazione dei dati. Vedi qui per sapere come organizzare i feed JSON per ciascuna entità.

Supportiamo content-type: application/x-ndjson o application/json.

Sicurezza #

> ⚠️ Il vostro deve essere mantenuto sicuro, quindi gli endpoint che implementate devono richiedere l’autenticazione prima di essere distribuiti! > > Per questo motivo, l’HTTPS è forzato su tutti gli URL.

Si raccomanda che il feed JSON accetti solo una connessione crittografata SSL e che utilizzi l’autenticazione HTTP, se possibile.

Quando si interroga l’endpoint, la piattaforma Clerk invia un’intestazione di autorizzazione a ogni richiesta HTTP, che deve essere verificata:

X-Clerk-Authorization : Bearer THE_TOKEN

È possibile verificare il token con una richiesta POST all’endpoint token/verify https://api.clerk.io/v2/token/verify:

{ "token": "THE_TOKEN", "key": "your_store_public_key"}

Vedere il nostro documentazione api per maggiori dettagli

Aggiornamenti incrementali #

> I prodotti, le categorie, i clienti e le pagine vengono eliminati se non presenti_ nel feed JSON. Utilizzare il parametro di query modified_after per abilitare gli aggiornamenti incrementali e mantenere i dati esistenti che non sono stati modificati. Vedi sotto

> Gli ordini vengono sempre mantenuti.

Per impostazione predefinita, Clerk.io cancella i prodotti, le categorie, i clienti e le pagine non presenti nel feed JSON. Quando si hanno grandi insiemi di dati, questo può essere un problema, in quanto può essere necessario molto tempo per sincronizzare tutti i dati. In questo caso, è possibile inviare solo i dati che sono stati modificati dopo una certa data, utilizzando il parametro modified_after. Vedi sotto

Gli ordini vengono sempre conservati. Questi possono essere cancellati inviando una richiesta di DELETE all’indirizzo punto finale ordini.

Parametri della query #

Per supportare la paginazione e gli aggiornamenti incrementali per grandi insiemi di dati, sono supportati i seguenti parametri di query:

limit={{limit}}
offset={{offset}}
modified_after={{modified_after}}

Dimensione di paginazione con {{limit}} e {{offset}} #

Il parametro di query limit può essere usato per limitare la quantità di entità restituite in ogni richiesta. Il valore predefinito è 25 e il valore massimo è 1000.

Quando si utilizza il parametro di query limit, è necessario utilizzare anche il parametro di query offset. Aumentando il parametro offset con il parametro limit fino a quando non vengono restituiti più dati, restituendo un array vuoto o una risposta vuota.

Utilizzando il parametro di query modified_after #

> funziona solo se {{modified_after}} è presente nell’URL e un valore in Incremental Time.

Per conservare i dati esistenti, si può usare il parametro di query modified_after.

{{modified_after}} deve essere presente nell’URL e un valore in Incremental Time in Impostazioni di sincronizzazione dei dati perché abbia effetto.

Questo ha effetto solo su ogni singolo URL, quindi se si hanno più URL, è necessario aggiungere {{modified_after}} a ogni URL.

Per eliminare i prodotti, le categorie, i clienti e le pagine che non sono presenti nel feed JSON, è possibile inviare una richiesta DELETE agli URL endpoint prodotti, endpoint categorie, endpoint clienti e endpoint pagine.

Struttura del feed JSON #

> Supportiamo solo gli attributi dei tipi: int, float, str, array e bool.

Ogni feed JSON deve essere un array di oggetti, dove ogni oggetto rappresenta una singola entità (prodotto, categoria, ordine, cliente o pagina). Gli oggetti nell’URL Prodotti devono rappresentare i prodotti, gli oggetti nell’URL Categorie devono rappresentare le categorie, ecc.

Ogni oggetto deve contenere i campi obbligatori per il tipo di entità e può contenere facoltativamente qualsiasi attributo extra.

I campi obbligatori sono contrassegnati da un * nelle tabelle seguenti.__ | int/str | L’ID del prodotto, che deve essere unico per ogni prodotto name |** | str | La descrizione del prodotto. price |__### Prodotti*__ | str | L’URL completo dell’immagine del prodotto. Se utilizzata per le miniature, si consiglia una dimensione massima dell’immagine di 200x200px. url |** | array | Un array di ID di categoria a cui il prodotto appartiene. created_at |Il feed JSON per i prodotti deve essere un array di oggetti, dove ogni oggetto rappresenta un singolo prodotto. | int/str | L’ID della categoria, che deve essere unico per ogni categoria. name |** | str | L’URL della categoria. subcategories |Tabella dei campi obbligatori e alcuni esempi di campi opzionali per un oggetto prodotto: | int/str | L’ID dell’ordine, che deve essere unico per ogni ordine. products |** | unix timestamp | L’ora in cui l’ordine è stato effettuato come Unix Timestamp. customer | | int/str | L’ID del cliente. email | | str | L’e-mail del cliente. Necessario per utilizzare i prodotti Auto-Email e Audience.

Esempio di feed JSON per gli ordini #

[
  {
    "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 #

Il feed JSON per i clienti deve essere un array di oggetti, dove ogni oggetto rappresenta un singolo cliente.

Tabella dei campi obbligatori e alcuni esempi di campi opzionali per un oggetto cliente:

Esempio di feed JSON per i clienti #

[
  {
    "id": 135,
    "name": "Luke Skywalker",
    "email": "luke@rebels.org",
    "subscribed": true,
    "gender": "male",
    "zip": "1134",
    "is_b2b": "false"
  },
  {
    "id": 165,
    "name": "Darth Vader",
    "email": "vader@empire.com",
    "subscribed": false,
    "gender": "male",
    "age": 45,
    "interests": ["lightsaber", "force"],
    "is_b2b": true
  }
]

Pagine #

Il feed JSON per le Pagine deve essere un array di oggetti, dove ogni oggetto rappresenta una singola pagina.

Tabella dei campi obbligatori e alcuni esempi di campi opzionali per un oggetto pagina:

Esempio di feed JSON per le pagine #

[
  {
    "id": 135,
    "type": "cms",
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
    "title": "Open Hours",
    "text": "The main text about our opening hours..."
  },
  {
    "id": 1354,
    "type": "blog",
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
    "title": "New Blog Post",
    "text": "The main text about our opening hours...",
    "keywords": ["blog", "post", "new"]
  }
]

Feed multilingue #

>Si prega di notare che il feed multilingue non è generalmente raccomandato. Non supportiamo tutte le funzioni, ad esempio l’importazione delle pagine. In genere non lo consigliamo per la facilità con cui è possibile incasinare l’indicizzazione se i requisiti non sono soddisfatti.

Esempio di feed JSON per i prodotti #

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