Data Feeds

Einleitung #

Diese Anleitung erklärt, wie Sie Ihre JSON-Feeds einrichten, um Ihre Daten mit Clerk.io zu synchronisieren.

> Wenn Sie einen unserer Unterstützte Plattform verwenden, brauchen Sie keinen JSON-Feed einzurichten.

Unser älterer JSON Feed wird weiterhin unterstützt, aber wir empfehlen die Verwendung des neuen JSON Feeds für neue Integrationen.

Der neue JSON Feed macht es einfacher und effizienter für Sie, Ihre Daten mit Clerk.io zu synchronisieren.

Dies geschieht durch die Möglichkeit, Ihre Daten in separaten Dateien/Endpunkten zu synchronisieren.

Außerdem werden Paginierung und inkrementelle Updates für große Datensätze unterstützt.

Einrichtung #

Um loszulegen, gehen Sie zu my.clerk.io und klicken Sie auf “Daten” im Menü auf der linken Seite.

Scrollen Sie nach unten zu “Data Sync Settings” und wählen Sie “Clerk.io JSON Feed V2” aus dem Dropdown-Menü Sync Method in der oberen rechten Ecke.

Fügen Sie die URLs für Ihre JSON-Feeds für Ihre Produkte, Kategorien, Bestellungen, Kunden und Seiten in Data Sync Settings.
Siehe hier ein, wie Sie die JSON-Feeds für jede Entität organisieren können.

Wir unterstützen content-type: application/x-ndjson oder application/json.

Sicherheit #

> ⚠️ Ihre Sicherheit muss gewährleistet sein, daher müssen die von Ihnen implementierten Endpunkte eine Authentifizierung erfordern, bevor sie eingesetzt werden! > > Aus diesem Grund wird HTTPS für alle URLs erzwungen.

Wir empfehlen, dass der JSON-Feed nur eine SSL-verschlüsselte Verbindung akzeptiert und wenn möglich HTTP-Authentifizierung verwendet.

Bei der Abfrage Ihres Endpunkts sendet die Plattform Clerk bei jeder HTTP-Anfrage einen Autorisierungs-Header, den Sie überprüfen müssen:

X-Clerk-Authorization : Bearer THE_TOKEN

Sie können das Token mit einer POST-Anfrage an den Endpunkt token/verify https://api.clerk.io/v2/token/verify verifizieren:

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

Weitere Einzelheiten finden Sie auf unserer Website api-Dokumentation

Inkrementelle Updates #

> Produkte, Kategorien, Kunden und Seiten werden gelöscht, wenn sie im JSON-Feed nicht vorhanden sind. Verwenden Sie den Abfrageparameter modified_after, um inkrementelle Updates zu aktivieren und bestehende Daten, die nicht geändert wurden, beizubehalten. Siehe Unten

> Bestellungen werden immer beibehalten

Standardmäßig löscht Clerk.io Produkte, Kategorien, Kunden und Seiten, die nicht im JSON-Feed vorhanden sind. Bei großen Datenmengen kann dies ein Problem sein, da es lange dauern kann, alle Daten zu synchronisieren.
In diesem Fall können Sie nur die Daten senden, die nach einem bestimmten Datum geändert wurden, was mit dem Abfrageparameter modified_after möglich ist. Siehe Unten

Aufträge werden immer beibehalten. Sie können gelöscht werden, indem Sie eine DELETE-Anfrage an die Endpunkt Bestellungen senden.

Abfrageparameter #

Um Paginierung und inkrementelle Updates für große Datensätze zu unterstützen, werden die folgenden Abfrageparameter unterstützt:

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

Paging-Größe mit {{limit}} und {{offset}} #

Der Abfrageparameter limit kann verwendet werden, um die Anzahl der Entitäten zu begrenzen, die bei jeder Anfrage zurückgegeben werden.
Der Standardwert ist 25 und der Höchstwert ist 1000.\

