# Omnicado - Mall Marketplace API Proxy ## Description This is version `1.0.0` of this API documentation. Last update on Nov 2, 2022. # 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](https://tools.ietf.org/id/draft-polli-ratelimit-headers-00.html) and more about Mall rate limiting rules [here](https://knowledgebase.mallgroup.com/en/api-limity-co-je-rate-limiter/). ## Data validation API requests are validated. If there are any errors to fix, error list is returned in the response body. ## Servers ## Authentication The API accepts 2 different authentication methods: - Application name (http_api_key) - Client (http_api_key) ## Endpoints and operations ### [Categories](https://mall-api-proxy.documentation.omnicado.com/group/endpoint-categories.md) - [Get list of category parameters and their values](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-categories-parameter-parameters.md) - [Get list of category parameters](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-categories-parameter-params.md) - [Get list of all available categories](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-categories.md) - [Get list of parameter values](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-categories-parameter-params-parameter.md) - [Category tree by country](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-categories-tree-parameter.md) - [Category detail](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-categories-detail-parameter.md) ### [Brands](https://mall-api-proxy.documentation.omnicado.com/group/endpoint-brands.md) - [Get list of all available brands](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-brands.md) ### [Product labels](https://mall-api-proxy.documentation.omnicado.com/group/endpoint-product-labels.md) - [Get list of product labels](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-labels.md) ### [Products](https://mall-api-proxy.documentation.omnicado.com/group/endpoint-products.md) - [Get products list](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-products.md) - [Create new product](https://mall-api-proxy.documentation.omnicado.com/operation/operation-post-products.md) - [Get existing product detail](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-products-parameter.md) - [Update existing product](https://mall-api-proxy.documentation.omnicado.com/operation/operation-put-products-parameter.md) - [Delete product](https://mall-api-proxy.documentation.omnicado.com/operation/operation-delete-products-parameter.md) - [Activate product](https://mall-api-proxy.documentation.omnicado.com/operation/operation-post-products-parameter-activate.md) - [Get product availability](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-products-parameter-availability.md) - [Update product availability](https://mall-api-proxy.documentation.omnicado.com/operation/operation-put-products-parameter-availability.md) - [Get product pricing](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-products-parameter-pricing.md) - [Update product pricing](https://mall-api-proxy.documentation.omnicado.com/operation/operation-put-products-parameter-pricing.md) - [Get product supply delay](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-products-parameter-supply-delay.md) - [Update product supply delay](https://mall-api-proxy.documentation.omnicado.com/operation/operation-put-products-parameter-supply-delay.md) - [Set product supply delay](https://mall-api-proxy.documentation.omnicado.com/operation/operation-post-products-parameter-supply-delay.md) - [Delete product supply delay](https://mall-api-proxy.documentation.omnicado.com/operation/operation-delete-products-parameter-supply-delay.md) ### [Variants](https://mall-api-proxy.documentation.omnicado.com/group/endpoint-variants.md) - [Get list of variants](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-products-parameter-variants.md) - [Create a new variant](https://mall-api-proxy.documentation.omnicado.com/operation/operation-post-products-parameter-variants.md) - [Get variant data](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-products-parameter-variants-parameter.md) - [Update existing variant](https://mall-api-proxy.documentation.omnicado.com/operation/operation-put-products-parameter-variants-parameter.md) - [Delete variant](https://mall-api-proxy.documentation.omnicado.com/operation/operation-delete-products-parameter-variants-parameter.md) - [Get variant availability](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-products-parameter-variants-parameter-availability.md) - [Update variant availability](https://mall-api-proxy.documentation.omnicado.com/operation/operation-put-products-parameter-variants-parameter-availability.md) - [Get variant pricing](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-products-parameter-variants-parameter-pricing.md) - [Update variant pricing](https://mall-api-proxy.documentation.omnicado.com/operation/operation-put-products-parameter-variants-parameter-pricing.md) - [Get variant supply delay](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-products-parameter-variants-parameter-supply-delay.md) - [Update variant supply delay](https://mall-api-proxy.documentation.omnicado.com/operation/operation-put-products-parameter-variants-parameter-supply-delay.md) - [Set variant supply delay](https://mall-api-proxy.documentation.omnicado.com/operation/operation-post-products-parameter-variants-parameter-supply-delay.md) - [Delete variant supply delay](https://mall-api-proxy.documentation.omnicado.com/operation/operation-delete-products-parameter-variants-parameter-supply-delay.md) ### [Deliveries](https://mall-api-proxy.documentation.omnicado.com/group/endpoint-deliveries.md) - [Get districts](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-deliveries-districts.md) - [Get list of partner defined deliveries](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-deliveries-partner.md) - [Create partner delivery](https://mall-api-proxy.documentation.omnicado.com/operation/operation-post-deliveries-partner.md) - [Delete all partner deliveries](https://mall-api-proxy.documentation.omnicado.com/operation/operation-delete-deliveries-partner.md) - [Get partner delivery detail](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-deliveries-partner-parameter.md) - [Update selected partner delivery](https://mall-api-proxy.documentation.omnicado.com/operation/operation-put-deliveries-partner-parameter.md) - [Delete single partner delivery](https://mall-api-proxy.documentation.omnicado.com/operation/operation-delete-deliveries-partner-parameter.md) - [Get list of partner pickup points](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-deliveries-partner-parameter-pickup-point.md) - [Add new partner pickup point](https://mall-api-proxy.documentation.omnicado.com/operation/operation-post-deliveries-partner-parameter-pickup-point.md) - [Get detail of one single pickup point](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-deliveries-partner-parameter-pickup-point-parameter.md) - [Update partner pickup point](https://mall-api-proxy.documentation.omnicado.com/operation/operation-put-deliveries-partner-parameter-pickup-point-parameter.md) - [Delete one selected pickup point](https://mall-api-proxy.documentation.omnicado.com/operation/operation-delete-deliveries-partner-parameter-pickup-point-parameter.md) - [Get data for all pricing levels](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-deliveries-partner-parameter-pricing.md) - [Create or update pricing levels](https://mall-api-proxy.documentation.omnicado.com/operation/operation-post-deliveries-partner-parameter-pricing.md) - [Delete delivery method pricing](https://mall-api-proxy.documentation.omnicado.com/operation/operation-delete-deliveries-partner-parameter-pricing.md) ### [Transports](https://mall-api-proxy.documentation.omnicado.com/group/endpoint-transports.md) - [Get transports](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-transports.md) - [Transport detail](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-transports-parameter.md) ### [Orders](https://mall-api-proxy.documentation.omnicado.com/group/endpoint-orders.md) - [Get orders using filters](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-orders.md) - [Get list of unconfirmed orders](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-orders-unconfirmed.md) - [Get list of orders by status](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-orders-parameter.md) - [Get order detail](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-orders-parameter.md) - [Update order](https://mall-api-proxy.documentation.omnicado.com/operation/operation-put-orders-parameter.md) - [Generate labels for MALL Delivery orders](https://mall-api-proxy.documentation.omnicado.com/operation/operation-post-orders-labels.md) - [Generates labels for both DIP and MPD orders](https://mall-api-proxy.documentation.omnicado.com/operation/operation-post-orders-labels-bulk.md) - [Set order item serial numbers](https://mall-api-proxy.documentation.omnicado.com/operation/operation-put-orders-parameter-items-parameter-serial-numbers.md) - [Set order tracking number](https://mall-api-proxy.documentation.omnicado.com/operation/operation-put-orders-parameter-tracking-number-parameter.md) - [Set order tracking information](https://mall-api-proxy.documentation.omnicado.com/operation/operation-put-orders-parameter-tracking.md) - [Create new order labels](https://mall-api-proxy.documentation.omnicado.com/operation/operation-post-orders-parameter-labels.md) - [Returns order consignments](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-orders-parameter-consignments.md) - [Get order statistics](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-orders-stats.md) ### [Invoices](https://mall-api-proxy.documentation.omnicado.com/group/endpoint-invoices.md) - [Get list](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-invoices.md) - [Get invoice detail](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-invoices-parameter.md) - [Download invoice PDF](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-invoices-parameter-download.md) ### [Checks](https://mall-api-proxy.documentation.omnicado.com/group/endpoint-checks.md) - [Check products and variants delivery setup](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-checks-deliveries.md) - [Check products/variants media](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-checks-media.md) ### [Offsets](https://mall-api-proxy.documentation.omnicado.com/group/endpoint-offsets.md) - [Get offset list](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-offsets.md) - [GET detail](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-offsets-parameter.md) - [Download offset PDF](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-offsets-parameter-download.md) ### [Batches](https://mall-api-proxy.documentation.omnicado.com/group/endpoint-batches.md) - [Activate selected products](https://mall-api-proxy.documentation.omnicado.com/operation/operation-put-batches-products-activate-selected.md) - [Activate all products](https://mall-api-proxy.documentation.omnicado.com/operation/operation-put-batches-products-activate-all.md) - [Batch update of product/variant availability](https://mall-api-proxy.documentation.omnicado.com/operation/operation-post-availability.md) ### [Partners](https://mall-api-proxy.documentation.omnicado.com/group/endpoint-partners.md) - [Get partner supply delay data](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-partners-supply-delay.md) - [Update partner supply delay](https://mall-api-proxy.documentation.omnicado.com/operation/operation-put-partners-supply-delay.md) - [Create new partner supply delay](https://mall-api-proxy.documentation.omnicado.com/operation/operation-post-partners-supply-delay.md) - [Delete partner supply delay](https://mall-api-proxy.documentation.omnicado.com/operation/operation-delete-partners-supply-delay.md) ### [Search](https://mall-api-proxy.documentation.omnicado.com/group/endpoint-search.md) - [Find product](https://mall-api-proxy.documentation.omnicado.com/operation/operation-get-search-article-parameter.md) [Powered by Bump.sh](https://bump.sh)