clerk.io

Einleitung #

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

> Wenn Sie eine unserer unterstützten Plattformen verwenden, müssen Sie keinen JSON-Feed einrichten.

Unser älterer JSON Feed wird immer noch 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.

Data Sync Settings panel for JSON Feed V2

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 Sync Method Dropdown 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 ein. Sehen Sie hier, wie Sie die JSON-Feeds für jede Entität organisieren können.

Wir unterstützen den Inhaltstyp: application/x-ndjson oder application/json.

Sicherheit #

> ⚠️ Sie müssen sicher 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 Clerk-Plattform bei jeder HTTP-Anfrage einen Autorisierungs-Header, den Sie überprüfen müssen:

X-Clerk-Authorization : Bearer THE_TOKEN

You can verify the token with a POST request to the token/verify endpoint https://api.clerk.io/v2/token/verify:

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

See our api documentation for more details

Incremental Updates #

Products, Categories, Customers and Pages are deleted if not present in the JSON Feed. Use the modified_after query parameter to enable incremental updates and keep existing data that has not been modified. See Below

Orders are always retained

By default Clerk.io will delete Products, Categories, Customers and Pages that are not present in the JSON Feed.
When having big data sets, this can be a problem, as it can take a long time to sync all data.
In this case, you can send only the data that has bene modified after a given date, which can be done by using the modified_after query parameter. See Below

Orders are always retained. These can be deleted by sending a DELETE request to the orders endpoint.

Query Parameters #

To support pagination and incremental updates for large data sets, we support the following query parameters:

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

Paging size with `{{limit}}` and `{{offset}}` #

The limit query parameter can be used to limit the amount of entities returned in each request.
The default value is 25 and the maximum value is 1000.\

When using the limit query parameter, you must also use the offset query parameter.
As we increase the offset by the limit until no more data is returned, either by returning an empty array or by an empty response.

Using the `modified_after` query parameter #

Retaining only works if {{modified_after}} is present in the URL and a value in Incremental Time.

To retain existing data, you can use the modified_after query parameter.

{{modified_after}} needs to be present in the URL as well as a value in Incremental Time in Data Sync Settings for this to take effect.

This only effects each URL individually, so if you have multiple URLs, you need to add {{modified_after}} to each URL.

To delete Products, Categories, Customers and Pages that are not present in the JSON Feed, you can send a DELETE request to the products endpoint, categories endpoint, customers endpoint and pages endpoint.

JSON Feed Structure #

We only support attributes of the types: int, float, str, array and bool.

Each JSON Feed should be an array of objects, where each object represents a single entity (product, category, order, customer or page). Objects in the Products URL should represent products, objects in the Categories URL should represent categories, etc.

Each object must contain the mandatory fields for the entity type, and can optionally contain any extra attributes.

Mandatory fields are marked with a * in the tables below.

Products #

The JSON Feed for products should be an array of objects, where each object represents a single product.

Table of mandatory and some examples of optional fields for a product object:

Attribute	Required	Type	Description
`id`	*	int/str	The product ID, which should be unique for each product
`name`	*	str	The product name.
`description`	*	str	The product description.
`price`	*	float	The product current selling price.
`list_price`		float	The product original list price. Useful to show discounts.
`image`	*	str	The full URL for the product image. When used for thumbnails we recommend a maximum image size of 200x200px.
`url`	*	str	The product URL.
`categories`	*	array	An array of category IDs that the product belongs to.
`created_at`	*	int	The UNIX timestamp of when the product was created.
`brand`		str	The product brand.
`color_names`		array	An array of color names for the product.
`color_codes`		array	An array of color codes for the product.
`reviews_amount`		int	The amount of reviews for the product.
`reviews_avg`		float	The average review score for the product.

Example JSON Feed for products #

[
  {
    "id": 135,
    "name": "Lichtschwert",
    "description": "Antikes Rebellen-Lichtschwert",
    "Preis": 99995.95,
    "image": "https://galactic-empire-merch.com/images/a-r-lightsaber.jpg",
    "url": "https://galactic-empire-merch.com/antique-rebel-lightsaber",
    "Marke": "Je'daii",
    "Kategorien": [987, 654],
    "created_at": 1199145600,
    "color_names": ["Grün", "Rot"],
    "color_codes": ["#7CFC00","#FF3131"],
    "reviews_amount": 164,
    "reviews_avg": 4.8
  },
  {
    "id": 261,
    "name": "Todesstern Deluxe",
    "description": "Todesstern - Garantiert idiotensicher",
    "Preis": 99999999999999.95,
    "image": "https://galactic-empire-merch.com/images/death-star.jpg",
    "url": "https://galactic-empire-merch.com/death-star",
    "Marke": "Imperial Inc.",
    "Kategorien": [345678],
    "created_at": 1197565600
  }
]