Wenn Sie den Abfrageparameter limit verwenden, müssen Sie auch den Abfrageparameter offset verwenden.
Wir erhöhen den offset um den limit, bis keine Daten mehr zurückgegeben werden, entweder durch Rückgabe eines leeren Arrays oder durch eine leere Antwort.

Verwendung des modified_after Abfrageparameters #

> Das Zurückhalten funktioniert nur, wenn {{modified_after}} in der URL und ein Wert in Incremental Time vorhanden ist.

Um vorhandene Daten beizubehalten, können Sie den Abfrageparameter modified_after verwenden.

{{modified_after}} {{modified_after}} muss in der URL vorhanden sein sowie ein Wert in Incremental Time in Data Sync Settings, damit dies wirksam wird.

Dies wirkt sich nur auf jede URL einzeln aus. Wenn Sie also mehrere URLs haben, müssen Sie {{modified_after}} zu jeder URL hinzufügen.

Um Produkte, Kategorien, Kunden und Seiten zu löschen, die nicht im JSON-Feed vorhanden sind, können Sie eine DELETE-Anfrage an die URLs Produkte Endpunkt, Kategorien Endpunkt, Endpunkt Kunden und Seiten Endpunkt senden.

JSON-Feed-Struktur #

> Wir unterstützen nur Attribute der Typen: int, float, str, array und bool.

Jeder JSON-Feed sollte ein Array von Objekten sein, wobei jedes Objekt eine einzelne Entität darstellt (Produkt, Kategorie, Bestellung, Kunde oder Seite). Die Objekte in der URL “Products” sollten Produkte darstellen, die Objekte in der URL “Categories” sollten Kategorien darstellen, usw.

Jedes Objekt muss die Pflichtfelder für den Entitätstyp enthalten und kann optional zusätzliche Attribute enthalten.

Pflichtfelder sind mit einem * in den unten stehenden Tabellen.__ | int/str | Die Produkt-ID, die für jedes Produkt eindeutig sein sollte, gekennzeichnet name |** | str | Die Produktbeschreibung. price |__### Produkte*__ | str | Die vollständige URL für das Produktbild. Bei der Verwendung für Thumbnails empfehlen wir eine maximale Bildgröße von 200x200px. url |** | array | Ein Array von Kategorie-IDs, zu denen das Produkt gehört. created_at |Der JSON-Feed für Produkte sollte ein Array von Objekten sein, wobei jedes Objekt ein einzelnes Produkt darstellt. | int/str | Die Kategorie-ID, die für jede Kategorie eindeutig sein sollte. name |** | str | Die Kategorie-URL. subcategories |Tabelle der obligatorischen und einiger Beispiele für optionale Felder für ein Produktobjekt: | int/str | Die Bestell-ID, die für jede Bestellung eindeutig sein sollte. products |** | unix timestamp | Der Zeitpunkt der Bestellung als Unix-Zeitstempel. customer | | int/str | Die Kunden-ID. email | | str | Die Kunden-E-Mail. Wird für die Verwendung unserer Produkte Auto-Email und Audience benötigt.

Beispiel JSON-Feed für Bestellungen #

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

Kunden #

Der JSON-Feed für Kunden sollte ein Array von Objekten sein, wobei jedes Objekt einen einzelnen Kunden darstellt.

Tabelle der obligatorischen und einiger Beispiele für optionale Felder für ein Kundenobjekt:

Beispiel JSON-Feed für Kunden #

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

Seiten #

Der JSON-Feed für Seiten sollte ein Array von Objekten sein, wobei jedes Objekt eine einzelne Seite darstellt.

Tabelle der obligatorischen und einiger Beispiele für optionale Felder für ein Seitenobjekt:

Beispiel JSON-Feed für Seiten #

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

Mehrsprachiger Feed #

>Bitte beachten Sie, dass ein mehrsprachiger Feed nicht generell empfohlen wird. Wir unterstützen nicht alle Funktionen, z.B. den Seitenimport. Wir raten generell davon ab, da die Indexierung leicht durcheinander gebracht werden kann, wenn die Anforderungen nicht erfüllt sind.

Beispiel JSON-Feed für Produkte #

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