Topsort Reference Catalog API (1.0.0)

Download OpenAPI specification:Download

Integration for Marketplaces' catalog queries

Catalog

Integration for Marketplaces' catalog queries.

Health Check

Responses
200

The service is up and ready to accept requests.

get/
Request samples
import fetch from 'node-fetch';

async function run() {
  const marketplaceDomain = 'demo.topsort.com/topsort/api';
  const resp = await fetch(
    `https://${marketplaceDomain}/`,
    {method: 'GET'}
  );

  const data = await resp.text();
  console.log(data);
}

run();

Retrieves products by IDs

SecurityBearerAuth
Request
Request Body schema: application/json

An array of product IDs.

Array ([ 0 .. 50 ] items)
string non-empty
Responses
200

Returns the products' details, if available.

401

Credentials are missing or invalid.

post/products
Request samples
application/json
[
  • "eyGqR4YQgBJa",
  • "KHqzavLNS25n",
  • "wJLZ4TCNZtEW"
]
Response samples
application/json
[]

Searches products

SecurityBearerAuth
Request
query Parameters
search
required
string

The search string provided by the user. When a blank string is provided, the string should match all products (e.g. all products with a given category ID).

Example: search=delirium tremens
vendorID
string non-empty

Vendor unique identifier. This identifier is given by the marketplace and allows this service to match the vendor with the proper products.

Example: vendorID=9SiwYqqL8vdG
categoryID
string non-empty

Only retrieve products whose category matches the provided ID.

Example: categoryID=ahEDqV5uhjj8
next
string non-empty

The string identifying the requested page. In case this parameter is missing then the first page should be returned. Note that the specifics about this parameter controlled entirely by what's returned as next in a paginated response and could either be a page number or a cursor.

Responses
200

Returns products' details for the provided search terms if available, separated in pages.

401

Credentials are missing or invalid.

get/products/search
Request samples
import fetch from 'node-fetch';

