omnicado-mall-proxy

Omnicado - Mall Marketplace API Proxy
1.0.0

Base URL 
https://mpapi.proxy.omnicado.com/v1

Trivia

Omnicado MALL Marketplace API Proxy provides functionality for sellers to manage their marketplace catalog, prices, promotions, inventory, orders and offsets based on MALL marketplace API. It is quite useful in cases you already have existing connection with Mall API and you want to build connection with Omnicado on top of existing connection.

API architecture

API is based on software architectural style REST and is secured by HTTPS protocol.

API functions

API endpoints are called by the appropriate HTTP methods

  • GET returns data about object, does not make any change
  • POST sends new data object
  • PUT updates existing data object
  • DELETE deletes data object

API endpoints

Production environment
  • For real traffic use endpoint https://mpapi.proxy.omnicado.com/v1/ for all countries. Country is recognized from client_id (see bellow).

Authorization

For all requests authorization key must be sent in a request as a client_id parameter.

Data format

All data are in the JSON format and encoded UTF-8. Content type can be set either as Content-Type: application/json or Content-Type: application/json; Charset=UTF-8.

Objects identification

All objects within the interface (e.g. products/variants) must have a unique identifier that is managed by a partner:

  • MALL does not assign any numerical series to partners
  • identifiers must start with a letter, number or an underscore and may contain letters, numbers, dashes, underscores or dots. You may use this regex to validate your product/variant id /^[a-z0-9_][a-z0-9\-_.]*$/i
  • identifier must be unique in the context of partner

There is an exception for orders, invoices and offsets and MALL Product number - Mall generates an ID, this ID is numeric and it is necessary to use it.

Please beware: our order numbers exceed the maximum allowed integer size for 32-bit PHP. You will need to use 64 bit version to avoid inconsistent order data.

Output

The endpoints return the output in the following structure:

{
    "result": {
        "code": 200/400/403/404/429/500,
        "status": OK/ERROR/LIMITED,
        "message": additional error information
    },
    "paging": {
        "pages": number of pages,
        "size": number of objects on a page,
        "page": number of current page
    },
    "data": {
        data structure
    }
}

Paging and message may be missing when not needed.

DELETE requests return no content (204 status code).

Result

Returns HTTP code, status and additional error message.

Paging

Object paging is included in a case that the output is divided into multiple pages. To select a specific page output you can use a page query variable.

Paging can be set by calling URL with parameters page and page_size. The default page size (and also the maximum value) is 100. With exception of /v1/products endpoint which has static page size of 1000 records and /v1/orders endpoints, that have maximum limit of 1000 records.

https://mpapi.proxy.omnicado.com/v1/products?client_id={clientId}&page={page}&page_size={pageSize}

Data

Data structure differs depending on the endpoint and is described for each endpoint separately.

HTTP codes
  • 200 OK - everything is fine and the data is returned correctly
  • 201 Created - sent data was accepted and entity created
  • 204 No content - response for your request does not contain any data
  • 400 Bad Request - the data sent by the client are not valid (detailed description is returned in the message attribute)
  • 401 Unauthorized - unauthorized access, missing or bad client_id
  • 403 Forbidden - you do not have access to this endpoint and method combination
  • 404 Not Found - requested data not found
  • 429 Too Many Requests - you have been rate limited and should slow down your request rate
  • 500 Internal Server Error - may be caused e.g. by unavailable access to one of the system interfaces (database, webservices, SAP etc.)

Rate limiting

When calling any API endpoint, API wil return following headers in a response.

x-ratelimit-limit: 2875, 5750;w=86400;name="partner:my_client_id|domain:other|unit:d", 2875;w=3600;name="partner:my_client_id|domain:other|unit:h", 17250;w=60;name="partner:my_client_id|domain:other|unit:m"
x-ratelimit-remaining: 2871
x-ratelimit-reset: 3527

x-ratelimit-limit

  • contains all available time windows applicable for request made with the count of requests from smallest window as first value

x-ratelimit-remaining

  • smallest amount of requests remaining in the time window (i.e. if you have 1000 remaining requests for hour window and 1600 for day, this header will contain 1000)
  • if you reach 0 remaining requests, API will return 429 Too Many Requests HTTP status code until the window resets

x-ratelimit-reset

  • time in seconds until current window with lowest amount of requests resets

Read more about rate limit headers here and more about Mall rate limiting rules here.

Data validation

API requests are validated. If there are any errors to fix, error list is returned in the response body.

This is version 1.0.0 of this API documentation. Last update on Nov 2, 2022.