diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index 2eab7dd..daa915b 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -2,7 +2,7 @@ openapi: 3.1.0 info: title: 'Shoptet API' version: 1.0.0 - description: "Created in cooperation with the Ministry of Industry and Trade of the Czech Republic within the \"The Country for the Future\" programme.\n\n\nThis documentation provides information about the interface for developers who would like to gain access to Shoptet\ne-shops. For more information about Shoptet, see https://www.shoptet.cz/.\n\nThe API is available in two access modes:\n\n- for \"Shoptet partner” developers who create the interconnection with the services and extend the Shoptet system's\n functions for public usage. For more information about API and conditions, under which\n it can be used, see https://developers.shoptet.com/addons/.\n- direct private access to eshop data for eshop owner - available only for [Premium Members](https://www.shoptetpremium.cz/).\n See https://developers.shoptet.com/premium for more information about API access.\n# Basic principles of working with API\n\n## How to call API\n\nAPI supports communication in JSON format. The URL for calling API requests is https://api.myshoptet.com. The API calls\n(endpoints and message formats) are common for private as well as addons access, it however uses different authentication\nand authorization principles.\n\n### For Addons\n\nAPI is made to create the supplements for the Shoptet system and uses OAuth2 authorization principles.\nTo access the API it is necessary to implement a web service at your side, which will communicate with our OAuth server.\n\nIn your e-shop administration, which you are using to work with our API, you must search in the `API Partner` section for the `Access to API` tab.\nHere, you will find your clientID and addresses, from where you can call our OAuth server.\n\nThe work with API begins with e-shop addon installation. (The installation process can be tested in the addon detail in the `Users` section, where you can cause the installation for your e-shop.)\nIn your addon detail, in the `Settings` section, enter URL to gain a OAuth code. The URL must be linked to your server, where the script is prepared, which is able to gain an OAuth access token.\nAt this address, you will receive the HTTP request with a GET parameter `code`, when installing the addon, with unique value (a 255 character long string).\nThe `code` provided only has short-term validity and can be used only once. With this code, request our OAuth server to provide an `OAuth access token`.\nSuch a request shall follow within the same script that received the `code`.\nDo not put off gaining the OAuth access token for a later time, and do not reply to our request with a `200 OK` status, until you gain the OAuth access token.\nThe address for you to call, and an example of implementation, can be found in e-shop administration in the `Access to API` section.\n\nAs a response you will obtain a JSON with your OAuth access token. Save this token securely. Never send this token to the client computer, and use it only\nfor communication between the servers and for gaining the temporary token for access to API.\n\nIf you have successfully received an OAuth access token, your script must end with the HTTP status code “200”.\n\nNow you have your OAuth access token, which links your addon with a specific e-shop, perhaps you would like to communicate with the e-shop via API.\n\nFrom your server, call `https:///action/ApiOAuthServer/getAccessToken` address with HTTP header `Authorization: Bearer `.\nAs the reply, you will receive a JSON containing an API access token value and the token expiration time value. An example of calling can be found in e-shop administration in the `Access to API` section.\nIt is possible to request a maximum of 5 valid tokens.\n\nThe API access token will enable you to call an individual URL of our API, for example `https://api.myshoptet.com/api/eshop`. Send the API access token in each request in the HTTP header`Shoptet-Access-Token`.\nYou can have several valid API access tokens available at any one time. Should the validity of the API access token expire, you will receive a HTTP status code 401 and message about token expiration.\n\n```\n{\n \"data\": 'null',\n \"errors\": [\n {\n \"errorCode\": \"expired-token\",\n \"message\": \"Token is expired. Please ask for new one.\",\n \"instance\": \"unknown\"\n }\n ]\n}\n```\n\nIf your token does not have the access right for a specific endpoint, you will obtain a reply with HTTP status code 403 Forbidden.\n\n```\n{\n \"data\": 'null',\n \"errors\": [\n {\n \"errorCode\": \"invalid-token-no-rights\",\n \"message\": \"Your access token \\\"afd..123\\\" has no defined rights for this resource.\",\n \"instance\": \"access-token\"\n }\n ]\n}\n```\n\n### For private API access (Premium)\n\nYou can create API access tokens simply in the eshop administration. Send them in the request header `Shoptet-Private-API-Token`.\nYou can automatically access all API endpoints.\n\n## Rate limiting\n\nRate limiting is only at the level of server overload protection (DDoS), whereas the quantity of queries or total volume of data are unlimited.\nThese are therefore the limits of the maximum number of coincident active connections. A maximum of 50 from a single IP address, and a maximum of\n3 connections for a single token. If the limit is exceeded, the HTTP code 429 is returned. See also Nginx configuration:\n\n```\n limit_conn per_ip 50;\n limit_conn per_token 3;\n limit_conn_status 429;\n```\n\nSome URLs, for example for bulk operations, can have their own specific limits, which are mentioned in this documentation.\n\n## Locks\n\nWrite endpoints (DELETE, PATCH, POST, PUT methods) can take longer and may be prone to two concurrent matching requests.\nTo avoid problems with retrying identical write requests, we have added the locking function of these requests to the application.\nIf you execute the same request two times in quick succession, the second request receives error response with a 423 code.\nThe lock is only valid for a specific called URL, for the duration of the request processing, but no longer than 5 seconds.\n\n## API versioning\n\nCurrent version of API: v1.0\n\nThe client must send a `Content-Type` header with value of `application/vnd.shoptet.v1.0`,\nwhere `v1.0` is the API version supported by the client. If there is any change in the API, then we are trying to make it\nreverse compatible, therefore it is not necessary to regularly update your connection after each change in our interface.\n\nThe version is the same for all endpoints described here.\n\n## Server response format\n\nAll JSON responses from the server have the same format, as a base.\nIf any of the sections is not present in the response, a `null` value is then received.\n\nExample of call for addons:\n\n```\ncurl --include \\\n -H 'Shoptet-Access-Token: 123456-a-123-XXXXXXXXXXXXXXXXXXXXXXXXX' \\\n -H 'Content-Type: application/vnd.shoptet.v1.0' \\\n 'https://api.myshoptet.com/api/eshop'\n```\n\nExample of call for private API access:\n\n```\ncurl --include \\\n -H 'Shoptet-Private-API-Token: 123456-a-123-XXXXXXXXXXXXXXXXXXXXXXXXX' \\\n -H 'Content-Type: application/vnd.shoptet.v1.0' \\\n 'https://api.myshoptet.com/api/eshop'\n```\n\nExample of response:\n\n```\nHTTP/2 200\ndate: Fri, 13 Jul 2018 15:57:29 GMT\ncontent-type: application/vnd.shoptet.v1.0+json; charset=utf-8\n\n{\n \"data\": {\n \"contactInformation\": {\n \"eshopName\": \"www.domena-eshopu.cz\",\n \"url\": \"https:\\/\\/www.domena-eshopu.cz\\/\",\n \"companyId\": \"28935675\",\n ...\n }\n ...\n },\n \"errors\": 'null'\n}\n```\n\nThe basic structure of the response in the event of an error is as follows:\n\n```\n{\n \"data\": 'null',\n \"errors\": [\n {\n \"errorCode\": \"missing-access-token\",\n \"message\": \"Missing access token. Please add `Shoptet-Access-Token` header to your request.\",\n \"instance\": \"unknown\"\n }\n ]\n}\n```\n\nMost of the endpoints are synchronous, i.e. your answer is provided immediately and contains the data requested. There\nare however some endpoints, where either the request or the response processing takes longer time. These are implemented as\n[Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/). Your request will be queued and you\nreceive only job identification in the response. You will be notified using a\n[webhook](https://developers.shoptet.com/api/documentation/webhooks/) when the job is completed and your results\ndownloadable. Be aware, that registration of webhook `job:finished` is required to be able to run asynchronous requests.\nIf webhook is not registered, you will receive an error response with HTTP status code 403 and job won't be queued.\nWebhook `job:finished` is also emitted when the job is failed so there is need to check the [Detail of job](openapi/job-endpoints/getjobdetail) to get the result of the job. If an error occurs during an asynchronous request, the job is automatically marked as failed 3 hours after its creation, and in this case, the `job:finished` webhook is not emitted.\n\nSome attributes may be added to the new API version, or the sequence of attributes can be changed.\nYour software, therefore, shall not rely on either of these.\nIf some attributes are renamed or removed, you will be informed in an additional\nheader - see also [API versioning](#section/Basic-principles-of-working-with-API/API-versioning) and [Deprecated header + Sunset](#section/Basic-principles-of-working-with-API/Deprecated-header-+-Sunset).\n\n## Deprecated header + Sunset\n\nIf you are calling some endpoint in a version that will not be supported in the future, you will receive a response with the header\n`X-Shoptet-Deprecated`. If you detect this header within the response and its presence is logged,\nyou should be aware of the support termination for a specific endpoint in advance and thus have enough time for correction.\n\nFurthermore, you shall also receive the response with a`Sunset` header with the date when the support for this endpoint is to be terminated.\n\n## Status codes\n\nWhen processing the response, the client shall first detect, what response status code was received.\n\nFor GET requests for responses with 200 code, it is not necessary to explore the `errors` part of the response.\nFor PATCH/PUT requests, which can process more records at the same time and some records\nare not processed successfully, these end with a 200 response code and the errors key contains info\n on skipped rows.\nThe unknown record is returned with a 404 code, etc. These responses have the error field filled in, where you can\nfind detailed info about the error.\n\nThe following errors might be expected:\n\n* 400 - Some of the validations on item level have failed. There is no reason to retry, it will fail always.\n\n* 401 - Invalid token or the token has expired (for addons access tokens). You have to ask for another one.\n\n* 403 - Forbidden. The token has no rights to the endpoint called. The endpoints must be allowed for an addon\n and the eshop must have approved them. Valid for addons access tokens, private tokens can always access all\n endpoints. Can be also returned when required module for request is missing.\n* 404 - Either the endpoint is wrong; or most commonly, an entity identifier, which is part of the URL, does\n not exist.\n* 409 - Conflict - the action could not be completed for some consistency rules, such as duplicate data\n or relation, which would be broken.\n* 413 - Payload too large - update requests can sometimes contain multiple entities to be amended. There is\n however a limit (varying for each request), how many can be specified within one request. If you breach the\n limit, you will get this error and nothing will be updated.\n* 422 - Unprocessable entity - we were not able to parse the request - it does not match the expected format.\n Something is wrong with the request as whole, it might not be a correct JSON or it does not match the expected\n JSON schema. There is no reason to retry, it will always fail.\n* 423 - Locked - for update and some read request we apply locks, usually on an URL level, which should avoid\n consistency problems possibly occuring from parallel updates. See [chapter about locks](#section/Basic-principles-of-working-with-API/Locks). Retry later,\n try to avoid parallel update requests.\n* 500 - General server error. Yes, this might happen to our software, too. Most commonly this is a temporary\n database issue and it might (but might not), work a few minutes later. We monitor all such errors and we\n try to analyze and fix them.\n* 503 - System maintenance. Most commonly we move a database to another database cluster or a database migration is\n pending and it will be available in a few minutes. Please try later.\n\n## Paging\n\nSome endpoints can return larger quantity of records. Such endpoints do not return the entire result, but support pagination of results.\nYou can page using `page` (int) and `itemsPerPage` (int) parameters. The first page has number 1. If you require a different\nquantity of items per page, use the `itemsPerPage` parameter. CAUTION: the number of items per page can be decreased only, the default\nvalue is maximum. The default value can be different for each endpoint.\n\nWhen paging, check the total number of items, if not altered (`totalCount`), then the\nitems on pages could be shifted and some of them could be missed or processed twice.\n\n## Section on demand\n\nSome endpoints return the data sections as optional, on demand. The request is done by giving the section name in the\n`include` parameter. Part of the data is returned each time, the other section only on demand. This makes the responses smaller for those, who do not need the data\n, thus saving the volume of data transmitted and shortening the time to process the request.\n\nFor example, for \"Eshop Info\" endpoint, you will gain basic info when simply calling `[GET] /api/eshop`, but payment\nmethods and transport options only when using `[GET] /api/eshop?include=paymentMethods,shippingMethods`.\n\nMore values are separated by a comma, no sequencing, no upper/lower case differentiation. Other blocks are available on demand\nand each endpoint informs you which identifier to request.\n\n## Translations\n\nFor proper functionality in translations you will have to get module Foreign languages (Cizí jazyky) activated on customer e-shop. Multi-language support in API is handled by query parameter `language`, which can be used in whole API. If parameter is not set, default shop language is used.\nRead endpoints (HTTP verb GET) will return corresponding language version of texts where applicable.\n\nFor write endpoints, first use POST endpoint to create entity and then use PATCH endpoint with corresponding language query parameter to set language fields.\n\nPlease note that in some endpoints (typically surcharge/filtering/variant parameters) you must use the identifier's currently selected language variant (which is filtered in list).\n\n## Files\n\nFor files upload, there are [Files endpoints](#tag/Files).\n\nThe file is uploaded to a temporary storage which is not accessible publicly. The file is kept there for 7 days and then deleted.\n\nAfter you upload a file, you may copy it to some API entities in their endpoints - you specify filename returned in response of upload job.\n\nPlease note that currently only images (png, jpg, gif) are allowed filetypes for file upload.\n\n# Product images\n\nShoptet saves the product images in their original size and then prepares several sizes for standardized usage (called\nimage cuts). These cuts are created in advance and saved on the disk, so they are readily available. The list of cuts is\nthe same for each e-shop, and each e-shop can theoretically have different cut sizes. In practice, their size is given\nby the template and most templates use the same sizes. The list of provided cuts is given by\nthe [Image cuts](#section/Code-lists/Image-cuts) code list.\n\nThe `/api/eshop?include=imageCuts` endpoint returns the `imageCuts` field in the response, where each cut has the actual\nsize defined, and the URL base path. There are two base URLs (example for classic.shoptet.cz, cut `detail`):\n\n- `urlPath`: \"https://classic.shoptet.cz/user/shop/detail/\"\n\n- `cdnPath`: \"https://cdn-api.myshoptet.com/usr/classic.shoptet.cz/user/shop/detail/\"\n\nUse the `urlPath` in case you need an up-to-date image right now. Use the url for your backend processing and you\nwill retrieve the images only once. Images retrieved via `urlPath` are not cached. You can use image name or SEO version\nof the image name - see below.\n\nUse the `cdnPath` in case you want to use the image url on the frontend and users of your application will display it,\ne.g. if you provide an alternative frontend, mobile application etc. The images are cached and provided with lower\nlatency. Use `cdnName` retrieved from the product detail endpoint (or similar) - see below.\n\nOnce you determine the URL based on the purpose and image cut size (for example `detail` for product detail, or `related`\nfor product preview), just append the filename you need. The filename can be retrieved from Product detail endpoint.\n\nAlthough the e-shop is behind the content delivery network (Cloudflare CDN), API still returns the same domain. Whether\nthe e-shop is behind the Cloudflare CDN, you can find out from response headers (`CDN-Loop: cloudflare` header).\n\nThe product detail endpoint `/api/products/{guid}?include=images` returns the image field `data.images[]` in the same\nsequence, as these are entered in administration. The file name `name` (for example `100.jpg`) needs to be connected\nto the URL cut and then you have complete path to the image of a given cut (size), for example\n`https://classic.shoptet.cz/user/shop/detail/100.jpg`. You can also use `seoName`, which also contains a description\nof the image - you will be redirected to the same image. The `cdnName` is intended for use with the `cdnUrl` only.\nThe fields look like: (excerpt)\n\n```json\n \"name\": \"106.png\",\n \"description\": \"shamrock 2115611 640\",\n \"seoName\": \"106_shamrock-2115611-640.png\",\n \"cdnName\": \"106_shamrock-2115611-640.png?5b2a41f5\"\n```\n\nOne of the images mentioned for the product can be selected as the default image for the product variant. The selected\nimage is in `data.variants[].image` item and contains the name of the image – this can be searched for in the image\nlist, in the `name` item. Should the variant have no preselected default image, the parameter `image` is `null`.\nIf `data.variants[].isProductDefaultImage` is true, then the default product image is given. If it is `false`, then it is the default variant image.\nThe item `data.items[].mainImage` contains the main image in order detail - this is either a default variant image,\nor, if not set (or product does not have variants), the default product image is given. The structure is the same as\nin product details, but not all images are given here, only the default one – representative image. The full path can\nbe gained by assembling the `urlPath` from the e-shop info and the `name` or `seoName` items, given for the order item.\n\nSimilarly, the product list gives `data.products[].mainImage`, which mentions the initial image for each product.\n\n# Code lists\n\n## Image cuts\n\nValue | Description\n-------- | ---------\norig | original image (in the original resolution)\nbig | big image (typically 1024x768 px)\ndetail |image detail (typically 360x270 px)\ncategory | size for listing in category (typically 216x105 px)\n\n## Product visibility\n\nValue | Description\n-------- | ---------\nhidden | Hide product\nvisible | Show product\nblocked | Cannot be ordered\nshow-registered | Show only to logged-in users\nblock-unregistered | Do not allow order to logged-out users\ncash-desk-only | Show only in cash desk\ndetail-only | Do not show e-shop navigation\n\n## Product types\n\nValue | Description\n-------- | ---------\nproduct | Product\nbazar | Second-hand product\nservice | Service\ngift-certificate | Gift (deprecated)\nproduct-set | Product set\n\n## Types of order items\n\nValue | Description\n-------- | ---------\nproduct | Product\nbazar | Second-hand product\nservice | Service\nshipping | Transportation\nbilling | Payment method\ndiscount-coupon | Discount coupon\nvolume-discount | Volume discount\ngift | Gift\ngift-certificate | Gift certificate\ngeneric-item | Non-specific item\nproduct-set | Product set\nproduct-set-item | Product set item\ndeposit | Deposit\n\n## Sorting of products in category\n\nValue | Description\n-------- | ---------\ndefault | Default\nmost-selling | Most selling first\ncheapest | Cheapest first\nmost-expensive | Most expensive first\noldest | Oldest first\nnewest | Newest first\nalphabetically | Alphabetically\nalphabetically-desc | Alphabetically, descending\nproduct-code | Per product code\nproduct-code-desc | Per product code, descending\ncategory-priority | Category priority\ncategory-priority-desc | Category priority, descending\n\n## Webhook event types\n\nValue | Description | Identifier meaning\n-------- | --------- | ---------\nbrand:create | Brand creation event | String (`code`) - brand unique code\nbrand:update | Brand change event | String (`code`) - brand unique code\nbrand:delete | Brand deleting event | String (`code`) - brand unique code\ncreditNote:create | Credit note creation event | Number (`code`) of credit note\ncreditNote:delete | Credit note deleting event | Number (`code`) of credit note\ncreditNote:update | Credit note change event | Number (`code`) of credit note\ncustomer:create | New customer was created | Customer GUID\ncustomer:update | Customer was updated. Throws `409 Conflict` when try to register simultaneously with `customer:disableOrders` or `customer:enableOrders` | Customer GUID\ncustomer:disableOrders | An event disabled the customer, and his future orders will be automatically cancelled. Throws `409 Conflict` when try to register simultaneously with `customer:update` | Customer GUID\ncustomer:enableOrders | An event enabled the customer's future orders. Throws `409 Conflict` when try to register simultaneously with `customer:update` | Customer GUID\ncustomer:import | Import of 1 and more customers was executed | Fixed string \"customers\"\ncustomer:delete | Customer was deleted | Customer GUID\ndeliveryNote:create | Delivery note creation event | Number (`code`) of delivery note\ndeliveryNote:delete | Delivery note deleting event | Number (`code`) of delivery note\ndeliveryNote:update | Delivery note change event | Number (`code`) of delivery note\neshop:currencies | Currencies settings change event | ID of eshop\neshop:billingInformation | Billing information (i.e. eshop billing address) change event | ID of eshop\neshop:design | Design settings (template, colors, fonts, layout) | ID of eshop\neshop:mandatoryFields | Mandatory fields of customer were updated | ID of eshop\neshop:projectDomain | Domain of eshop was changed | ID of eshop\ninvoice:create | Invoice creation event | Number (`code`) of invoice\ninvoice:delete | Invoice deleting event | Number (`code`) of invoice\ninvoice:update | Invoice change event | Number (`code`) of invoice\njob:finished | The asynchronous request was finished | Job `id`\nmailingListEmail:create | E-mail addition event into the e-mail distribution list | Name (`code`) of e-mail distribution list\nmailingListEmail:delete | E-mail deleting event from the e-mail distribution list | Name (`code`) of e-mail distribution\norder:cancel | Order cancel event. Webhook is emitted when order status is set to `canceled`. Throws `409 Conflict` when try to register simultaneously with `order:update` | Number (`code`) of order\norder:create | Order creation event | Number (`code`) of order\norder:delete | Order deleting event | Number (`code`) of order\norder:update | Order change event. Throws `409 Conflict` when try to register simultaneously with `order:cancel` | Number (`code`) of order\norderStatusesList:change | Order status list change event. Emitted when order status is created, updated or deleted | Order status `ID`\npaymentMethod:change | Payment method change event | Payment method GUID\nproformaInvoice:create | Proforma invoice creation event | Number (`code`) of proforma invoice\nproformaInvoice:delete | Proforma invoice deleting event | Number (`code`) of proforma invoice\nproformaInvoice:update | Proforma invoice change event | Number (`code`) of proforma invoice\nproofPayment:create | Proof of payment creation event | Number (`code`) of proof payment\nproofPayment:delete | Proof of payment deleting event | Number (`code`) of proof payment\nproofPayment:update | Proof of payment change event | Number (`code`) of proof payment\nshippingMethod:change | Shipping method change event | Shipping method GUID\nshippingRequest:cancelled | Shipping request was not chosen for order delivery | `shippingRequestCode` associated with the cart\nshippingRequest:confirmed | Shipping request was chosen for order delivery | `shippingRequestCode` associated with the cart\nstock:movement | Stock change event | Stock ID\nstock:inStock (*) | Stock change event - sum across all of the stocks raised above 0 (beta, see below) | Number (`code`) of product\nstock:soldOut (*) | Stock change event - sum across all of the stocks reached 0 (beta, see below) | Number (`code`) of product\nstock:minStockSupplyReached (*) | Stock change event - sum across all of the stocks reached minimum stock supply value, if this limit is set for product (beta, see below) | Number (`code`) of product\n(*) These webhooks are considered beta/experimental, for more information, please visit the X-url\n### Mass Webhooks\n\nThese webhooks are sent when a mass change of entities is performed. The payload contains a json serialized list of IDs of changed entities.\nPurpose of these webhooks is to downgrade number of requests, while i.e. administrator performs mass change of orders status at once etc.\nSo instead of emitting one event for every order, we emit one event for all of them.\n\nFor now, if some mass event is performed, we also sent \"single\" webhook event for every updated entity as usual, but it will be changed in future,\nso please watch [release changes](https://developers.shoptet.com/category/api/) for more info \n\nValue | Description | Identifier meaning\n-------- | --------- | ---------\ninvoice:massUpdate | Mass change of invoices event | Json serialized list of number (`code`) of invoices\norder:massUpdate | Mass change of orders event | Json serialized list of number (`code`) of orders\n\n### System Webhooks\n\nThese webhooks cannot be registered via API, they are setup in Partners' Addon administration section instead.\n\nValue | Description\n----- | -----------\naddon:suspend | The addon was suspended by the eshop or by Shoptet operations staff\naddon:approve | The addon was approved (resumed) after it was suspended\naddon:uninstall | The addon was uninstalled by the eshop admin or the eshop was terminated\n\n## URL address from endpoint Eshop info\nSee endpoint [Eshop info](#tag/Eshop)\nIdent | Description\n------| -----\nadmin-orders-list | Listing of orders in administration\nadmin-customers-list | List of customers in administration\noauth | OAuth server address, used for [e-shop user verification](https://developers.shoptet.com/api/documentation/eshop-verification-using-oauth/)\n\n## List of product catalogues\n\nProvider (identification) | Description\n------| -----\nglami | Glami\ngoogle | Google\nheureka | Heuréka\nzbozi | Zboží.cz\n\n## Invoice Billing Methods\n\nid | Description\n------| -----\n1 | COD (cz: Dobírka)\n2 | Wire transfer (cz: Převodem)\n3 | Cash (cz: Hotově)\n4 | Card (cz: Kartou)\n## VAT modes\n \n \nValue |\n------|\nNormal |\nOne Stop Shop |\nMini One Stop Shop |\n \nReverse charge |\n \nOutside the EU |\n\n# Postman collection for Shoptet API\n\nIf you use Postman as an API platform for building and using APIs, we provide you a complex collection of Shoptet API.\nYou have 2 options how to import our postman collection (created from [openApi schema](https://swagger.io/specification/) - openapi.yaml ) into your postman client\n\n## Fork Shoptet API Collection from Shoptet Public API Workspace (recommended)\n\nSee [Shoptet Public API Workspace](https://www.postman.com/shoptet-developers/shoptet-public-api-workspace).\nAlso check postman documentation for more details: [Fork a collection](https://learning.postman.com/docs/collaborating-in-postman/using-version-control/forking-elements/).\n\n### Step 1: Navigate to Shoptet Public API Workspace\n\n- Launch Postman on your desktop or in the browser.\n- In the search bar in the top header of app, type **Shoptet Public API** and select collection from Shoptet public API Workspace.\n\n### Step 2: Locate the Shoptet API Collection\n\n- Once inside the Shoptet Public API Workspace, go to the **Collections** tab.\n- Find the **Shoptet API** collection.\n\n### Step 3: Fork the Collection\n\n- Click on the **Shoptet API** collection to open it.\n- In the collection view, click the **Fork** button in the top-right corner.\n- In the fork dialog, choose a name for your forked collection.\n- Select the workspace where you want to save the forked collection.\n- **It’s recommended to check `watch original collection` to get notified about changes in the original collection.**\n- Click **Fork Collection**.\n\n### Step 4: Access Your Forked Collection\n\n- Navigate to the workspace where you saved the forked collection.\n- You’ll now find the forked **Shoptet API** collection under the **Collections** tab, ready for you to use and modify.\nNow you have your own copy of the Shoptet API collection! If you want to add changes from the original collection, you can do so by click on `pull changes` in collection settings.\n\n## Import openapi.yaml into Postman as a Collection\n\n### Step 1: Upload the `openapi.yaml` File\n\n- Download the [openapi.yaml](https://github.com/shoptet/developers/blob/master/openapi/openapi.yaml) file from our developers [repository](https://github.com/shoptet/developers).\n- Launch Postman on your desktop or in the browser.\n- In the top-left corner of Postman, click the **Import** button.\n- A pop-up window will appear.\n- Drag and drop your `openapi.yaml` file into the window, or click **Upload Files** and browse to the file's location.\n\n### Step 2: Verify OpenAPI Import\n\n- Postman will automatically recognize the OpenAPI schema.\n- It will display a preview of the API schema.\n\n### Step 3: Import as Collection\n\n- Once the file is recognized, click **Import**.\n- Postman will convert the OpenAPI schema into a collection of requests, based on the defined endpoints in the `openapi.yaml` file.\n\n### Step 4: Access the Imported Collection\n\n- After the import is successful, go to the **Collections** tab.\n- You’ll find your new collection, named after the OpenAPI schema, containing all the API requests generated from the file.\n\nNow you can explore the API endpoints and use them directly within Postman!\n## Collection settings\n1. Click the **Shoptet API** collection name.\n2. Go to **Authorization** tab.\n3. Set your access token into the `value` of `Shoptet-Access-Token` key.\n4. Go to **Variables** tab.\n5. You can set `baseUrl` variable here.\n# Last changes\n\nLast API changes are published on the [API news] page (https://developers.shoptet.com/category/api/)." + description: "Created in cooperation with the Ministry of Industry and Trade of the Czech Republic within the \"The Country for the Future\" programme.\n\n\nThis documentation provides information about the interface for developers who would like to gain access to Shoptet\ne-shops. For more information about Shoptet, see https://www.shoptet.cz/.\n\nThe API is available in two access modes:\n\n- for \"Shoptet partner” developers who create the interconnection with the services and extend the Shoptet system's\n functions for public usage. For more information about API and conditions, under which\n it can be used, see https://developers.shoptet.com/addons/.\n- direct private access to eshop data for eshop owner - available only for [Premium Members](https://www.shoptetpremium.cz/).\n See https://developers.shoptet.com/premium for more information about API access.\n# Basic principles of working with API\n\n## How to call API\n\nAPI supports communication in JSON format. The URL for calling API requests is https://api.myshoptet.com. The API calls\n(endpoints and message formats) are common for private as well as addons access, it however uses different authentication\nand authorization principles.\n\n### For Addons\n\nAPI is made to create the supplements for the Shoptet system and uses OAuth2 authorization principles.\nTo access the API it is necessary to implement a web service at your side, which will communicate with our OAuth server.\n\nIn your e-shop administration, which you are using to work with our API, you must search in the `API Partner` section for the `Access to API` tab.\nHere, you will find your clientID and addresses, from where you can call our OAuth server.\n\nThe work with API begins with e-shop addon installation. (The installation process can be tested in the addon detail in the `Users` section, where you can cause the installation for your e-shop.)\nIn your addon detail, in the `Settings` section, enter URL to gain a OAuth code. The URL must be linked to your server, where the script is prepared, which is able to gain an OAuth access token.\nAt this address, you will receive the HTTP request with a GET parameter `code`, when installing the addon, with unique value (a 255 character long string).\nThe `code` provided only has short-term validity and can be used only once. With this code, request our OAuth server to provide an `OAuth access token`.\nSuch a request shall follow within the same script that received the `code`.\nDo not put off gaining the OAuth access token for a later time, and do not reply to our request with a `200 OK` status, until you gain the OAuth access token.\nThe address for you to call, and an example of implementation, can be found in e-shop administration in the `Access to API` section.\n\nAs a response you will obtain a JSON with your OAuth access token. Save this token securely. Never send this token to the client computer, and use it only\nfor communication between the servers and for gaining the temporary token for access to API.\n\nIf you have successfully received an OAuth access token, your script must end with the HTTP status code “200”.\n\nNow you have your OAuth access token, which links your addon with a specific e-shop, perhaps you would like to communicate with the e-shop via API.\n\nFrom your server, call `https:///action/ApiOAuthServer/getAccessToken` address with HTTP header `Authorization: Bearer `.\nAs the reply, you will receive a JSON containing an API access token value and the token expiration time value. An example of calling can be found in e-shop administration in the `Access to API` section.\nIt is possible to request a maximum of 5 valid tokens.\n\nThe API access token will enable you to call an individual URL of our API, for example `https://api.myshoptet.com/api/eshop`. Send the API access token in each request in the HTTP header`Shoptet-Access-Token`.\nYou can have several valid API access tokens available at any one time. Should the validity of the API access token expire, you will receive a HTTP status code 401 and message about token expiration.\n\n```\n{\n \"data\": 'null',\n \"errors\": [\n {\n \"errorCode\": \"expired-token\",\n \"message\": \"Token is expired. Please ask for new one.\",\n \"instance\": \"unknown\"\n }\n ]\n}\n```\n\nIf your token does not have the access right for a specific endpoint, you will obtain a reply with HTTP status code 403 Forbidden.\n\n```\n{\n \"data\": 'null',\n \"errors\": [\n {\n \"errorCode\": \"invalid-token-no-rights\",\n \"message\": \"Your access token \\\"afd..123\\\" has no defined rights for this resource.\",\n \"instance\": \"access-token\"\n }\n ]\n}\n```\n\n### For private API access (Premium)\n\nYou can create API access tokens simply in the eshop administration. Send them in the request header `Shoptet-Private-API-Token`.\nYou can automatically access all API endpoints.\n\n## Rate limiting\n\nRate limiting is only at the level of server overload protection (DDoS), whereas the quantity of queries or total volume of data are unlimited.\nThese are therefore the limits of the maximum number of coincident active connections. A maximum of 50 from a single IP address, and a maximum of\n3 connections for a single token. If the limit is exceeded, the HTTP code 429 is returned. See also Nginx configuration:\n\n```\n limit_conn per_ip 50;\n limit_conn per_token 3;\n limit_conn_status 429;\n```\n\nSome URLs, for example for bulk operations, can have their own specific limits, which are mentioned in this documentation.\n\n## Locks\n\nWrite endpoints (DELETE, PATCH, POST, PUT methods) can take longer and may be prone to two concurrent matching requests.\nTo avoid problems with retrying identical write requests, we have added the locking function of these requests to the application.\nIf you execute the same request two times in quick succession, the second request receives error response with a 423 code.\nThe lock is only valid for a specific called URL, for the duration of the request processing, but no longer than 5 seconds.\n\n## API versioning\n\nCurrent version of API: v1.0\n\nThe client must send a `Content-Type` header with value of `application/vnd.shoptet.v1.0`,\nwhere `v1.0` is the API version supported by the client. If there is any change in the API, then we are trying to make it\nreverse compatible, therefore it is not necessary to regularly update your connection after each change in our interface.\n\nThe version is the same for all endpoints described here.\n\n## Server response format\n\nAll JSON responses from the server have the same format, as a base.\nIf any of the sections is not present in the response, a `null` value is then received.\n\nExample of call for addons:\n\n```\ncurl --include \\\n -H 'Shoptet-Access-Token: 123456-a-123-XXXXXXXXXXXXXXXXXXXXXXXXX' \\\n -H 'Content-Type: application/vnd.shoptet.v1.0' \\\n 'https://api.myshoptet.com/api/eshop'\n```\n\nExample of call for private API access:\n\n```\ncurl --include \\\n -H 'Shoptet-Private-API-Token: 123456-a-123-XXXXXXXXXXXXXXXXXXXXXXXXX' \\\n -H 'Content-Type: application/vnd.shoptet.v1.0' \\\n 'https://api.myshoptet.com/api/eshop'\n```\n\nExample of response:\n\n```\nHTTP/2 200\ndate: Fri, 13 Jul 2018 15:57:29 GMT\ncontent-type: application/vnd.shoptet.v1.0+json; charset=utf-8\n\n{\n \"data\": {\n \"contactInformation\": {\n \"eshopName\": \"www.domena-eshopu.cz\",\n \"url\": \"https:\\/\\/www.domena-eshopu.cz\\/\",\n \"companyId\": \"28935675\",\n ...\n }\n ...\n },\n \"errors\": 'null'\n}\n```\n\nThe basic structure of the response in the event of an error is as follows:\n\n```\n{\n \"data\": 'null',\n \"errors\": [\n {\n \"errorCode\": \"missing-access-token\",\n \"message\": \"Missing access token. Please add `Shoptet-Access-Token` header to your request.\",\n \"instance\": \"unknown\"\n }\n ]\n}\n```\n\nMost of the endpoints are synchronous, i.e. your answer is provided immediately and contains the data requested. There\nare however some endpoints, where either the request or the response processing takes longer time. These are implemented as\n[Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/). Your request will be queued and you\nreceive only job identification in the response. You will be notified using a\n[webhook](https://developers.shoptet.com/api/documentation/webhooks/) when the job is completed and your results\ndownloadable. Be aware, that registration of webhook `job:finished` is required to be able to run asynchronous requests.\nIf webhook is not registered, you will receive an error response with HTTP status code 403 and job won't be queued.\nWebhook `job:finished` is also emitted when the job is failed so there is need to check the [Detail of job](#tag/job-endpoints/getjobdetail) to get the result of the job. If an error occurs during an asynchronous request, the job is automatically marked as failed 3 hours after its creation, and in this case, the `job:finished` webhook is not emitted.\n\nSome attributes may be added to the new API version, or the sequence of attributes can be changed.\nYour software, therefore, shall not rely on either of these.\nIf some attributes are renamed or removed, you will be informed in an additional\nheader - see also [API versioning](#section/Basic-principles-of-working-with-API/API-versioning) and [Deprecated header + Sunset](#section/Basic-principles-of-working-with-API/Deprecated-header-+-Sunset).\n\n## Deprecated header + Sunset\n\nIf you are calling some endpoint in a version that will not be supported in the future, you will receive a response with the header\n`X-Shoptet-Deprecated`. If you detect this header within the response and its presence is logged,\nyou should be aware of the support termination for a specific endpoint in advance and thus have enough time for correction.\n\nFurthermore, you shall also receive the response with a`Sunset` header with the date when the support for this endpoint is to be terminated.\n\n## Status codes\n\nWhen processing the response, the client shall first detect, what response status code was received.\n\nFor GET requests for responses with 200 code, it is not necessary to explore the `errors` part of the response.\nFor PATCH/PUT requests, which can process more records at the same time and some records\nare not processed successfully, these end with a 200 response code and the errors key contains info\n on skipped rows.\nThe unknown record is returned with a 404 code, etc. These responses have the error field filled in, where you can\nfind detailed info about the error.\n\nThe following errors might be expected:\n\n* 400 - Some of the validations on item level have failed. There is no reason to retry, it will fail always.\n\n* 401 - Invalid token or the token has expired (for addons access tokens). You have to ask for another one.\n\n* 403 - Forbidden. The token has no rights to the endpoint called. The endpoints must be allowed for an addon\n and the eshop must have approved them. Valid for addons access tokens, private tokens can always access all\n endpoints. Can be also returned when required module for request is missing.\n* 404 - Either the endpoint is wrong; or most commonly, an entity identifier, which is part of the URL, does\n not exist.\n* 409 - Conflict - the action could not be completed for some consistency rules, such as duplicate data\n or relation, which would be broken.\n* 413 - Payload too large - update requests can sometimes contain multiple entities to be amended. There is\n however a limit (varying for each request), how many can be specified within one request. If you breach the\n limit, you will get this error and nothing will be updated.\n* 422 - Unprocessable entity - we were not able to parse the request - it does not match the expected format.\n Something is wrong with the request as whole, it might not be a correct JSON or it does not match the expected\n JSON schema. There is no reason to retry, it will always fail.\n* 423 - Locked - for update and some read request we apply locks, usually on an URL level, which should avoid\n consistency problems possibly occuring from parallel updates. See [chapter about locks](#section/Basic-principles-of-working-with-API/Locks). Retry later,\n try to avoid parallel update requests.\n* 500 - General server error. Yes, this might happen to our software, too. Most commonly this is a temporary\n database issue and it might (but might not), work a few minutes later. We monitor all such errors and we\n try to analyze and fix them.\n* 503 - System maintenance. Most commonly we move a database to another database cluster or a database migration is\n pending and it will be available in a few minutes. Please try later.\n\n## Paging\n\nSome endpoints can return larger quantity of records. Such endpoints do not return the entire result, but support pagination of results.\nYou can page using `page` (int) and `itemsPerPage` (int) parameters. The first page has number 1. If you require a different\nquantity of items per page, use the `itemsPerPage` parameter. CAUTION: the number of items per page can be decreased only, the default\nvalue is maximum. The default value can be different for each endpoint.\n\nWhen paging, check the total number of items, if not altered (`totalCount`), then the\nitems on pages could be shifted and some of them could be missed or processed twice.\n\n## Section on demand\n\nSome endpoints return the data sections as optional, on demand. The request is done by giving the section name in the\n`include` parameter. Part of the data is returned each time, the other section only on demand. This makes the responses smaller for those, who do not need the data\n, thus saving the volume of data transmitted and shortening the time to process the request.\n\nFor example, for \"Eshop Info\" endpoint, you will gain basic info when simply calling `[GET] /api/eshop`, but payment\nmethods and transport options only when using `[GET] /api/eshop?include=paymentMethods,shippingMethods`.\n\nMore values are separated by a comma, no sequencing, no upper/lower case differentiation. Other blocks are available on demand\nand each endpoint informs you which identifier to request.\n\n## Translations\n\nFor proper functionality in translations you will have to get module Foreign languages (Cizí jazyky) activated on customer e-shop. Multi-language support in API is handled by query parameter `language`, which can be used in whole API. If parameter is not set, default shop language is used.\nRead endpoints (HTTP verb GET) will return corresponding language version of texts where applicable.\n\nFor write endpoints, first use POST endpoint to create entity and then use PATCH endpoint with corresponding language query parameter to set language fields.\n\nPlease note that in some endpoints (typically surcharge/filtering/variant parameters) you must use the identifier's currently selected language variant (which is filtered in list).\n\n## Files\n\nFor files upload, there are [Files endpoints](#tag/Files).\n\nThe file is uploaded to a temporary storage which is not accessible publicly. The file is kept there for 7 days and then deleted.\n\nAfter you upload a file, you may copy it to some API entities in their endpoints - you specify filename returned in response of upload job.\n\nPlease note that currently only images (png, jpg, gif) are allowed filetypes for file upload.\n\n# Product images\n\nShoptet saves the product images in their original size and then prepares several sizes for standardized usage (called\nimage cuts). These cuts are created in advance and saved on the disk, so they are readily available. The list of cuts is\nthe same for each e-shop, and each e-shop can theoretically have different cut sizes. In practice, their size is given\nby the template and most templates use the same sizes. The list of provided cuts is given by\nthe [Image cuts](#section/Code-lists/Image-cuts) code list.\n\nThe `/api/eshop?include=imageCuts` endpoint returns the `imageCuts` field in the response, where each cut has the actual\nsize defined, and the URL base path. There are two base URLs (example for classic.shoptet.cz, cut `detail`):\n\n- `urlPath`: \"https://classic.shoptet.cz/user/shop/detail/\"\n\n- `cdnPath`: \"https://cdn-api.myshoptet.com/usr/classic.shoptet.cz/user/shop/detail/\"\n\nUse the `urlPath` in case you need an up-to-date image right now. Use the url for your backend processing and you\nwill retrieve the images only once. Images retrieved via `urlPath` are not cached. You can use image name or SEO version\nof the image name - see below.\n\nUse the `cdnPath` in case you want to use the image url on the frontend and users of your application will display it,\ne.g. if you provide an alternative frontend, mobile application etc. The images are cached and provided with lower\nlatency. Use `cdnName` retrieved from the product detail endpoint (or similar) - see below.\n\nOnce you determine the URL based on the purpose and image cut size (for example `detail` for product detail, or `related`\nfor product preview), just append the filename you need. The filename can be retrieved from Product detail endpoint.\n\nAlthough the e-shop is behind the content delivery network (Cloudflare CDN), API still returns the same domain. Whether\nthe e-shop is behind the Cloudflare CDN, you can find out from response headers (`CDN-Loop: cloudflare` header).\n\nThe product detail endpoint `/api/products/{guid}?include=images` returns the image field `data.images[]` in the same\nsequence, as these are entered in administration. The file name `name` (for example `100.jpg`) needs to be connected\nto the URL cut and then you have complete path to the image of a given cut (size), for example\n`https://classic.shoptet.cz/user/shop/detail/100.jpg`. You can also use `seoName`, which also contains a description\nof the image - you will be redirected to the same image. The `cdnName` is intended for use with the `cdnUrl` only.\nThe fields look like: (excerpt)\n\n```json\n \"name\": \"106.png\",\n \"description\": \"shamrock 2115611 640\",\n \"seoName\": \"106_shamrock-2115611-640.png\",\n \"cdnName\": \"106_shamrock-2115611-640.png?5b2a41f5\"\n```\n\nOne of the images mentioned for the product can be selected as the default image for the product variant. The selected\nimage is in `data.variants[].image` item and contains the name of the image – this can be searched for in the image\nlist, in the `name` item. Should the variant have no preselected default image, the parameter `image` is `null`.\nIf `data.variants[].isProductDefaultImage` is true, then the default product image is given. If it is `false`, then it is the default variant image.\nThe item `data.items[].mainImage` contains the main image in order detail - this is either a default variant image,\nor, if not set (or product does not have variants), the default product image is given. The structure is the same as\nin product details, but not all images are given here, only the default one – representative image. The full path can\nbe gained by assembling the `urlPath` from the e-shop info and the `name` or `seoName` items, given for the order item.\n\nSimilarly, the product list gives `data.products[].mainImage`, which mentions the initial image for each product.\n\n# Code lists\n\n## Image cuts\n\nValue | Description\n-------- | ---------\norig | original image (in the original resolution)\nbig | big image (typically 1024x768 px)\ndetail |image detail (typically 360x270 px)\ncategory | size for listing in category (typically 216x105 px)\n\n## Product visibility\n\nValue | Description\n-------- | ---------\nhidden | Hide product\nvisible | Show product\nblocked | Cannot be ordered\nshow-registered | Show only to logged-in users\nblock-unregistered | Do not allow order to logged-out users\ncash-desk-only | Show only in cash desk\ndetail-only | Do not show e-shop navigation\n\n## Product types\n\nValue | Description\n-------- | ---------\nproduct | Product\nbazar | Second-hand product\nservice | Service\ngift-certificate | Gift (deprecated)\nproduct-set | Product set\n\n## Types of order items\n\nValue | Description\n-------- | ---------\nproduct | Product\nbazar | Second-hand product\nservice | Service\nshipping | Transportation\nbilling | Payment method\ndiscount-coupon | Discount coupon\nvolume-discount | Volume discount\ngift | Gift\ngift-certificate | Gift certificate\ngeneric-item | Non-specific item\nproduct-set | Product set\nproduct-set-item | Product set item\ndeposit | Deposit\n\n## Sorting of products in category\n\nValue | Description\n-------- | ---------\ndefault | Default\nmost-selling | Most selling first\ncheapest | Cheapest first\nmost-expensive | Most expensive first\noldest | Oldest first\nnewest | Newest first\nalphabetically | Alphabetically\nalphabetically-desc | Alphabetically, descending\nproduct-code | Per product code\nproduct-code-desc | Per product code, descending\ncategory-priority | Category priority\ncategory-priority-desc | Category priority, descending\n\n## Webhook event types\n\nValue | Description | Identifier meaning\n-------- | --------- | ---------\nbrand:create | Brand creation event | String (`code`) - brand unique code\nbrand:update | Brand change event | String (`code`) - brand unique code\nbrand:delete | Brand deleting event | String (`code`) - brand unique code\ncreditNote:create | Credit note creation event | Number (`code`) of credit note\ncreditNote:delete | Credit note deleting event | Number (`code`) of credit note\ncreditNote:update | Credit note change event | Number (`code`) of credit note\ncustomer:create | New customer was created | Customer GUID\ncustomer:update | Customer was updated. Throws `409 Conflict` when try to register simultaneously with `customer:disableOrders` or `customer:enableOrders` | Customer GUID\ncustomer:disableOrders | An event disabled the customer, and his future orders will be automatically cancelled. Throws `409 Conflict` when try to register simultaneously with `customer:update` | Customer GUID\ncustomer:enableOrders | An event enabled the customer's future orders. Throws `409 Conflict` when try to register simultaneously with `customer:update` | Customer GUID\ncustomer:import | Import of 1 and more customers was executed | Fixed string \"customers\"\ncustomer:delete | Customer was deleted | Customer GUID\ndeliveryNote:create | Delivery note creation event | Number (`code`) of delivery note\ndeliveryNote:delete | Delivery note deleting event | Number (`code`) of delivery note\ndeliveryNote:update | Delivery note change event | Number (`code`) of delivery note\neshop:currencies | Currencies settings change event | ID of eshop\neshop:billingInformation | Billing information (i.e. eshop billing address) change event | ID of eshop\neshop:design | Design settings (template, colors, fonts, layout) | ID of eshop\neshop:mandatoryFields | Mandatory fields of customer were updated | ID of eshop\neshop:projectDomain | Domain of eshop was changed | ID of eshop\ninvoice:create | Invoice creation event | Number (`code`) of invoice\ninvoice:delete | Invoice deleting event | Number (`code`) of invoice\ninvoice:update | Invoice change event | Number (`code`) of invoice\njob:finished | The asynchronous request was finished | Job `id`\nmailingListEmail:create | E-mail addition event into the e-mail distribution list | Name (`code`) of e-mail distribution list\nmailingListEmail:delete | E-mail deleting event from the e-mail distribution list | Name (`code`) of e-mail distribution\norder:cancel | Order cancel event. Webhook is emitted when order status is set to `canceled`. Throws `409 Conflict` when try to register simultaneously with `order:update` | Number (`code`) of order\norder:create | Order creation event | Number (`code`) of order\norder:delete | Order deleting event | Number (`code`) of order\norder:update | Order change event. Throws `409 Conflict` when try to register simultaneously with `order:cancel` | Number (`code`) of order\norderStatusesList:change | Order status list change event. Emitted when order status is created, updated or deleted | Order status `ID`\npaymentMethod:change | Payment method change event | Payment method GUID\nproformaInvoice:create | Proforma invoice creation event | Number (`code`) of proforma invoice\nproformaInvoice:delete | Proforma invoice deleting event | Number (`code`) of proforma invoice\nproformaInvoice:update | Proforma invoice change event | Number (`code`) of proforma invoice\nproofPayment:create | Proof of payment creation event | Number (`code`) of proof payment\nproofPayment:delete | Proof of payment deleting event | Number (`code`) of proof payment\nproofPayment:update | Proof of payment change event | Number (`code`) of proof payment\nshippingMethod:change | Shipping method change event | Shipping method GUID\nshippingRequest:cancelled | Shipping request was not chosen for order delivery | `shippingRequestCode` associated with the cart\nshippingRequest:confirmed | Shipping request was chosen for order delivery | `shippingRequestCode` associated with the cart\nstock:movement | Stock change event | Stock ID\nstock:inStock (*) | Stock change event - sum across all of the stocks raised above 0 (beta, see below) | Number (`code`) of product\nstock:soldOut (*) | Stock change event - sum across all of the stocks reached 0 (beta, see below) | Number (`code`) of product\nstock:minStockSupplyReached (*) | Stock change event - sum across all of the stocks reached minimum stock supply value, if this limit is set for product (beta, see below) | Number (`code`) of product\n(*) These webhooks are considered beta/experimental, for more information, please visit the X-url\n### Mass Webhooks\n\nThese webhooks are sent when a mass change of entities is performed. The payload contains a json serialized list of IDs of changed entities.\nPurpose of these webhooks is to downgrade number of requests, while i.e. administrator performs mass change of orders status at once etc.\nSo instead of emitting one event for every order, we emit one event for all of them.\n\nFor now, if some mass event is performed, we also sent \"single\" webhook event for every updated entity as usual, but it will be changed in future,\nso please watch [release changes](https://developers.shoptet.com/category/api/) for more info \n\nValue | Description | Identifier meaning\n-------- | --------- | ---------\ninvoice:massUpdate | Mass change of invoices event | Json serialized list of number (`code`) of invoices\norder:massUpdate | Mass change of orders event | Json serialized list of number (`code`) of orders\n\n### System Webhooks\n\nThese webhooks cannot be registered via API, they are setup in Partners' Addon administration section instead.\n\nValue | Description\n----- | -----------\naddon:suspend | The addon was suspended by the eshop or by Shoptet operations staff\naddon:approve | The addon was approved (resumed) after it was suspended\naddon:uninstall | The addon was uninstalled by the eshop admin or the eshop was terminated\n\n## URL address from endpoint Eshop info\nSee endpoint [Eshop info](#tag/Eshop)\nIdent | Description\n------| -----\nadmin-orders-list | Listing of orders in administration\nadmin-customers-list | List of customers in administration\noauth | OAuth server address, used for [e-shop user verification](https://developers.shoptet.com/api/documentation/eshop-verification-using-oauth/)\n\n## List of product catalogues\n\nProvider (identification) | Description\n------| -----\nglami | Glami\ngoogle | Google\nheureka | Heuréka\nzbozi | Zboží.cz\n\n## Invoice Billing Methods\n\nid | Description\n------| -----\n1 | COD (cz: Dobírka)\n2 | Wire transfer (cz: Převodem)\n3 | Cash (cz: Hotově)\n4 | Card (cz: Kartou)\n## VAT modes\n \n \nValue |\n------|\nNormal |\nOne Stop Shop |\nMini One Stop Shop |\n \nReverse charge |\n \nOutside the EU |\n\n# Postman collection for Shoptet API\n\nIf you use Postman as an API platform for building and using APIs, we provide you a complex collection of Shoptet API.\nYou have 2 options how to import our postman collection (created from [openApi schema](https://swagger.io/specification/) - openapi.yaml ) into your postman client\n\n## Fork Shoptet API Collection from Shoptet Public API Workspace (recommended)\n\nSee [Shoptet Public API Workspace](https://www.postman.com/shoptet-developers/shoptet-public-api-workspace).\nAlso check postman documentation for more details: [Fork a collection](https://learning.postman.com/docs/collaborating-in-postman/using-version-control/forking-elements/).\n\n### Step 1: Navigate to Shoptet Public API Workspace\n\n- Launch Postman on your desktop or in the browser.\n- In the search bar in the top header of app, type **Shoptet Public API** and select collection from Shoptet public API Workspace.\n\n### Step 2: Locate the Shoptet API Collection\n\n- Once inside the Shoptet Public API Workspace, go to the **Collections** tab.\n- Find the **Shoptet API** collection.\n\n### Step 3: Fork the Collection\n\n- Click on the **Shoptet API** collection to open it.\n- In the collection view, click the **Fork** button in the top-right corner.\n- In the fork dialog, choose a name for your forked collection.\n- Select the workspace where you want to save the forked collection.\n- **It’s recommended to check `watch original collection` to get notified about changes in the original collection.**\n- Click **Fork Collection**.\n\n### Step 4: Access Your Forked Collection\n\n- Navigate to the workspace where you saved the forked collection.\n- You’ll now find the forked **Shoptet API** collection under the **Collections** tab, ready for you to use and modify.\nNow you have your own copy of the Shoptet API collection! If you want to add changes from the original collection, you can do so by click on `pull changes` in collection settings.\n\n## Import openapi.yaml into Postman as a Collection\n\n### Step 1: Upload the `openapi.yaml` File\n\n- Download the [openapi.yaml](https://github.com/shoptet/developers/blob/master/openapi/openapi.yaml) file from our developers [repository](https://github.com/shoptet/developers).\n- Launch Postman on your desktop or in the browser.\n- In the top-left corner of Postman, click the **Import** button.\n- A pop-up window will appear.\n- Drag and drop your `openapi.yaml` file into the window, or click **Upload Files** and browse to the file's location.\n\n### Step 2: Verify OpenAPI Import\n\n- Postman will automatically recognize the OpenAPI schema.\n- It will display a preview of the API schema.\n\n### Step 3: Import as Collection\n\n- Once the file is recognized, click **Import**.\n- Postman will convert the OpenAPI schema into a collection of requests, based on the defined endpoints in the `openapi.yaml` file.\n\n### Step 4: Access the Imported Collection\n\n- After the import is successful, go to the **Collections** tab.\n- You’ll find your new collection, named after the OpenAPI schema, containing all the API requests generated from the file.\n\nNow you can explore the API endpoints and use them directly within Postman!\n## Collection settings\n1. Click the **Shoptet API** collection name.\n2. Go to **Authorization** tab.\n3. Set your access token into the `value` of `Shoptet-Access-Token` key.\n4. Go to **Variables** tab.\n5. You can set `baseUrl` variable here.\n# Last changes\n\nLast API changes are published on the [API news] page (https://developers.shoptet.com/category/api/)." servers: - url: 'https://api.myshoptet.com'