Categories #

The JSON Feed for Categories should be an array of objects, where each object represents a single category.

Table of mandatory and some examples of optional fields for a category object:

Attribute		Type	Description
`id`	*	int/str	The category ID, this should be unique for each category.
`name`	*	str	The category name.
`url`	*	str	The category URL.
`subcategories`	*	array	An array of category IDs that are subcategories of this category.
`image`		str	The full URL for the category image.
`description`		str	The category description.

Example JSON Feed for Categories #

[
  {
    "id": 1,
    "name": "Kaiserliche Waren",
    "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"
  }
]

Orders #

Orders are stored as a log and thus never deleted. If you want to delete an order, you can do so by sending a DELETE request to the orders endpoint.

The JSON Feed for Orders should be an array of objects, where each object represents a single order.

Table of mandatory and some examples of optional fields for a order object:

Example JSON Feed for Orders #

[
  {
    "id": 123458,
    "kunde": 789,
    "email": "vader@the-death-star.com",
    "produkte": [{"id":456,"quantity":1,"price":200.00}, {"id":789,"quantity":2,"price":120.00}],
    "time": 1389871120
  },
  {
    "id": 123456,
    "Kunde": 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,
    "Kunde": "",
    "products": [{"id":789,"quantity":2,"price":120.00}],
    "time": 1389871090
  }
]

Customers #

The JSON Feed for Customers should be an array of objects, where each object represents a single customer.

Table of mandatory and some examples of optional fields for a customer object:

Attribute		Type	Description
`id`	*	int/str	The customer ID, this should be unique for each customer.
`name`	*	str	The customers full name.
`email`	*	str	The customer email.
`subscribed`	*	bool	Boolean indicating whether the customer has subscribed to newsletters. This must be true for Clerk.io to send marketing emails to this customer.
`zip`		str	The customers zip code.
`gender`		str	The customers gender
`age`		int	The customers age.
`is_b2b`		bool	Boolean indicating whether the customer is a business customer.

Example JSON Feed for Customers #

[
  {
    "id": 135,
    "name": "Luke Skywalker",
    "email": "luke@rebels.org",
    "abonniert": wahr,
    "Geschlecht": "männlich",
    "zip": "1134",
    "is_b2b": "false"
  },
  {
    "id": 165,
    "name": "Darth Vader",
    "email": "vader@empire.com",
    "abonniert": falsch,
    "Geschlecht": "männlich",
    "Alter": 45,
    "Interessen": ["Lichtschwert", "Macht"],
    "is_b2b": true
  }
]

Pages #

The JSON Feed for Pages should be an array of objects, where each object represents a single page.

Table of mandatory and some examples of optional fields for a page object:

Attribute		Type	Description
`id`	*	int/str	The page ID, this should be unique for each page.
`type`	*	str	The type of the content. Used to separate different types of pages such as CMP pages, blog posts and landing pages.`custom`.
`url`	*	str	The URL of the content.
`title`	*	str	The title of the content.
`text`	*	str	The text of the content.
`image`		str	The full URL for the content image.

Example JSON Feed for Pages #

[
  {
    "id": 135,
    "type": "cms",
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
    "title": "Open Hours",
    "text": "Der Haupttext über unsere Öffnungszeiten..."
  },
  {
    "id": 1354,
    "type": "blog",
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
    "title": "Neuer Blogbeitrag",
    "text": "Der Haupttext über unsere Öffnungszeiten...",
    "keywords": ["blog", "post", "new"]
  }
]

Multi-language feed #

Please note that multi-language feed is not generally recommended. We do not support all features e.g. Pages import. We do not generally advice this due to how easy it is to mess up the indexation if the requirements are not met.

Example JSON Feed for products #

[
  {
    "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",
    "kategorien": [987, 654],
    "created_at": 1199145600,
    "color_names": ["Grün", "Rot"],
    "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"},
    "Marke": "Imperial Inc.",
    "categories": [345678],
    "created_at": 1197565600
  }
]

Data Feeds

Einleitung #

Einrichtung #

Sicherheit #

Incremental Updates #

Query Parameters #

Paging size with {{limit}} and {{offset}} #

Using the modified_after query parameter #

JSON Feed Structure #

Products #

Example JSON Feed for products #

Categories #

Example JSON Feed for Categories #

Orders #

Example JSON Feed for Orders #

Customers #

Example JSON Feed for Customers #

Pages #

Example JSON Feed for Pages #

Multi-language feed #

Example JSON Feed for products #

Paging size with `{{limit}}` and `{{offset}}` #

Using the `modified_after` query parameter #