Catalog API

The Catalog API allows clients to send and update their catalog data using CSV, XML or JSON format. Clients can specify the type of update (FULL or DELTA) and provide their catalog information accordingly. The API endpoint expects a POST request with the catalog data and necessary parameters.

Endpoint

POST http://rs1.epoq.de/inbound-servletapi/update-catalog

Parameters

• tenantId (required): The client ID.
• format (required): Specifies the data format being used. Possible values are:
  • XML
  • CSV
  • JSON
• type (required): The type of catalog update. Possible values are:
  • FULL
  • DELTA
• updateID (optional): If FULL updates are split into multiple parts, they must share the same updateID. These should be numbered sequentially, and later updates must have a higher number.
• lastBatch (optional): Indicates that a full update was completely delivered.

Request Headers

• Authorization: A bearer token for authentication. (The token must be requested from epoq to be able to use the Catalog API)
• Content-Type: The format of the catalog data. Supported formats are:
  • application/csv
  • application/xml
  • application/json

Request Body

The request body should contain the catalog data in either CSV, XML, or JSON format.

CSV Format

The CSV should contain all available (and relevant for epoq) attributes of a product (see catalog format documentation for more detail).

You should use a correct separator char (e.g. “,”), end-of-line sequence (e.g. “\n”) and optionally you can use a quote char (e.g. ‘”’).

Example:

"productId","name","productUrl","price","smallImage","description","category","brand","variantOf","recommendable","quantity"
"12345","ExampleProduct","https://example.com/product","19.99","https://example.com/image.jpg","Lorem ipsum dolor sit amet, consectetur adipiscing elit.","Electronics","Example Brand","12345-a","true","10"

JSON Format

The request body should be a JSON document with the following structure:

[
    {
        "productId": "12345",
        "name": "Example Product",
        "productUrl": "https://example.com/product",
        "price": 19.99,
        "smallImage": "https://example.com/image.jpg",
        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
        "category": "Electronics",
        "brand": "Example Brand",
        "variantOf": "12345-a",
        "recommendable": true,
        "quantity": 10
    },
    {...},
    {...}
]

XML Format

The request body should be a XML document with the following structure:

<items>
    <item>
        <g:id>12345</g:id>
        <title>Example Product</title>
        <link>http://example.com/product</link>
        <g:price>19.99</g:price>
        <g:image_link>https://example.com/image.jpg</g:image_link>
        <description>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</description>
        <g:product_type>Electronics</g:product_type>
        <g:brand>Example Brand</g:brand>
        <e:variant_of>12345-a</e:variant_of>
        <e:recommendable>true</e:recommendable>
        <g:quantity>10</g:quantity>
    </item>
    <!-- Add more <item> elements here as needed -->
</items>

Example Request

curl -X POST \
    'http://rs1.epoq.de/inbound-servletapi/update-catalog?tenantId=TENANTID-com&format=csv&type=FULL' \
    -H 'Authorization: Bearer NT***=' \
    -H 'Content-Type: application/csv' \
    -T 'catalog.csv'

Response

• 200 OK: The catalog update was successful.
• Other HTTP status codes may be returned for different error scenarios.

Notes

• Make sure to replace the bearer token with the appropriate authentication token.
• Ensure that the CSV, XML or JSON data provided adheres to the specified format and column requirements.
• The tenantId parameter should be replaced with the client’s unique identifier.
• Choose the appropriate type parameter value based on the type of catalog update required.

Item Deletion

To delete items from the catalog, deliver a DELTA update containing the productId of the item to be removed and the attribute “e:is_deleted” with the value “1” in the update.
This marks the item for deletion in the catalog.

Example JSON line for deletion:

{
    "g:id": "12345",
    "e:is_deleted": "1"
}