Introduction

This document contains the specs for the REST endpoints used by Delivery Hero's Catalog application to import the vendor product information from CSV files.

Login

This endpoint is used to authenticate the user with the catalog and get the access token. [POST] https://example.com/api/auth

Request Example:

curl --location --request POST "http://localhost:8080/api/auth" \
  --header "Content-Type: application/json" \
  --data "{
    \"email\" : \"test@test.com\",
    \"password\" : \"changeit\"
}"

Response Example:

  • Success:
{
    "token": "<JWT TOKEN>"
}
  • Failure:
{
    "error": "Unauthorized",
    "message": "Invalid email or password",
    "statusCode": 401
}

Import Vendor Products

This endpoint can be used to upload the file containing the vendor products to the Delivery Hub catalog. [POST] https://example.com/api/v1/import

The header should contian the jwt token returned by the auth endpoint:

Parameters
Authorization Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIU...

Body

The endpoint expects form-data in the body with the following form fields:

Parameters
file (required, File) this contains the file that we want to import data from
platform (required, Integer) The ID of the platform for which we are importing the data, this ID is internal in the catalog and should be agreed on with the catalog team during the setup.
vendor (required, Integer) The ID of the vendor (Supermarket) for which we are importing the data. This ID is the one used by the platform.
configuration (required, String) A keyword that is agreed on with the catalog team, which refers to the expected format of the CSV file.
locale (required, String) A keyword that refers to the locale of the data inside the file being imported.

Request Example:

curl --location --request POST "http://localhost:8080/api/v1/import" \
  --header "Authorization: Bearer <JWT TOKEN>" \
  --form "file=@/path/to/file" \
  --form "platform=1" \
  --form "vendor=3" \
  --form "configuration=talabat" \
  --form "locale=es_UY"

Response

The response in case of success should be http 200 with the body containing a summary of the changes

Parameters Value
state Indicates if the item is new or if it was already existing, possible values are: new, changed, unchanged, error
message This is set only in case the state is error, it explains why the error happened
sku The product SKU as it was read from the file
title The product title as it was read from the file
imageUrl Image URL read from the file
price The price of the product as it was in the file
category The product category read from the file
available Indicates if the product was marked as available or not, the product is marked as available if the quantity is greater than 0
Response Example:
  • Success
{
    "results": [
        {
            "state": "new",
            "message": "",
            "sku": "7808725800164",
            "title": "PRODUCT NAME 1",
            "imageUrl": "http://www.example.com/path/to/image1",
            "price": 7190,
            "category": "OILS AND VINEGARS",
            "available": false
        },
        {
            "state": "new",
            "message": "",
            "sku": "2000407713969",
            "title": "PRODUCT NAME 2",
            "imageUrl": "http://www.example.com/path/to/image2",
            "price": 4490,
            "category": "OILS AND VINEGARS",
            "available": false
        }
    ]
}
  • Failure (Access Denied)
{
    "timestamp": "2019-03-22T12:44:09.880+0000",
    "status": 403,
    "error": "Forbidden",
    "message": "Access Denied",
    "path": "/api/v1/import"
}
  • Failure (Bad Request)
{
    "error": "Bad Request.",
    "message": "Vendor with id 33 was not found.",
    "statusCode": 400
}

CSV format mapping

Before starting to upload your CSV files to the Catalog application, we need to create a configuration on the catalog that contains information about how to read those CSV files. For example, we need to define which columns in the CSV file map to which fields in our Data Structure. We also need to define general charactaristics of the CSV file like the field separator, the character encoding and other fields. This is done by the Catalog team once before starting those integrations, and the result is a configuration which will be given a name that should be used in the configuration field in the import endpoint.