async function run() {
  const query = new URLSearchParams({search: 'string'}).toString();

  const marketplaceDomain = 'demo.topsort.com/topsort/api';
  const resp = await fetch(
    `https://${marketplaceDomain}/products/search?${query}`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN_HERE>'
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
{}

Retrieves categories

SecurityBearerAuth
Request
query Parameters
next
string non-empty

The string identifying the requested page. In case this parameter is missing then the first page should be returned. Note that the specifics about this parameter controlled entirely by what's returned as next in a paginated response and could either be a page number or a cursor.

Responses
200

Returns a complete list of categories, separated in pages.

401

Credentials are missing or invalid.

get/categories
Request samples
import fetch from 'node-fetch';

async function run() {
  const marketplaceDomain = 'demo.topsort.com/topsort/api';
  const resp = await fetch(
    `https://${marketplaceDomain}/categories`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN_HERE>'
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
{
  • "next": "asTpl1k746",
  • "response": [
    ]
}

Retrieves vendors

SecurityBearerAuth
Request
query Parameters
next
string non-empty

The string identifying the requested page. In case this parameter is missing then the first page should be returned. Note that the specifics about this parameter controlled entirely by what's returned as next in a paginated response and could either be a page number or a cursor.

Responses
200

Returns a complete list of vendors, separated in pages.

401

Credentials are missing or invalid.

get/vendors
Request samples
import fetch from 'node-fetch';

async function run() {
  const marketplaceDomain = 'demo.topsort.com/topsort/api';
  const resp = await fetch(
    `https://${marketplaceDomain}/vendors`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN_HERE>'
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
{
  • "next": "asTpl1k746",
  • "response": [
    ]
}

Retrieves brands

This endpoint is optional. It is used to allow advanced use cases for Banner Ads. Talk to your Account Manager to understand whether you need to implement this endpoint.

SecurityBearerAuth
Request
query Parameters
search
string

The search string provided by the user. In case this parameter is missing or an empty string is provided, all brands should be returned taking into account the other parameters.

Example: search=delirium tremens
vendorID
string non-empty

Vendor unique identifier. This identifier is given by the marketplace and allows this service to match the vendor with the proper brands.

Example: vendorID=9SiwYqqL8vdG
next
string non-empty

The string identifying the requested page. In case this parameter is missing then the first page should be returned. Note that the specifics about this parameter controlled entirely by what's returned as next in a paginated response and could either be a page number or a cursor.

Responses
200

Returns a complete list of brands, separated in pages.

401

Credentials are missing or invalid.

get/brands
Request samples
import fetch from 'node-fetch';

async function run() {
  const marketplaceDomain = 'demo.topsort.com/topsort/api';
  const resp = await fetch(
    `https://${marketplaceDomain}/brands`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN_HERE>'
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
{}

All Models

Brand

id
required
string non-empty

The brand ID.

name
required
string non-empty

The brand name.

imageURL
string <uri>

The brand image URL. Its size should be between 250x250 and 600x600 pixels.

{}

Category

id
required
string non-empty

The category ID. If there is no ID for categories in the marketplace, this can be the category name as long as it is unique.

name
required
string non-empty

The category name.

{
  • "id": "ahEDqV5uhjj8",
  • "name": "Beers/Belgian"
}

GetProductsByID Request

Array ([ 0 .. 50 ] items)
string non-empty
[
  • "eyGqR4YQgBJa",
  • "KHqzavLNS25n",
  • "wJLZ4TCNZtEW"
]

GetProductsByID Response

Array ([ 0 .. 50 ] items)
id
required
string non-empty read-only

The product ID.

name
required
string non-empty

The product name.

description
string non-empty

The product description.

vendorID
string non-empty

The vendor ID.

vendorName
string non-empty

The vendor name.

stock
integer <int32> >= 0

How many items of this product you have available. If this number is greater than 0, it means you have it in stock and you can fulfill a purchase.

price
integer <int32> >= 1

The product price in the minimum currency unit (e.g. cents if applicable). Refer to ISO 4217 to check how many decimals are used in your currency.

imageURL
string <uri>

The product image URL. Its size should be between 250x250 and 600x600 pixels.

categoryID
string non-empty

The category id.

categoryName
string non-empty

The category name.

[]

Paginated Brands Response

next
string non-empty

Id of the next page. This could be for example a page number (as a string) or a cursor identifying the next page. This attribute will be passed in the next query parameter.

required
Array of objects (Brand) [ 0 .. 50 ] items
{}

Paginated Categories Response

next
string non-empty

Id of the next page. This could be for example a page number (as a string) or a cursor identifying the next page. This attribute will be passed in the next query parameter.

required
Array of objects (Category) [ 0 .. 50 ] items
{
  • "next": "asTpl1k746",
  • "response": [
    ]
}

Paginated Products Response

next
string non-empty

Id of the next page. This could be for example a page number (as a string) or a cursor identifying the next page. This attribute will be passed in the next query parameter.

required
Array of objects (Product) [ 0 .. 50 ] items
{}

Paginated Response

next
string non-empty

Id of the next page. This could be for example a page number (as a string) or a cursor identifying the next page. This attribute will be passed in the next query parameter.

{
  • "next": "asTpl1k746"
}

Paginated Vendors Response

next
string non-empty

Id of the next page. This could be for example a page number (as a string) or a cursor identifying the next page. This attribute will be passed in the next query parameter.

required
Array of objects (Vendor) [ 0 .. 50 ] items
{
  • "next": "asTpl1k746",
  • "response": [
    ]
}

Product

A Product represents a product listed in a marketplace.

id
required
string non-empty read-only

The product ID.

name
required
string non-empty

The product name.

description
string non-empty

The product description.

vendorID
string non-empty

The vendor ID.

vendorName
string non-empty

The vendor name.

stock
integer <int32> >= 0

How many items of this product you have available. If this number is greater than 0, it means you have it in stock and you can fulfill a purchase.

price
integer <int32> >= 1

The product price in the minimum currency unit (e.g. cents if applicable). Refer to ISO 4217 to check how many decimals are used in your currency.

imageURL
string <uri>

The product image URL. Its size should be between 250x250 and 600x600 pixels.

categoryID
string non-empty

The category id.

categoryName
string non-empty

The category name.

{}

Vendor

id
required
string non-empty

The vendor ID.

name
required
string non-empty

The vendor name.

{
  • "id": "9SiwYqqL8vdG",
  • "name": "Huyghe Brewery"
}