From 7c51f995a697e2a90b9242f514d6dff129bfe5f2 Mon Sep 17 00:00:00 2001 From: github-actions Date: Wed, 30 Oct 2024 10:53:06 +0000 Subject: [PATCH] feat: Update OpenAPI file replicated from CMS4 --- openapi/openapi.yaml | 4424 ++++++++++++++++++++++++++++++++++++++---- openapi/redocly.yaml | 14 +- 2 files changed, 4080 insertions(+), 358 deletions(-) diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index 6ab40cd..797d2a9 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -2,10 +2,1358 @@ 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\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:terminate | The addon was terminated by the eshop or by Shoptet operations staff\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\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. + + + + + This documentation provides information about the interface for developers + who would like to gain access to Shoptet + + e-shops. For more information about Shoptet, see https://www.shoptet.cz/. + + + The API is available in two access modes: + + + - for "Shoptet partner” developers who create the interconnection with the + services and extend the Shoptet system's + functions for public usage. For more information about API and conditions, under which + it can be used, see https://developers.shoptet.com/addons/. + + - direct private access to eshop data for eshop owner - available only for + [Premium Members](https://www.shoptetpremium.cz/). + See https://developers.shoptet.com/premium for more information about API access. + + # Basic principles + + + ## How to call API + + + API supports communication in JSON format. The URL for calling API requests + is https://api.myshoptet.com. The API calls + + (endpoints and message formats) are common for private as well as addons + access, it however uses different authentication + + and authorization principles. + + + ### For Addons + + + API is made to create the supplements for the Shoptet system and uses OAuth2 + authorization principles. + + To access the API it is necessary to implement a web service at your side, + which will communicate with our OAuth server. + + + In 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. + + Here, you will find your clientID and addresses, from where you can call our + OAuth server. + + + The 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.) + + In 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. + + At 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). + + The `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`. + + Such a request shall follow within the same script that received the `code`. + + Do 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. + + The address for you to call, and an example of implementation, can be found + in e-shop administration in the `Access to API` section. + + + As 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 + + for communication between the servers and for gaining the temporary token + for access to API. + + + If you have successfully received an OAuth access token, your script must + end with the HTTP status code “200”. + + + Now 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. + + + From your server, call + `https:///action/ApiOAuthServer/getAccessToken` address + with HTTP header `Authorization: Bearer `. + + As 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. + + It is possible to request a maximum of 5 valid tokens. + + + The 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`. + + You 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. + + + ``` + + { + "data": 'null', + "errors": [ + { + "errorCode": "expired-token", + "message": "Token is expired. Please ask for new one.", + "instance": "unknown" + } + ] + } + + ``` + + + If your token does not have the access right for a specific endpoint, you + will obtain a reply with HTTP status code 403 Forbidden. + + + ``` + + { + "data": 'null', + "errors": [ + { + "errorCode": "invalid-token-no-rights", + "message": "Your access token \"afd..123\" has no defined rights for this resource.", + "instance": "access-token" + } + ] + } + + ``` + + + ### For private API access (Premium) + + + You can create API access tokens simply in the eshop administration. Send + them in the request header `Shoptet-Private-API-Token`. + + You can automatically access all API endpoints. + + + ## Rate limiting + + + Rate limiting is only at the level of server overload protection (DDoS), + whereas the quantity of queries or total volume of data are unlimited. + + These 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 + + 3 connections for a single token. If the limit is exceeded, the HTTP code + 429 is returned. See also Nginx configuration: + + + ``` + limit_conn per_ip 50; + limit_conn per_token 3; + limit_conn_status 429; + ``` + + + Some URLs, for example for bulk operations, can have their own specific + limits, which are mentioned in this documentation. + + + ## Locks + + + Write endpoints (DELETE, PATCH, POST, PUT methods) can take longer and may + be prone to two concurrent matching requests. + + To avoid problems with retrying identical write requests, we have added the + locking function of these requests to the application. + + If you execute the same request two times in quick succession, the second + request receives error response with a 423 code. + + The lock is only valid for a specific called URL, for the duration of the + request processing, but no longer than 5 seconds. + + + ## API versioning + + + Current version of API: v1.0 + + + The client must send a `Content-Type` header with value of + `application/vnd.shoptet.v1.0`, + + where `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 + + reverse compatible, therefore it is not necessary to regularly update your + connection after each change in our interface. + + + The version is the same for all endpoints described here. + + + ## Server response format + + + All JSON responses from the server have the same format, as a base. + + If any of the sections is not present in the response, a `null` value is + then received. + + + Example of call for addons: + + + ``` + + curl --include \ + -H 'Shoptet-Access-Token: 123456-a-123-XXXXXXXXXXXXXXXXXXXXXXXXX' \ + -H 'Content-Type: application/vnd.shoptet.v1.0' \ + 'https://api.myshoptet.com/api/eshop' + ``` + + + Example of call for private API access: + + + ``` + + curl --include \ + -H 'Shoptet-Private-API-Token: 123456-a-123-XXXXXXXXXXXXXXXXXXXXXXXXX' \ + -H 'Content-Type: application/vnd.shoptet.v1.0' \ + 'https://api.myshoptet.com/api/eshop' + ``` + + + Example of response: + + + ``` + + HTTP/2 200 + + date: Fri, 13 Jul 2018 15:57:29 GMT + + content-type: application/vnd.shoptet.v1.0+json; charset=utf-8 + + + { + "data": { + "contactInformation": { + "eshopName": "www.domena-eshopu.cz", + "url": "https:\/\/www.domena-eshopu.cz\/", + "companyId": "28935675", + ... + } + ... + }, + "errors": 'null' + } + + ``` + + + The basic structure of the response in the event of an error is as follows: + + + ``` + + { + "data": 'null', + "errors": [ + { + "errorCode": "missing-access-token", + "message": "Missing access token. Please add `Shoptet-Access-Token` header to your request.", + "instance": "unknown" + } + ] + } + + ``` + + + Most of the endpoints are synchronous, i.e. your answer is provided + immediately and contains the data requested. There + + are however some endpoints, where either the request or the response + processing takes longer time. These are implemented as + + [Asynchronous + requests](https://developers.shoptet.com/asynchronous-requests/). Your + request will be queued and you + + receive only job identification in the response. You will be notified using + a + + [webhook](https://developers.shoptet.com/api/documentation/webhooks/) when + the job is completed and your results + + downloadable. Be aware, that registration of webhook `job:finished` is + required to be able to run asynchronous requests. + + If webhook is not registered, you will receive an error response with HTTP + status code 403 and job won't be queued. + + Webhook `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. + + + Some attributes may be added to the new API version, or the sequence of + attributes can be changed. + + Your software, therefore, shall not rely on either of these. + + If some attributes are renamed or removed, you will be informed in an + additional + + header - 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). + + + ## Deprecated header + Sunset + + + If you are calling some endpoint in a version that will not be supported in + the future, you will receive a response with the header + + `X-Shoptet-Deprecated`. If you detect this header within the response and + its presence is logged, + + you should be aware of the support termination for a specific endpoint in + advance and thus have enough time for correction. + + + Furthermore, you shall also receive the response with a`Sunset` header with + the date when the support for this endpoint is to be terminated. + + + ## Status codes + + + When processing the response, the client shall first detect, what response + status code was received. + + + For GET requests for responses with 200 code, it is not necessary to explore + the `errors` part of the response. + + For PATCH/PUT requests, which can process more records at the same time and + some records + + are not processed successfully, these end with a 200 response code and the + errors key contains info + on skipped rows. + + The unknown record is returned with a 404 code, etc. These responses have + the error field filled in, where you can + + find detailed info about the error. + + + The following errors might be expected: + + + * 400 - Some of the validations on item level have failed. There is no + reason to retry, it will fail always. + + + * 401 - Invalid token or the token has expired (for addons access tokens). + You have to ask for another one. + + + * 403 - Forbidden. The token has no rights to the endpoint called. The + endpoints must be allowed for an addon + and the eshop must have approved them. Valid for addons access tokens, private tokens can always access all + endpoints. Can be also returned when required module for request is missing. + + * 404 - Either the endpoint is wrong; or most commonly, an entity + identifier, which is part of the URL, does + not exist. + + * 409 - Conflict - the action could not be completed for some consistency + rules, such as duplicate data + or relation, which would be broken. + + * 413 - Payload too large - update requests can sometimes contain multiple + entities to be amended. There is + however a limit (varying for each request), how many can be specified within one request. If you breach the + limit, you will get this error and nothing will be updated. + + * 422 - Unprocessable entity - we were not able to parse the request - it + does not match the expected format. + Something is wrong with the request as whole, it might not be a correct JSON or it does not match the expected + JSON schema. There is no reason to retry, it will always fail. + + * 423 - Locked - for update and some read request we apply locks, usually on + an URL level, which should avoid + consistency problems possibly occuring from parallel updates. See [chapter about locks](#section/Basic-principles-of-working-with-API/Locks). Retry later, + try to avoid parallel update requests. + + * 500 - General server error. Yes, this might happen to our software, too. + Most commonly this is a temporary + database issue and it might (but might not), work a few minutes later. We monitor all such errors and we + try to analyze and fix them. + + * 503 - System maintenance. Most commonly we move a database to another + database cluster or a database migration is + pending and it will be available in a few minutes. Please try later. + + + ## Paging + + + Some endpoints can return larger quantity of records. Such endpoints do not + return the entire result, but support pagination of results. + + You can page using `page` (int) and `itemsPerPage` (int) parameters. The + first page has number 1. If you require a different + + quantity of items per page, use the `itemsPerPage` parameter. CAUTION: the + number of items per page can be decreased only, the default + + value is maximum. The default value can be different for each endpoint. + + + When paging, check the total number of items, if not altered (`totalCount`), + then the + + items on pages could be shifted and some of them could be missed or + processed twice. + + + ## Section on demand + + + Some endpoints return the data sections as optional, on demand. The request + is done by giving the section name in the + + `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 + + , thus saving the volume of data transmitted and shortening the time to + process the request. + + + For example, for "Eshop Info" endpoint, you will gain basic info when simply + calling `[GET] /api/eshop`, but payment + + methods and transport options only when using `[GET] + /api/eshop?include=paymentMethods,shippingMethods`. + + + More values are separated by a comma, no sequencing, no upper/lower case + differentiation. Other blocks are available on demand + + and each endpoint informs you which identifier to request. + + + ## Translations + + + For 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. + + Read endpoints (HTTP verb GET) will return corresponding language version of + texts where applicable. + + + For write endpoints, first use POST endpoint to create entity and then use + PATCH endpoint with corresponding language query parameter to set language + fields. + + + Please 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). + + + ## Files + + + For files upload, there are [Files endpoints](#tag/Files). + + + The file is uploaded to a temporary storage which is not accessible + publicly. The file is kept there for 7 days and then deleted. + + + After you upload a file, you may copy it to some API entities in their + endpoints - you specify filename returned in response of upload job. + + + Please note that currently only images (png, jpg, gif) are allowed filetypes + for file upload. + + + # Product images + + + Shoptet saves the product images in their original size and then prepares + several sizes for standardized usage (called + + image cuts). These cuts are created in advance and saved on the disk, so + they are readily available. The list of cuts is + + the same for each e-shop, and each e-shop can theoretically have different + cut sizes. In practice, their size is given + + by the template and most templates use the same sizes. The list of provided + cuts is given by + + the [Image cuts](#section/Code-lists/Image-cuts) code list. + + + The `/api/eshop?include=imageCuts` endpoint returns the `imageCuts` field in + the response, where each cut has the actual + + size defined, and the URL base path. There are two base URLs (example for + classic.shoptet.cz, cut `detail`): + + + - `urlPath`: "https://classic.shoptet.cz/user/shop/detail/" + + + - `cdnPath`: + "https://cdn-api.myshoptet.com/usr/classic.shoptet.cz/user/shop/detail/" + + + Use the `urlPath` in case you need an up-to-date image right now. Use the + url for your backend processing and you + + will retrieve the images only once. Images retrieved via `urlPath` are not + cached. You can use image name or SEO version + + of the image name - see below. + + + Use the `cdnPath` in case you want to use the image url on the frontend and + users of your application will display it, + + e.g. if you provide an alternative frontend, mobile application etc. The + images are cached and provided with lower + + latency. Use `cdnName` retrieved from the product detail endpoint (or + similar) - see below. + + + Once you determine the URL based on the purpose and image cut size (for + example `detail` for product detail, or `related` + + for product preview), just append the filename you need. The filename can be + retrieved from Product detail endpoint. + + + Although the e-shop is behind the content delivery network (Cloudflare CDN), + API still returns the same domain. Whether + + the e-shop is behind the Cloudflare CDN, you can find out from response + headers (`CDN-Loop: cloudflare` header). + + + The product detail endpoint `/api/products/{guid}?include=images` returns + the image field `data.images[]` in the same + + sequence, as these are entered in administration. The file name `name` (for + example `100.jpg`) needs to be connected + + to the URL cut and then you have complete path to the image of a given cut + (size), for example + + `https://classic.shoptet.cz/user/shop/detail/100.jpg`. You can also use + `seoName`, which also contains a description + + of the image - you will be redirected to the same image. The `cdnName` is + intended for use with the `cdnUrl` only. + + The fields look like: (excerpt) + + + ```json + "name": "106.png", + "description": "shamrock 2115611 640", + "seoName": "106_shamrock-2115611-640.png", + "cdnName": "106_shamrock-2115611-640.png?5b2a41f5" + ``` + + + One of the images mentioned for the product can be selected as the default + image for the product variant. The selected + + image is in `data.variants[].image` item and contains the name of the image + – this can be searched for in the image + + list, in the `name` item. Should the variant have no preselected default + image, the parameter `image` is `null`. + + If `data.variants[].isProductDefaultImage` is true, then the default product image is given. If it is `false`, then + it is the default variant image. + + The item `data.items[].mainImage` contains the main image in order detail - + this is either a default variant image, + + or, if not set (or product does not have variants), the default product + image is given. The structure is the same as + + in product details, but not all images are given here, only the default one + – representative image. The full path can + + be gained by assembling the `urlPath` from the e-shop info and the `name` or + `seoName` items, given for the order item. + + + Similarly, the product list gives `data.products[].mainImage`, which + mentions the initial image for each product. + + + # Code lists + + + ## Image cuts + + + Value | Description + + -------- | --------- + + orig | original image (in the original resolution) + + big | big image (typically 1024x768 px) + + detail |image detail (typically 360x270 px) + + category | size for listing in category (typically 216x105 px) + + + ## Product visibility + + + Value | Description + + -------- | --------- + + hidden | Hide product + + visible | Show product + + blocked | Cannot be ordered + + show-registered | Show only to logged-in users + + block-unregistered | Do not allow order to logged-out users + + cash-desk-only | Show only in cash desk + + detail-only | Do not show e-shop navigation + + + ## Product types + + + Value | Description + + -------- | --------- + + product | Product + + bazar | Second-hand product + + service | Service + + gift-certificate | Gift (deprecated) + + product-set | Product set + + + ## Types of order items + + + Value | Description + + -------- | --------- + + product | Product + + bazar | Second-hand product + + service | Service + + shipping | Transportation + + billing | Payment method + + discount-coupon | Discount coupon + + volume-discount | Volume discount + + gift | Gift + + gift-certificate | Gift certificate + + generic-item | Non-specific item + + product-set | Product set + + product-set-item | Product set item + + deposit | Deposit + + + ## Sorting of products in category + + + Value | Description + + -------- | --------- + + default | Default + + most-selling | Most selling first + + cheapest | Cheapest first + + most-expensive | Most expensive first + + oldest | Oldest first + + newest | Newest first + + alphabetically | Alphabetically + + alphabetically-desc | Alphabetically, descending + + product-code | Per product code + + product-code-desc | Per product code, descending + + category-priority | Category priority + + category-priority-desc | Category priority, descending + + + ## Webhook event types + + + Value | Description | Identifier meaning + + -------- | --------- | --------- + + brand:create | Brand creation event | String (`code`) - brand unique code + + brand:update | Brand change event | String (`code`) - brand unique code + + brand:delete | Brand deleting event | String (`code`) - brand unique code + + creditNote:create | Credit note creation event | Number (`code`) of credit + note + + creditNote:delete | Credit note deleting event | Number (`code`) of credit + note + + creditNote:update | Credit note change event | Number (`code`) of credit + note + + customer:create | New customer was created | Customer GUID + + customer:update | Customer was updated. Throws `409 Conflict` when try to register simultaneously with `customer:disableOrders` or `customer:enableOrders` | Customer GUID + + customer: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 + + customer:enableOrders | An event enabled the customer's future orders. Throws `409 Conflict` when try to register simultaneously with `customer:update` | Customer GUID + + customer:import | Import of 1 and more customers was executed | Fixed string + "customers" + + customer:delete | Customer was deleted | Customer GUID + + deliveryNote:create | Delivery note creation event | Number (`code`) of + delivery note + + deliveryNote:delete | Delivery note deleting event | Number (`code`) of + delivery note + + deliveryNote:update | Delivery note change event | Number (`code`) of + delivery note + + eshop:currencies | Currencies settings change event | ID of eshop + + eshop:billingInformation | Billing information (i.e. eshop billing address) change event | ID of eshop + + eshop:design | Design settings (template, colors, fonts, layout) | ID of + eshop + + eshop:mandatoryFields | Mandatory fields of customer were updated | ID of + eshop + + eshop:projectDomain | Domain of eshop was changed | ID of eshop + + invoice:create | Invoice creation event | Number (`code`) of invoice + + invoice:delete | Invoice deleting event | Number (`code`) of invoice + + invoice:update | Invoice change event | Number (`code`) of invoice + + job:finished | The asynchronous request was finished | Job `id` + + mailingListEmail:create | E-mail addition event into the e-mail distribution + list | Name (`code`) of e-mail distribution list + + mailingListEmail:delete | E-mail deleting event from the e-mail distribution + list | Name (`code`) of e-mail distribution + + order: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 + + order:create | Order creation event | Number (`code`) of order + + order:delete | Order deleting event | Number (`code`) of order + + order:update | Order change event. Throws `409 Conflict` when try to register simultaneously with `order:cancel` | Number (`code`) of order + + orderStatusesList:change | Order status list change event. Emitted when order status is created, updated or deleted | Order status `ID` + + paymentMethod:change | Payment method change event | Payment method GUID + + proformaInvoice:create | Proforma invoice creation event | Number (`code`) + of proforma invoice + + proformaInvoice:delete | Proforma invoice deleting event | Number (`code`) + of proforma invoice + + proformaInvoice:update | Proforma invoice change event | Number (`code`) + of proforma invoice + + proofPayment:create | Proof of payment creation event | Number (`code`) of proof payment + + proofPayment:delete | Proof of payment deleting event | Number (`code`) of proof payment + + proofPayment:update | Proof of payment change event | Number (`code`) of proof payment + + shippingMethod:change | Shipping method change event | Shipping method GUID + + shippingRequest:cancelled | Shipping request was not chosen for order + delivery | `shippingRequestCode` associated with the cart + + shippingRequest:confirmed | Shipping request was chosen for order delivery | + `shippingRequestCode` associated with the cart + + stock:movement | Stock change event | Stock ID + + stock:inStock (*) | Stock change event - sum across all of the stocks raised above 0 (beta, see below) | Number (`code`) of product + + stock:soldOut (*) | Stock change event - sum across all of the stocks reached 0 (beta, see below) | Number (`code`) of product + + stock: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 + + (*) These webhooks are considered beta/experimental, for more information, please visit the X-url + + ### Mass Webhooks + + + These webhooks are sent when a mass change of entities is performed. The + payload contains a json serialized list of IDs of changed entities. + + Purpose of these webhooks is to downgrade number of requests, while i.e. + administrator performs mass change of orders status at once etc. + + So instead of emitting one event for every order, we emit one event for all + of them. + + + For 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, + + so please watch [release + changes](https://developers.shoptet.com/category/api/) for more info + + + + Value | Description | Identifier meaning + + -------- | --------- | --------- + + invoice:massUpdate | Mass change of invoices event | Json serialized + list of number (`code`) of invoices + + order:massUpdate | Mass change of orders event | Json serialized list + of number (`code`) of orders + + + ### System Webhooks + + + These webhooks cannot be registered via API, they are setup in Partners' + Addon administration section instead. + + + Value | Description + + ----- | ----------- + + addon:suspend | The addon was suspended by the eshop or by Shoptet + operations staff + + addon:approve | The addon was approved (resumed) after it was suspended + + addon:terminate | The addon was terminated by the eshop or by Shoptet + operations staff + + addon:uninstall | The addon was uninstalled by the eshop admin or the eshop + was terminated + + + ## URL address from endpoint Eshop info + + See endpoint [Eshop info](#tag/Eshop) + + Ident | Description + + ------| ----- + + admin-orders-list | Listing of orders in administration + + admin-customers-list | List of customers in administration + + oauth | OAuth server address, used for [e-shop user + verification](https://developers.shoptet.com/api/documentation/eshop-verification-using-oauth/) + + + ## List of product catalogues + + + Provider (identification) | Description + + ------| ----- + + glami | Glami + + google | Google + + heureka | Heuréka + + zbozi | Zboží.cz + + + ## Invoice Billing Methods + + + id | Description + + ------| ----- + + 1 | COD (cz: Dobírka) + + 2 | Wire transfer (cz: Převodem) + + 3 | Cash (cz: Hotově) + + 4 | Card (cz: Kartou) + + ## VAT modes + + + Value | + + ------| + + Normal | + + One Stop Shop | + + Mini One Stop Shop | + + Reverse charge | + + Outside the EU | + + + # Postman collection + + + If you use Postman as an API platform for building and using APIs, we provide you a complex collection of Shoptet API. + + You have 2 options how to import our postman collection (created from [openApi schema](https://swagger.io/specification/) - openapi.yaml ) into your postman client + + + ## Fork Shoptet API Collection from Shoptet Public API Workspace (recommended) + + + See [Shoptet Public API Workspace](https://www.postman.com/shoptet-developers/shoptet-public-api-workspace). + + Also check postman documentation for more details: [Fork a collection](https://learning.postman.com/docs/collaborating-in-postman/using-version-control/forking-elements/). + + + ### Step 1: Navigate to Shoptet Public API Workspace + + + - Launch Postman on your desktop or in the browser. + + - In the search bar in the top header of app, type **Shoptet Public API** and select collection from Shoptet public API Workspace. + + + ### Step 2: Locate the Shoptet API Collection + + + - Once inside the Shoptet Public API Workspace, go to the **Collections** tab. + + - Find the **Shoptet API** collection. + + + ### Step 3: Fork the Collection + + + - Click on the **Shoptet API** collection to open it. + + - In the collection view, click the **Fork** button in the top-right corner. + + - In the fork dialog, choose a name for your forked collection. + + - Select the workspace where you want to save the forked collection. + + - **It’s recommended to check `watch original collection` to get notified about changes in the original collection.** + + - Click **Fork Collection**. + + + ### Step 4: Access Your Forked Collection + + + - Navigate to the workspace where you saved the forked collection. + + - You’ll now find the forked **Shoptet API** collection under the **Collections** tab, ready for you to use and modify. + + Now 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. + + + ## Import openapi.yaml into Postman as a Collection + + + ### Step 1: Upload the `openapi.yaml` File + + + - Download the [openapi.yaml](https://github.com/shoptet/developers/blob/master/openapi/openapi.yaml) file from our developers [repository](https://github.com/shoptet/developers). + + - Launch Postman on your desktop or in the browser. + + - In the top-left corner of Postman, click the **Import** button. + + - A pop-up window will appear. + + - Drag and drop your `openapi.yaml` file into the window, or click **Upload Files** and browse to the file's location. + + + ### Step 2: Verify OpenAPI Import + + + - Postman will automatically recognize the OpenAPI schema. + + - It will display a preview of the API schema. + + + ### Step 3: Import as Collection + + + - Once the file is recognized, click **Import**. + + - Postman will convert the OpenAPI schema into a collection of requests, based on the defined endpoints in the `openapi.yaml` file. + + + ### Step 4: Access the Imported Collection + + + - After the import is successful, go to the **Collections** tab. + + - You’ll find your new collection, named after the OpenAPI schema, containing all the API requests generated from the file. + + + Now you can explore the API endpoints and use them directly within Postman! + + ## Collection settings + + 1. Click the **Shoptet API** collection name. + + 2. Go to **Authorization** tab. + + 3. Set your access token into the `value` of `Shoptet-Access-Token` key. + + 4. Go to **Variables** tab. + + 5. You can set `baseUrl` variable here. + + # Last changes + + + Last API changes are published on the [API news] page + (https://developers.shoptet.com/category/api/). servers: - url: 'https://api.myshoptet.com' +security: + - + shoptetAccessToken: [] + - + shoptetPrivateApiToken: [] +tags: + - + name: Eshop + description: 'This endpoint is used for general information about the e-shop settings.' + - + name: Products + description: 'Product endpoints are used for managing products in the e-shop and also for its related modules.' + - + name: 'Price lists' + description: 'Price lists are used for setting up different prices for products for different customer groups.' + - + name: Orders + description: 'Order endpoints are used for managing orders in the e-shop.' + - + name: Invoices + description: 'Invoice endpoints are used for managing invoices in the e-shop.' + - + name: 'Proforma invoices' + description: |- + Proforma invoice endpoints are used for managing proforma invoices in the e-shop. + + + The code (`code`) is the proforma invoice identifier. Although this is + usually a number, it is necessary to take into account that this might + also include + + letters, a dash, etc. + - + name: 'Credit notes' + description: |- + Credit note endpoints are used for managing credit notes in the e-shop. + + The code (`code`) is the credit note identifier. Although this is usually + a number, it is necessary to take into account that this might also + include + + letters, a dash, etc. + - + name: 'Delivery notes' + description: |- + Delivery note endpoints are used for managing delivery notes in the e-shop. + + + The code (`code`) is the credit notes identifier. Although this is usually + a number, it is necessary to take into account that this might also + include + + letters, a dash, etc. + - + name: 'Proof payments' + description: |- + The code (`code`) is the proof payments identifier. Although this is usually a number, it is necessary to take + into account that this might also include letters, a dash, etc. + - + name: Stocks + description: 'Stock endpoints are used for managing stocks in the e-shop.' + - + name: Suppliers + description: 'Supplier endpoints are used for managing suppliers in the e-shop.' + - + name: Brands + description: |- + Brand endpoints are used for managing brands in the e-shop. + + + **Please note**, the **field `code` is deprecated** - use `indexName` instead. Parameter `code` accepts both: + guid string style, e.g. `d467bfbe-4334-11ef-ad70-0242ac1f0005`, and index name string style, e.g. `willy-wonka`. + **The index name string style is deprecated** - use guid style. + - + name: Customers + description: 'Customer endpoints are used for managing customers in the e-shop.' + - + name: Templates + description: |- + In the last Shoptet version, it is not possible to change the e-shop + design via API. However, it is possible to include HTML codes + + into previously defined places. This enables the code or link to a file + containing additional CSS styles or JavaScript codes to be entered. + + The same functionality is now included within the e-shop administration + (`/admin/html-kody/`, `HTML code` tab). + + + There are 3 possible locations, where HTML codes can be inserted: + + + * `common-header` - the code will be inserted into each e-shop page header + (``) + + + * `common-footer` - the code will be inserted into each e-shop page foot + (before end ``) + + + * `order-confirmed` - the code will be inserted in the page confirming the + order (the "thank you page") + + + The inserted codes may come from 3 sources, and they are included in the + following order: + + 1. Codes from addons (the addon defines HTML codes to be inserted for + anybody, who installs the addon). If there are more of these, they are + inserted progressively, the order cannot be relied upon. + + 2. Codes entered via API. Each addon can insert only one code into each + location. If there are more of these addons, the codes will be inserted + progressively, one after another, the order cannot be relied upon. + + 3. The code entered in the administration GUI (`/admin/html-kody/`, `HTML + code` tab). + - + name: 'Payment gateways' + description: |- + API endpoints for integration of payment gateways. + + + **If you are a Premium client, contact your Account or Onboarding manager. + New payment gateway has to be approved by Shoptet and client needs to be + familiar with the terms of payment in advance**. + - + name: Webhooks + description: |- + API endpoints for webhook servicing. It offers the possibility to read, + add, change and delete the registered webhooks. Furthermore, it offers + + a list of notifications about invoked webhooks and their status. + + + The webhooks are HTTP calls, which send HTTPs calls to registered + subscribers if a specific event happens, + + for example creating an order. Then the information, in JSON format, is + delivered to the defined URL. + + + ```javascript + + { + "eshopId": 222651, + "event": "order:create", + "eventCreated": "2019-01-08T15:13:39+0100", + "eventInstance": "2018000057" + } + + ``` + + + The meaning of individual items: + + + * `eshopId` - number of the e-shop, where the event happened + + + * `event` - event which invoked the call (see code list Webhook event types) + + + * `eventCreated` - accurate time, when the event happened + + + * `eventInstance` - reference to a specified entity - according to the + context, order number, invoice number, product GUID, etc. + + + For more information about the function of webhooks, see + https://developers.shoptet.com/webhooks/. + - + name: 'Shipping methods' + description: |- + Shipping methods endpoints are used for managing shipping methods in the + e-shop. + - + name: 'Shipping requests' + description: |- + Shipping requests endpoints are used for managing shipping requests in the + e-shop. + - + name: 'Payment methods' + description: |- + Payment methods endpoints are used for managing payment methods in the + e-shop. + - + name: 'Unsubscribed emails' + description: |- + This functionality allows you to manage a list of email addresses that + opted out of receiving marketing communications in compliance with legal + requirements, including the possibility of comparing any further mailings + with this list to exclude opt-out contacts. + - + name: 'E-mail distribution lists' + description: |- + The functionality is subject to module activation [Mass + e-mailing](https://doplnky.shoptet.cz/hromadne-rozesilani-emailu) within + the e-shop. The addon using this endpoint must therefore have this module + defined as dependency. + - + name: 'Discount coupons' + description: |- + Discount coupons endpoints are used for managing discount coupons in the + e-shop. + - + name: 'X + Y discounts' + description: |- + X + Y discounts endpoints are used for managing X + Y discounts in the + e-shop. + - + name: Articles + description: 'Article endpoints are used for managing articles in the e-shop.' + - + name: Pages + description: 'Page endpoints are used for managing pages in the e-shop.' + - + name: Discussions + description: 'Discussion endpoints are used for managing discussions in the e-shop.' + - + name: 'Job endpoints' + description: 'Job endpoints are used for managing asynchronous jobs in the e-shop.' + - + name: Files + description: 'File endpoints are used for managing files in the e-shop.' + - + name: 'System endpoints' + description: 'This endpoints are used for obtaining information for endpoints in API.' paths: /api/eshop: get: @@ -1028,7 +2376,39 @@ paths: additionalProperties: false summary: 'Eshop info' operationId: getEshopInfo - description: "Information about queried e-shop (defined by token). Returns the contact data and e-shop settings.\n\nThis endpoint has several sections, which are only sent when requested in the `include` parameter (see [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand).\n\nIf you state the `include=imageCuts` parameter within the URL, information about the image cut will also be part of the response. For more information about the chapter [Product images](#section/Product-images).\n\n**Please note that languages section has meaning only if module foreign languages (Cizí jazyky) is enabled on current eshop. Otherwise you have to follow \"eshopLanguage\" attribute.**\nValue | Section\n--------|------\norderAdditionalFields | The order can contain up to six additional fields, which can be freely used by the e-shop for its individual needs. The field names can be defined in administration and this section returns their names.\norderStatuses | The order statuses, as defined for this e-shop.\npaymentMethods | Payment methods, as defined for this e-shop.\nshippingMethods | Transportation options, as defined for this e-shop.\nimageCuts | The information on image cuts (various sizes of the same image)\ncountries | Informations about eshop supported countries (name, validation patterns, ...)\ncashDesk | Informations about eshop cash desk configuration\nlanguages | Information about eshop languages settings - has meaning only if module foreign languages (Cizí jazyky) is enabled on current eshop" + description: |- + Information about queried e-shop (defined by token). Returns the contact data and e-shop settings. + + + This endpoint has several sections, which are only sent when requested in the `include` parameter (see + [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand). + + + If you state the `include=imageCuts` parameter within the URL, information about the image cut will also be part of the response. For more information + about the chapter [Product images](#section/Product-images). + + + **Please note that languages section has meaning only if module foreign languages (Cizí jazyky) is enabled on current eshop. Otherwise you have to follow "eshopLanguage" attribute.** + + Value | Section + + --------|------ + + orderAdditionalFields | The order can contain up to six additional fields, which can be freely used by the e-shop for its individual needs. The field names can be defined in administration and this section returns their names. + + orderStatuses | The order statuses, as defined for this e-shop. + + paymentMethods | Payment methods, as defined for this e-shop. + + shippingMethods | Transportation options, as defined for this e-shop. + + imageCuts | The information on image cuts (various sizes of the same image) + + countries | Informations about eshop supported countries (name, validation patterns, ...) + + cashDesk | Informations about eshop cash desk configuration + + languages | Information about eshop languages settings - has meaning only if module foreign languages (Cizí jazyky) is enabled on current eshop tags: - Eshop parameters: @@ -1290,7 +2670,10 @@ paths: additionalProperties: false summary: 'E-shop design' operationId: getEshopDesign - description: 'Information about queried e-shop template setting (defined by token). `backgroundImage` value can internally contain the link to a transparent reference gif, in this case the API returns a NULL value.' + description: |- + Information about queried e-shop template setting (defined by token). + `backgroundImage` value can internally contain the link to a transparent + reference gif, in this case the API returns a NULL value. tags: - Eshop parameters: @@ -1431,7 +2814,10 @@ paths: additionalProperties: false summary: 'E-shop mandatory fields' operationId: getEshopMandatoryFields - description: 'Information about queried e-shop mandatory fields setting (defined by token). Returns the values, which are set by e-shop administrator in Settings -> Customers -> Mandatory fields.' + description: |- + Information about queried e-shop mandatory fields setting (defined by token). + Returns the values, which are set by e-shop administrator in + Settings -> Customers -> Mandatory fields. tags: - Eshop parameters: @@ -1612,7 +2998,20 @@ paths: additionalProperties: false summary: 'List of products' operationId: getListOfProducts - description: "Returns the list of products - only basic info and GUID, using this you can determine the details with another API call. Endpoint supports [paging](#section/basic-principles-of-working-with-api/Paging).\n\nThis endpoint has several sections, which are sent only when requested in the `include` parameter (see [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand).\n\nIf you state the `include=images` parameter within the URL, then information about main product image will also be part of the response. For more information about the chapter [Product images](#section/Product-images).\n\nPlease note it is better to use List of all products endpoint for getting all products from eshop." + description: |- + Returns the list of products - only basic info and GUID, using this you can determine the details + with another API call. Endpoint supports [paging](#section/basic-principles-of-working-with-api/Paging). + + + This endpoint has several sections, which are sent only when requested in the `include` parameter (see + [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand). + + + If you state the `include=images` parameter within the URL, then information about main product image will + also be part of the response. For more information about the chapter [Product images](#section/Product-images). + + + Please note it is better to use List of all products endpoint for getting all products from eshop. tags: - Products parameters: @@ -1633,14 +3032,19 @@ paths: - name: visibility in: query - description: 'product visibility (visible, hidden, only for logged-in users...) - see also [Product visibility code list](#section/Code-lists/Product-visibility) Optional.' + description: |- + product visibility (visible, hidden, only for logged-in users...) - + see also [Product visibility code list](#section/Code-lists/Product-visibility) + Optional. example: visible schema: type: string - name: type in: query - description: 'product type (product, service, bazar...) - see also [Product type code list](#section/Code-lists/Product-types). Optional.' + description: |- + product type (product, service, bazar...) - see also [Product type + code list](#section/Code-lists/Product-types). Optional. example: product schema: type: string @@ -1654,7 +3058,9 @@ paths: - name: brandCode in: query - description: 'product brand (manufacturer) code from `/api/brands` endpoint. Optional.' + description: |- + product brand (manufacturer) code from `/api/brands` endpoint. + Optional. example: storm schema: type: string @@ -1668,7 +3074,9 @@ paths: - name: categoryGuid in: query - description: 'product category - only the products added to specific category will be included. Optional.' + description: |- + product category - only the products added to specific category will + be included. Optional. example: 5c499a23-70ac-11e9-9208-08002774f818 schema: type: string @@ -1689,7 +3097,9 @@ paths: - name: supplierGuid in: query - description: 'supplier GUID - only products with selected supplier will be included' + description: |- + supplier GUID - only products with selected supplier will be + included example: 16a67ec6-d957-11e0-b04f-57a43310b768 schema: type: string @@ -1734,7 +3144,33 @@ paths: additionalProperties: false summary: 'Product insertion' operationId: createProduct - description: "This endpoint allows you to insert products into Shoptet. You can use it for an import from an external system.\nRequest is sent in JSON format in its body. For detailed description of items, which can be provided, see the right-most\npane, section \"Request\" » \"Attributes\".\n\n**Currently it is possible to insert only a basic product attributes**\n\nWhen creating product without variants, add one variant to `variants` array and it will be created as product without variants,\nbut with values specified in the `variant`.\n\nWhen creating product with multiple variants, you must specify `parameters` which are different in each variant (variant A with\ncolor black and size XXL and variant B with color yellow and size XXL is correct, but two variants with color black and size XXL is not correct).\nAlso, `nameIndex` must be unique in a variant (variant A with color black and color white is not correct)." + description: |- + This endpoint allows you to insert products into Shoptet. You can use it + for an import from an external system. + + Request is sent in JSON format in its body. For detailed description of + items, which can be provided, see the right-most + + pane, section "Request" » "Attributes". + + + **Currently it is possible to insert only a basic product attributes** + + + When creating product without variants, add one variant to `variants` + array and it will be created as product without variants, + + but with values specified in the `variant`. + + + When creating product with multiple variants, you must specify + `parameters` which are different in each variant (variant A with + + color black and size XXL and variant B with color yellow and size XXL is + correct, but two variants with color black and size XXL is not correct). + + Also, `nameIndex` must be unique in a variant (variant A with color + black and color white is not correct). tags: - Products parameters: @@ -2247,7 +3683,7 @@ paths: errors: $ref: '#/components/schemas/Errors' example: - data: 'null' + data: null errors: - errorCode: missing-module @@ -2267,7 +3703,7 @@ paths: errors: $ref: '#/components/schemas/Errors' example: - data: 'null' + data: null errors: - errorCode: product-not-found @@ -2285,7 +3721,7 @@ paths: errors: $ref: '#/components/schemas/Errors' example: - data: 'null' + data: null errors: - errorCode: invalid-request-data @@ -2304,7 +3740,14 @@ paths: type: string - $ref: '#/components/parameters/DefaultContentType' - description: "This endpoint allows you to copy a product identified by a GUID.\nThe new product will have the same attributes as the original product. Many settings can be copied from the original product,but some settings require an active module. See the details below.\nBy default, all parameters are copied and set to true unless specified otherwise. If you only want to copy certain parameters, select those you want to copy and set the others to false. If you wish to copy all parameters, you don't need to include them in the request list at all.\nImportant note: If you previously had any active modules (such as Heureka, Seznam, GlobalSaleVat) that are no longer active, the resulting data may differ slightly because data requiring an active module will not be copied in this case." + description: |- + This endpoint allows you to copy a product identified by a GUID. + + The new product will have the same attributes as the original product. Many settings can be copied from the original product,but some settings require an active module. See the details below. + + By default, all parameters are copied and set to true unless specified otherwise. If you only want to copy certain parameters, select those you want to copy and set the others to false. If you wish to copy all parameters, you don't need to include them in the request list at all. + + Important note: If you previously had any active modules (such as Heureka, Seznam, GlobalSaleVat) that are no longer active, the resulting data may differ slightly because data requiring an active module will not be copied in this case. tags: - Products requestBody: @@ -2430,7 +3873,64 @@ paths: $ref: '#/components/schemas/Errors' summary: 'List of all products' operationId: getListOfAllProducts - description: "Using this endpoint, you can get list of all products with detailed info of each product (like in Product Detail endpoint) asynchronously. See how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our developer's portal.\n\nResponse will be in [jsonlines](https://jsonlines.org/) format with each product taking one line of output file. One product in response has the same format as product detail response (in `data` attribute)\n\nThis endpoint has several sections, which are exported only when requested in the `include` parameter (see [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)).\n\nInclude parameter | Meaning\n--- | ---\nimages | Export will also contain the list of all product images. For more information about the chapter [Product images](#product-images).\nvariantParameters | Export will also contain a field of variant parameters and a variant description, as they are visible to customers.\nallCategories | Export will also contain information on all the categories that the product was assigned into\nflags | Details on product designation\ndescriptiveParameters | Export will also contain descriptive parameters of the product\nmeasureUnit | Export will also contain measure unit info of every variant.\nsurchargeParameters | Export will also contain surcharge parameters of the product.\nsetItems | Export will also contain items, products, in set.\nfilteringParameters | Export will also contain filtering parameters of the product.\nrecyclingFee | Export will also contain recycling fee.\nwarranty | Export will also contain product warranty.\nsortVariants | Product variants will be sorted as in administration.\ngifts | List of gifts (variants) related to product\nalternativeProducts | The response will also contain alternative products.\nrelatedProducts | The response will also contain related products.\nrelatedVideos | The response will also contain related videos.\nrelatedFiles | The response will also contain related files.\nperStockAmounts | The response will also contain amounts/claims per individual stocks.\nperPricelistPrices | The response will also contain prices per individual price lists.\n\nResult file is compressed using GZIP." + description: |- + Using this endpoint, you can get list of all products with detailed info of each product (like in Product Detail endpoint) + asynchronously. See how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our + developer's portal. + + + Response will be in [jsonlines](https://jsonlines.org/) format with each product taking one line of output file. + One product in response has the same format as product detail response (in `data` attribute) + + + This endpoint has several sections, which are exported only when requested in the `include` parameter (see + [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)). + + + Include parameter | Meaning + + --- | --- + + images | Export will also contain the list of all product images. For more information about the chapter [Product images](#product-images). + + variantParameters | Export will also contain a field of variant parameters and a variant description, as they are visible to customers. + + allCategories | Export will also contain information on all the categories that the product was assigned into + + flags | Details on product designation + + descriptiveParameters | Export will also contain descriptive parameters of the product + + measureUnit | Export will also contain measure unit info of every variant. + + surchargeParameters | Export will also contain surcharge parameters of the product. + + setItems | Export will also contain items, products, in set. + + filteringParameters | Export will also contain filtering parameters of the product. + + recyclingFee | Export will also contain recycling fee. + + warranty | Export will also contain product warranty. + + sortVariants | Product variants will be sorted as in administration. + + gifts | List of gifts (variants) related to product + + alternativeProducts | The response will also contain alternative products. + + relatedProducts | The response will also contain related products. + + relatedVideos | The response will also contain related videos. + + relatedFiles | The response will also contain related files. + + perStockAmounts | The response will also contain amounts/claims per individual stocks. + + perPricelistPrices | The response will also contain prices per individual price lists. + + + Result file is compressed using GZIP. tags: - Products parameters: @@ -2458,14 +3958,19 @@ paths: - name: visibility in: query - description: 'product visibility (visible, hidden, only for logged-in users...) - see also [Product visibility code list](#section/Code-lists/Product-visibility) Optional.' + description: |- + product visibility (visible, hidden, only for logged-in users...) - + see also [Product visibility code list](#section/Code-lists/Product-visibility) + Optional. example: visible schema: type: string - name: type in: query - description: 'product type (product, service, bazar...) - see also [Product type code list](#section/Code-lists/Product-types). Optional.' + description: |- + product type (product, service, bazar...) - see also [Product type + code list](#section/Code-lists/Product-types). Optional. example: product schema: type: string @@ -2479,7 +3984,9 @@ paths: - name: brandCode in: query - description: 'product brand (manufacturer) code from `/api/brands` endpoint. Optional.' + description: |- + product brand (manufacturer) code from `/api/brands` endpoint. + Optional. example: storm schema: type: string @@ -2493,7 +4000,9 @@ paths: - name: categoryGuid in: query - description: 'product category - only the products added to specific category will be included. Optional.' + description: |- + product category - only the products added to specific category will + be included. Optional. example: 5c499a23-70ac-11e9-9208-08002774f818 schema: type: string @@ -2507,7 +4016,9 @@ paths: - name: supplierGuid in: query - description: 'supplier GUID - only products with selected supplier will be included' + description: |- + supplier GUID - only products with selected supplier will be + included example: 16a67ec6-d957-11e0-b04f-57a43310b768 schema: type: string @@ -2543,7 +4054,54 @@ paths: $ref: '#/components/schemas/Errors' summary: 'Product detail' operationId: getProductDetail - description: "Returns detailed information about one product. The product includes the variant field. In case the product comes in variants, the field contains all the available variants. If the product does not have any variants, it contains only one variant with product information.\n\nThis endpoint has several sections, which are sent only when requested in the `include` parameter (see [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)).\nInclude parameter | Meaning\n--- | ---\nimages | The response will also contain the list of all product images. For more information about the chapter [Product images](#section/Product-images).\nvariantParameters | The response will also contain a field of variant parameters and a variant description, as they are visible to customers.\nallCategories | The response will also contain information on all the categories that the product was assigned into\nflags | Details on product designation\ndescriptiveParameters | The response will also contain descriptive parameters of the product\nmeasureUnit | The response will also contain measure unit info of every variant.\nsurchargeParameters | The response will also contain surcharge parameters of the product.\nsetItems | The response will also contain items, products, in set.\nfilteringParameters | The response will also contain filtering parameters of the product.\nwarranty | The response will also contain product warranty.\nsortVariants | Product variants will be sorted as in administration.\ngifts | Product gifts, will be sorted as in administration\nalternativeProducts | The response will also contain alternative products.\nrelatedProducts | The response will also contain related products.\nrelatedVideos | The response will also contain related videos.\nrelatedFiles | The response will also contain related files.\nperStockAmounts | The response will also contain amounts/claims per individual stocks.\nperPricelistPrices | The response will also contain prices per individual price lists." + description: |- + Returns detailed information about one product. The product includes the variant field. In case the product comes in variants, + the field contains all the available variants. If the product does not have any variants, it contains only one variant + with product information. + + + This endpoint has several sections, which are sent only when requested in the `include` parameter (see + [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)). + + Include parameter | Meaning + + --- | --- + + images | The response will also contain the list of all product images. For more information about the chapter [Product images](#section/Product-images). + + variantParameters | The response will also contain a field of variant parameters and a variant description, as they are visible to customers. + + allCategories | The response will also contain information on all the categories that the product was assigned into + + flags | Details on product designation + + descriptiveParameters | The response will also contain descriptive parameters of the product + + measureUnit | The response will also contain measure unit info of every variant. + + surchargeParameters | The response will also contain surcharge parameters of the product. + + setItems | The response will also contain items, products, in set. + + filteringParameters | The response will also contain filtering parameters of the product. + + warranty | The response will also contain product warranty. + + sortVariants | Product variants will be sorted as in administration. + + gifts | Product gifts, will be sorted as in administration + + alternativeProducts | The response will also contain alternative products. + + relatedProducts | The response will also contain related products. + + relatedVideos | The response will also contain related videos. + + relatedFiles | The response will also contain related files. + + perStockAmounts | The response will also contain amounts/claims per individual stocks. + + perPricelistPrices | The response will also contain prices per individual price lists. tags: - Products parameters: @@ -2583,7 +4141,30 @@ paths: additionalProperties: false summary: 'Product update' operationId: updateProduct - description: "Allows you to change a product, which is identified by the guid.\n\nThis endpoint allows you to update products in Shoptet.\nRequest is sent in JSON format in its body. For detailed description of items, which can be updated and their format,\ncheck the right-most pane, section \"Request\" » \"Attributes\"\n\nProduct variant can be updated by specifying its `code`. When `code` is not specified or not existing, new variant will be created.\nIf you want to change `code` of variant, use `code` to specify variant to be changed and `newCode` for specifying new code.\n\nField `parameters` should contain ALL parameters that the edited variant should contain.\nThat means, if you have for example \"color:black\" in variant and you specify only new parameter \"size\", parameter color will be deleted." + description: |- + Allows you to change a product, which is identified by the guid. + + + This endpoint allows you to update products in Shoptet. + + Request is sent in JSON format in its body. For detailed description of + items, which can be updated and their format, + + check the right-most pane, section "Request" » "Attributes" + + + Product variant can be updated by specifying its `code`. When `code` is + not specified or not existing, new variant will be created. + + If you want to change `code` of variant, use `code` to specify variant + to be changed and `newCode` for specifying new code. + + + Field `parameters` should contain ALL parameters that the edited variant + should contain. + + That means, if you have for example "color:black" in variant and you + specify only new parameter "size", parameter color will be deleted. tags: - Products parameters: @@ -3110,7 +4691,9 @@ paths: errors: - errorCode: product-not-found - message: 'Product with identificator "93bc0dbe-7481-11e8-8216-002590dad85e" not found.' + message: |- + Product with identificator + "93bc0dbe-7481-11e8-8216-002590dad85e" not found. instance: 93bc0dbe-7481-11e8-8216-002590dad85e 409: description: Conflict @@ -3128,11 +4711,21 @@ paths: errors: - errorCode: product-used-in-set - message: 'Product with identificator "93bc0dbe-7481-11e8-8216-002590dad85e" cannot be deleted because is used in product set.' + message: |- + Product with identificator + "93bc0dbe-7481-11e8-8216-002590dad85e" cannot be deleted + because is used in product set. instance: 93bc0dbe-7481-11e8-8216-002590dad85e summary: 'Product deletion' operationId: deleteProduct - description: "Deletes product as per entered `guid`. If successful, returns the code 200.\nIf the product does not exist within the e-shop, a 404 code is returned.\nIf the product cannot be deleted, because it is part of set or used as a gift to some product, a 409 code is returned." + description: |- + Deletes product as per entered `guid`. If successful, returns the code + 200. + + If the product does not exist within the e-shop, a 404 code is returned. + + If the product cannot be deleted, because it is part of set or used as a + gift to some product, a 409 code is returned. tags: - Products parameters: @@ -3175,7 +4768,41 @@ paths: additionalProperties: false summary: 'Product BATCH update' operationId: productBatchUpdate - description: "This endpoint allows you to update multiple products at once. Batch update is processed asynchronously in same way as for example products snapshot,\nbut it does not have `resultUrl` with products to download in response. Instead, you can check attribute `log` which contains successfully updated products and errors.\n\nSee how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our developer's portal.\n\nFile with data for update must be in JSONL ([jsonlines](https://jsonlines.org/)) format. Each line must contain one product in JSON format. Maximum size of file is 100MB.\nStructure of JSON row is same as structure of JSON for single product update above. You can add one extra optional attribute\n\"language\" which defines language of updating product, so you are able to update multiple language attributes (i.e. \"name\", \"description\" etc.) of one product in one batch file.\nIf language is not defined, default language of shop is used.\n\nAsynchronous job process jsonl file row by row and try to validate and save data. If there is any error, row is skipped and error is logged, but it does not stop processing of other rows.\nIn Log, every product is identified by its position in file (starting from 1)." + description: |- + This endpoint allows you to update multiple products at once. Batch + update is processed asynchronously in same way as for example products + snapshot, + + but it does not have `resultUrl` with products to download in response. + Instead, you can check attribute `log` which contains successfully + updated products and errors. + + + See how [Asynchronous + requests](https://developers.shoptet.com/asynchronous-requests/) work on + our developer's portal. + + + File with data for update must be in JSONL + ([jsonlines](https://jsonlines.org/)) format. Each line must contain one + product in JSON format. Maximum size of file is 100MB. + + Structure of JSON row is same as structure of JSON for single product + update above. You can add one extra optional attribute + + "language" which defines language of updating product, so you are able + to update multiple language attributes (i.e. "name", "description" etc.) + of one product in one batch file. + + If language is not defined, default language of shop is used. + + + Asynchronous job process jsonl file row by row and try to validate and + save data. If there is any error, row is skipped and error is logged, + but it does not stop processing of other rows. + + In Log, every product is identified by its position in file (starting + from 1). tags: - Products requestBody: @@ -3211,7 +4838,10 @@ paths: $ref: '#/components/schemas/Errors' summary: 'Product detail by code' operationId: getProductDetailByCode - description: 'Retrieve details about one product. Optional sections can be requested using `?include=` parameter The response format is the same as for [Product detail](#tag/products/getlistofproducts) endpoint.' + description: |- + Retrieve details about one product. Optional sections can be requested + using `?include=` parameter + The response format is the same as for [Product detail](#tag/products/getlistofproducts) endpoint. tags: - Products parameters: @@ -3251,7 +4881,32 @@ paths: additionalProperties: false summary: 'Product update by code' operationId: updateProductByCode - description: "This endpoint allows you to update products identified by a product code in Shoptet.\nRequest is sent in JSON format in its body. For detailed description of items, which can be updated and their format,\ncheck the right-most pane, section \"Request\" » \"Attributes\".\n\nProduct variant can be updated by specifying its `code`. When `code` is not specified or not existing, new variant will be created.\nIf you want to change `code` of variant, use `code` to specify variant to be changed and `newCode` for specifying new code.\n\nField `parameters` should contain ALL parameters that the edited variant should contain.\nThat means, if you have for example \"color:black\" in variant and you specify only new parameter \"velikost\", parameter color will be deleted.\n\n**Please note that any product's variant can be edited by this endpoint, not only the one in url**" + description: |- + This endpoint allows you to update products identified by a product code + in Shoptet. + + Request is sent in JSON format in its body. For detailed description of + items, which can be updated and their format, + + check the right-most pane, section "Request" » "Attributes". + + + Product variant can be updated by specifying its `code`. When `code` is + not specified or not existing, new variant will be created. + + If you want to change `code` of variant, use `code` to specify variant + to be changed and `newCode` for specifying new code. + + + Field `parameters` should contain ALL parameters that the edited variant + should contain. + + That means, if you have for example "color:black" in variant and you + specify only new parameter "velikost", parameter color will be deleted. + + + **Please note that any product's variant can be edited by this endpoint, + not only the one in url** tags: - Products parameters: @@ -3796,11 +5451,23 @@ paths: errors: - errorCode: product-used-in-set - message: 'Product with identificator "133" cannot be deleted because is used in product set.' + message: |- + Product with identificator "133" cannot be deleted because + is used in product set. instance: '133' summary: 'Product variant deletion' operationId: deleteProductVariant - description: "Deletes product variant as per entered `code`. If this is the last product variant, the entire product is deleted.\nIf successful, returns the code 200.\nIf the product variant does not exist within the e-shop, a 404 code is returned.\nIf the product variant cannot be deleted, because it is part of set or used as a gift to some product, a 409 code is returned." + description: |- + Deletes product variant as per entered `code`. If this is the last + product variant, the entire product is deleted. + + If successful, returns the code 200. + + If the product variant does not exist within the e-shop, a 404 code is + returned. + + If the product variant cannot be deleted, because it is part of set or + used as a gift to some product, a 409 code is returned. tags: - Products parameters: @@ -3882,7 +5549,13 @@ paths: additionalProperties: false summary: 'List of product images' operationId: getListOfProductImages - description: "Returns list of product's images.\nData from this endpoint and from product's detail endpoint (list named `images` when using `?include=images` parameter) are the same.\nUse this endpoint when working only with product images to save time." + description: |- + Returns list of product's images. + + Data from this endpoint and from product's detail endpoint (list named + `images` when using `?include=images` parameter) are the same. + + Use this endpoint when working only with product images to save time. tags: - Products parameters: @@ -3897,7 +5570,9 @@ paths: - name: gallery in: path - description: 'Gallery identifier - use `shop` for normal and `shop360` for 360 photos' + description: |- + Gallery identifier - use `shop` for normal and `shop360` for 360 + photos required: true example: shop schema: @@ -3930,7 +5605,19 @@ paths: instance: instance summary: 'Delete all product images in gallery' operationId: deleteAllProductImagesInGallery - description: "Deletes all product's images by gallery name. If `removeReference` parameter is not present or set to `false` and if image is referenced\nas variant image, then image will be skipped and present in `errors` in response.\nIf `removeReference` is set to true, then this reference will be removed with the image.\n\nReturns `200` status code. If any image deletion failed, it will be noted in `errors` section in response." + description: |- + Deletes all product's images by gallery name. If `removeReference` + parameter is not present or set to `false` and if image is referenced + + as variant image, then image will be skipped and present in `errors` in + response. + + If `removeReference` is set to true, then this reference will be removed + with the image. + + + Returns `200` status code. If any image deletion failed, it will be + noted in `errors` section in response. tags: - Products parameters: @@ -3953,7 +5640,9 @@ paths: - name: removeReference in: query - description: "If product's variant image reference should be removed. Default `false`." + description: |- + If product's variant image reference should be removed. Default + `false`. example: 'true' schema: type: boolean @@ -4030,7 +5719,10 @@ paths: additionalProperties: false summary: 'Product images update' operationId: getProductImagesUpdate - description: 'Using this endpoint you can modify product images attributes, such as description and priority (order). Maximum of 100 images can be sent at once.' + description: |- + Using this endpoint you can modify product images attributes, such as + description and priority (order). Maximum of 100 images can be sent at + once. tags: - Products parameters: @@ -4045,7 +5737,9 @@ paths: - name: gallery in: path - description: 'Gallery identifier - use `shop` for normal and `shop360` for 360 photos' + description: |- + Gallery identifier - use `shop` for normal and `shop360` for 360 + photos required: true example: shop schema: @@ -4123,7 +5817,15 @@ paths: additionalProperties: false summary: 'Product images insertion' operationId: createProductImages - description: "Using this endpoint you can upload new images to a product. This is an asynchronous request,\nsee how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our\ndeveloper's portal. Maximum of 100 images can be sent at once." + description: |- + Using this endpoint you can upload new images to a product. This is an + asynchronous request, + + see how [Asynchronous + requests](https://developers.shoptet.com/asynchronous-requests/) work on + our + + developer's portal. Maximum of 100 images can be sent at once. tags: - Products parameters: @@ -4138,7 +5840,9 @@ paths: - name: gallery in: path - description: 'Gallery identifier - use `shop` for normal and `shop360` for 360 photos' + description: |- + Gallery identifier - use `shop` for normal and `shop360` for 360 + photos required: true example: shop schema: @@ -4218,7 +5922,14 @@ paths: additionalProperties: false summary: 'Product images source update' operationId: updateProductImagesSource - description: "Using this endpoint you can modify product image attributes and also upload a new image and replace the existing one.\nThis is an asynchronous request, see how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/\nwork on our developer's portal." + description: |- + Using this endpoint you can modify product image attributes and also + upload a new image and replace the existing one. + + This is an asynchronous request, see how [Asynchronous + requests](https://developers.shoptet.com/asynchronous-requests/ + + work on our developer's portal. tags: - Products parameters: @@ -4233,7 +5944,9 @@ paths: - name: gallery in: path - description: 'Gallery identifier - use `shop` for normal and `shop360` for 360 photos' + description: |- + Gallery identifier - use `shop` for normal and `shop360` for 360 + photos required: true example: shop schema: @@ -4310,7 +6023,15 @@ paths: additionalProperties: false summary: 'Delete one product image' operationId: deleteOneProductImage - description: "Deletes product's image. If `removeReference` parameter is not present or set to `false` and if image is referenced\nas variant image, then image won't be deleted and response will have status code `409 Conflict`.\nIf `removeReference` is set to true, then this reference will be removed with the image." + description: |- + Deletes product's image. If `removeReference` parameter is not present + or set to `false` and if image is referenced + + as variant image, then image won't be deleted and response will have + status code `409 Conflict`. + + If `removeReference` is set to true, then this reference will be removed + with the image. tags: - Products parameters: @@ -4341,7 +6062,9 @@ paths: - name: removeReference in: query - description: "If product's variant image reference should be removed. Default `false`." + description: |- + If product's variant image reference should be removed. Default + `false`. example: 'true' schema: type: boolean @@ -4395,7 +6118,249 @@ paths: additionalProperties: false summary: 'Last product changes' operationId: getLastProductChanges - description: "Returns the list of products, which were changed (added/edited or deleted). Endpoint is intended to determine the changes after you have loaded the complete list of products and you need to know if any of these have been changed. Guaranteed history is 30 days, older data are deleted progressively.\n\nEach product in the log is mentioned only with its last change. For example, if the product was modified and then deleted, the log will show only information about its deletion.\n\nCreation is considered as `edit` action. So, when there is a new item created, it will be displayed like `edit` action.\n\nEndpoint supports [pagination](#section/basic-principles-of-working-with-api/Paging).\n\nDescription of object attributes with information about changes:\n|Field |Causes product change|Notes. |\n|--------------------------------------|---------------------|---------------------------------------|\n|guid |Yes | |\n|type |Yes | |\n|visibility |Yes | |\n|creationTime |Yes | |\n|changeTime |Yes | |\n|shortDescription |Yes | |\n|description |Yes | |\n|metaDescription |Yes | |\n|name |Yes | |\n|internalNote |Yes | |\n|defaultCategory |Yes |Only category - product relation change|\n|defaultCategory.guid |No | |\n|defaultCategory.name |No | |\n|supplier |Yes |Only supplier - product relation change|\n|supplier.guid |No | |\n|supplier.name |No | |\n|brand |Yes |Only brand - product relation change |\n|brand.code |No | |\n|brand.name |No | |\n|categories |Yes |Only product - category relation |\n|categories.guid |No | |\n|categories.parentGuid |No | |\n|categories.name |No | |\n|url |Yes |Only for relative url. Domain change no|\n|flags |Yes | |\n|flags.code |No | |\n|flags.title |No | |\n|flags.dateFrom |Yes | |\n|flags.dateTo |Yes | |\n|variants |Yes | |\n|variants.code |Yes | |\n|variants.ean |Yes | |\n|variants.stock |no | |\n|variants.unit |yes | |\n|variants.weight |yes | |\n|variants.visible |yes | |\n|variants.minStockSupply |yes | |\n|variants.negativeStockAllowed |yes | |\n|variants.amountDecimalPlaces |yes | |\n|variants.price |yes | |\n|variants.includingVat |yes | |\n|variants.vatRate |yes | |\n|variants.currencyCode |yes | |\n|variants.actionPrice |yes | |\n|variants.commonPrice |yes | |\n|variants.manufacturerCode |yes | |\n|variants.pluCode |yes | |\n|variants.isbn |yes | |\n|variants.serialNo |yes | |\n|variants.mpn |yes | |\n|variants.availability |yes | |\n|variants.availabilityWhenSoldOut |yes | |\n|variants.image |yes | |\n|variants.parameters |yes | |\n|variants.name |yes | |\n|variants.measureUnit |yes | |\n|variants.measureUnit.measureAmount |yes | |\n|variants.measureUnit.measureUnitId |yes | |\n|variants.measureUnit.packagingAmount |yes | |\n|variants.measureUnit.packagingUnitId |yes | |\n|variants.measureUnit.measureUnitName |yes | |\n|variants.measureUnit.packagingUnitName|yes | |\n|variants.measureUnit.measurePrice |yes | |\n|variants.recyclingFee |yes | |\n|images |yes | |\n|images.name |yes | |\n|images.priority |yes | |\n|images.description |yes | |\n|images.changeTime |yes | |\n|images.seoName |yes | |\n|images.cdnName |yes | |\n|descriptiveParameters |yes | |\n|descriptiveParameters.name |yes | |\n|descriptiveParameters.value |yes | |\n|descriptiveParameters.description |yes | |\n|descriptiveParameters.priority |yes | |\n|surchargeParameters |no | |\n|surchargeParameters.code |no | |\n|surchargeParameters.name |no | |\n|surchargeParameters.displayName |no | |\n|surchargeParameters.description |no | |\n|surchargeParameters.priority |no | |\n|surchargeParameters.required |no | |\n|surchargeParameters.currency |no | |\n|surchargeParameters.includingVat |no | |\n|surchargeParameters.values |no | |\n|surchargeParameters.values.valueIndex |no | |\n|surchargeParameters.values.description|no | |\n|surchargeParameters.values.price |no | |\n|surchargeParameters.values.priority |no | |\n|surchargeParameters.values.visible |no | |\n|setItems |yes | |\n|setItems.guid |no | |\n|setItems.code |no | |\n|setItems.amount |no | |\n|filteringParameters |yes |Only relation |\n|filteringParameters.code |no | |\n|filteringParameters.name |no | |\n|filteringParameters.displayName |no | |\n|filteringParameters.description |no | |\n|filteringParameters.priority |yes | |\n|filteringParameters.googleMapping |no | |\n|filteringParameters.values |yes |Only relation |\n|filteringParameters.values.valueIndex |no | |\n|filteringParameters.values.name |no | |\n|filteringParameters.values.priority |no | |\n|filteringParameters.values.color |no | |\n|filteringParameters.values.image |no | |\n|warranty |yes |only relation |\n|warranty.inMonths |no | |\n|warranty.description |no | |" + description: |- + Returns the list of products, which were changed (added/edited or deleted). Endpoint is intended to determine + the changes after you have loaded the complete list of products and you need to know if any of these have been changed. + Guaranteed history is 30 days, older data are deleted progressively. + + + Each product in the log is mentioned only with its last change. For example, if the product was modified and then deleted, + the log will show only information about its deletion. + + + Creation is considered as `edit` action. So, when there is a new item created, it will be displayed like `edit` action. + + + Endpoint supports [pagination](#section/basic-principles-of-working-with-api/Paging). + + + Description of object attributes with information about changes: + + |Field |Causes product change|Notes. | + + |--------------------------------------|---------------------|---------------------------------------| + + |guid |Yes | | + + |type |Yes | | + + |visibility |Yes | | + + |creationTime |Yes | | + + |changeTime |Yes | | + + |shortDescription |Yes | | + + |description |Yes | | + + |metaDescription |Yes | | + + |name |Yes | | + + |internalNote |Yes | | + + |defaultCategory |Yes |Only category - product relation change| + + |defaultCategory.guid |No | | + + |defaultCategory.name |No | | + + |supplier |Yes |Only supplier - product relation change| + + |supplier.guid |No | | + + |supplier.name |No | | + + |brand |Yes |Only brand - product relation change | + + |brand.code |No | | + + |brand.name |No | | + + |categories |Yes |Only product - category relation | + + |categories.guid |No | | + + |categories.parentGuid |No | | + + |categories.name |No | | + + |url |Yes |Only for relative url. Domain change no| + + |flags |Yes | | + + |flags.code |No | | + + |flags.title |No | | + + |flags.dateFrom |Yes | | + + |flags.dateTo |Yes | | + + |variants |Yes | | + + |variants.code |Yes | | + + |variants.ean |Yes | | + + |variants.stock |no | | + + |variants.unit |yes | | + + |variants.weight |yes | | + + |variants.visible |yes | | + + |variants.minStockSupply |yes | | + + |variants.negativeStockAllowed |yes | | + + |variants.amountDecimalPlaces |yes | | + + |variants.price |yes | | + + |variants.includingVat |yes | | + + |variants.vatRate |yes | | + + |variants.currencyCode |yes | | + + |variants.actionPrice |yes | | + + |variants.commonPrice |yes | | + + |variants.manufacturerCode |yes | | + + |variants.pluCode |yes | | + + |variants.isbn |yes | | + + |variants.serialNo |yes | | + + |variants.mpn |yes | | + + |variants.availability |yes | | + + |variants.availabilityWhenSoldOut |yes | | + + |variants.image |yes | | + + |variants.parameters |yes | | + + |variants.name |yes | | + + |variants.measureUnit |yes | | + + |variants.measureUnit.measureAmount |yes | | + + |variants.measureUnit.measureUnitId |yes | | + + |variants.measureUnit.packagingAmount |yes | | + + |variants.measureUnit.packagingUnitId |yes | | + + |variants.measureUnit.measureUnitName |yes | | + + |variants.measureUnit.packagingUnitName|yes | | + + |variants.measureUnit.measurePrice |yes | | + + |variants.recyclingFee |yes | | + + |images |yes | | + + |images.name |yes | | + + |images.priority |yes | | + + |images.description |yes | | + + |images.changeTime |yes | | + + |images.seoName |yes | | + + |images.cdnName |yes | | + + |descriptiveParameters |yes | | + + |descriptiveParameters.name |yes | | + + |descriptiveParameters.value |yes | | + + |descriptiveParameters.description |yes | | + + |descriptiveParameters.priority |yes | | + + |surchargeParameters |no | | + + |surchargeParameters.code |no | | + + |surchargeParameters.name |no | | + + |surchargeParameters.displayName |no | | + + |surchargeParameters.description |no | | + + |surchargeParameters.priority |no | | + + |surchargeParameters.required |no | | + + |surchargeParameters.currency |no | | + + |surchargeParameters.includingVat |no | | + + |surchargeParameters.values |no | | + + |surchargeParameters.values.valueIndex |no | | + + |surchargeParameters.values.description|no | | + + |surchargeParameters.values.price |no | | + + |surchargeParameters.values.priority |no | | + + |surchargeParameters.values.visible |no | | + + |setItems |yes | | + + |setItems.guid |no | | + + |setItems.code |no | | + + |setItems.amount |no | | + + |filteringParameters |yes |Only relation | + + |filteringParameters.code |no | | + + |filteringParameters.name |no | | + + |filteringParameters.displayName |no | | + + |filteringParameters.description |no | | + + |filteringParameters.priority |yes | | + + |filteringParameters.googleMapping |no | | + + |filteringParameters.values |yes |Only relation | + + |filteringParameters.values.valueIndex |no | | + + |filteringParameters.values.name |no | | + + |filteringParameters.values.priority |no | | + + |filteringParameters.values.color |no | | + + |filteringParameters.values.image |no | | + + |warranty |yes |only relation | + + |warranty.inMonths |no | | + + |warranty.description |no | | tags: - Products parameters: @@ -4857,7 +6822,9 @@ paths: errors: - errorCode: category-not-found - message: 'Category with identificator "5c499200-70ac-11e9-9208-08002774f818" not found.' + message: |- + Category with identificator + "5c499200-70ac-11e9-9208-08002774f818" not found. instance: 5c499200-70ac-11e9-9208-08002774f818 409: description: Conflict @@ -4877,7 +6844,9 @@ paths: errors: - errorCode: category-used-by-products - message: 'Category "5c499200-70ac-11e9-9208-08002774f818" cannot be deleted, because some products are assigned to it.' + message: |- + Category "5c499200-70ac-11e9-9208-08002774f818" cannot + be deleted, because some products are assigned to it. instance: 5c499200-70ac-11e9-9208-08002774f818 example2: value: @@ -4885,11 +6854,27 @@ paths: errors: - errorCode: category-has-children - message: 'Category "5c499200-70ac-11e9-9208-08002774f818" cannot be deleted, because it is a parent category.' + message: |- + Category "5c499200-70ac-11e9-9208-08002774f818" cannot + be deleted, because it is a parent category. instance: 5c499200-70ac-11e9-9208-08002774f818 summary: 'Product category deletion' operationId: deleteProductCategory - description: "Deletes product category as per entered `categoryGuid`. If successful, returns the code 200.\nIf the category does not exist within the e-shop, a 404 code is returned.\nIf the category cannot be deleted, because it is used by some product or has children, a 409 code is returned.\nOptional parameter `deleteUsed` allows deleting categories used by products. The products are marked as changed.\nOptional parameter `deleteChildren` allows deleting categories with child categories. The children are deleted too." + description: |- + Deletes product category as per entered `categoryGuid`. If successful, + returns the code 200. + + If the category does not exist within the e-shop, a 404 code is + returned. + + If the category cannot be deleted, because it is used by some product or + has children, a 409 code is returned. + + Optional parameter `deleteUsed` allows deleting categories used by + products. The products are marked as changed. + + Optional parameter `deleteChildren` allows deleting categories with + child categories. The children are deleted too. tags: - Products parameters: @@ -4946,7 +6931,41 @@ paths: additionalProperties: false summary: 'Product category BATCH update' operationId: updateProductCategoryBatch - description: "This endpoint allows you to update multiple categories at once. Batch update is processed asynchronously in same way as for example products snapshot,\nbut it does not have `resultUrl` with categories to download in response. Instead, you can check attribute `log` which contains successfully updated categories and errors.\n\nSee how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our developer's portal.\n\nFile with data for update must be in JSONL ([jsonlines](https://jsonlines.org/)) format. Each line must contain one category in JSON format. Maximum size of file is 100MB.\nStructure of JSON row is same as structure of JSON for single category update above. You can add one extra optional attribute\n\"language\" which defines language of updating category, so you are able to update multiple language attributes (i.e. \"name\", \"description\" etc.) of one category in one batch file.\nIf language is not defined, default language of shop is used.\n\nAsynchronous job process jsonl file row by row and try to validate and save data. If there is any error, row is skipped and error is logged, but it does not stop processing of other rows.\nIn Log, every product is identified by its position in file (starting from 1)." + description: |- + This endpoint allows you to update multiple categories at once. Batch + update is processed asynchronously in same way as for example products + snapshot, + + but it does not have `resultUrl` with categories to download in + response. Instead, you can check attribute `log` which contains + successfully updated categories and errors. + + + See how [Asynchronous + requests](https://developers.shoptet.com/asynchronous-requests/) work on + our developer's portal. + + + File with data for update must be in JSONL + ([jsonlines](https://jsonlines.org/)) format. Each line must contain one + category in JSON format. Maximum size of file is 100MB. + + Structure of JSON row is same as structure of JSON for single category + update above. You can add one extra optional attribute + + "language" which defines language of updating category, so you are able + to update multiple language attributes (i.e. "name", "description" etc.) + of one category in one batch file. + + If language is not defined, default language of shop is used. + + + Asynchronous job process jsonl file row by row and try to validate and + save data. If there is any error, row is skipped and error is logged, + but it does not stop processing of other rows. + + In Log, every product is identified by its position in file (starting + from 1). tags: - Products requestBody: @@ -5069,11 +7088,25 @@ paths: errors: - errorCode: unknown-product - message: 'Product "19ee3c7c-92c7-11e9-9373-08002774f818" does not exist. Skipped.' + message: |- + Product "19ee3c7c-92c7-11e9-9373-08002774f818" does not + exist. Skipped. instance: 19ee3c7c-92c7-11e9-9373-08002774f818 summary: 'Update product order in category' operationId: updateProductOrderInCategory - description: "Using this endpoint you can update product priority within a category.\nYou can request multiple updates at once; the maximum is 200 updates per request.\nIn case of a partial failure, the response code will be `200 OK` and the errorneous items will be\nlisted in the `errors` array. In case of a complete failure, response code will be `400 BAD REQUEST`.\nMinimum priority is 0, maximum priority is 65535." + description: |- + Using this endpoint you can update product priority within a category. + + You can request multiple updates at once; the maximum is 200 updates per + request. + + In case of a partial failure, the response code will be `200 OK` and the + errorneous items will be + + listed in the `errors` array. In case of a complete failure, response + code will be `400 BAD REQUEST`. + + Minimum priority is 0, maximum priority is 65535. tags: - Products parameters: @@ -7817,7 +9850,17 @@ paths: additionalProperties: false summary: 'List of variant parameters' operationId: getListOfVariantParameters - description: "Returns the list of available variant parameters with their available values within the e-shop.\n\nList of variant parameters endpoint has section, which is only sent when requested in the `include` parameter.\nValue | Section\n--------|------\n`values` | Variant parameter values" + description: |- + Returns the list of available variant parameters with their available values within the e-shop. + + + List of variant parameters endpoint has section, which is only sent when requested in the `include` parameter. + + Value | Section + + --------|------ + + `values` | Variant parameter values tags: - Products parameters: @@ -8534,7 +10577,15 @@ paths: type: string - $ref: '#/components/parameters/DefaultContentType' - description: "Returns list of alternative products related to product defined by `guid`, list is ordered by priority parameter.\nIf `Pair reciprocally` option (`Settings > Product > Related and Alternative products`) is enabled, list of\nitems will be enriched by items that has called product in own alternative table." + description: |- + Returns list of alternative products related to product defined by + `guid`, list is ordered by priority parameter. + + If `Pair reciprocally` option (`Settings > Product > Related and + Alternative products`) is enabled, list of + + items will be enriched by items that has called product in own + alternative table. tags: - Products post: @@ -8575,7 +10626,12 @@ paths: type: string - $ref: '#/components/parameters/DefaultContentType' - description: "This method add given product, defined with `guid` at the end of the alternative product list. After product\nis successfully saved, complete list of alternative product is returned in response." + description: |- + This method add given product, defined with `guid` at the end of the + alternative product list. After product + + is successfully saved, complete list of alternative product is returned + in response. tags: - Products requestBody: @@ -8639,7 +10695,12 @@ paths: type: string - $ref: '#/components/parameters/DefaultContentType' - description: "This method set given products (minimum 0, maximum 50), defined with `guid` to the alternative product list. After product\nis successfully saved, complete list of alternative product is returned in response." + description: |- + This method set given products (minimum 0, maximum 50), defined with + `guid` to the alternative product list. After product + + is successfully saved, complete list of alternative product is returned + in response. tags: - Products requestBody: @@ -8708,7 +10769,15 @@ paths: type: string - $ref: '#/components/parameters/DefaultContentType' - description: "Returns list of related products related to product defined by `guid`, list is ordered by priority parameter.\nIf `Pair reciprocally` option (`Settings > Product > Related and Alternative products`) is enabled, list of\nitems will be enriched by items that has called product in own related table." + description: |- + Returns list of related products related to product defined by `guid`, + list is ordered by priority parameter. + + If `Pair reciprocally` option (`Settings > Product > Related and + Alternative products`) is enabled, list of + + items will be enriched by items that has called product in own related + table. tags: - Products post: @@ -8749,7 +10818,12 @@ paths: type: string - $ref: '#/components/parameters/DefaultContentType' - description: "This method add given product, defined with `guid` at the end of the related product list. After product\nis successfully saved, complete list of related product is returned in response." + description: |- + This method add given product, defined with `guid` at the end of the + related product list. After product + + is successfully saved, complete list of related product is returned in + response. tags: - Products requestBody: @@ -8813,7 +10887,12 @@ paths: type: string - $ref: '#/components/parameters/DefaultContentType' - description: "This method set given products (minimum 0, maximum 50), defined with `guid` to the related product list. After product\nis successfully saved, complete list of related product is returned in response." + description: |- + This method set given products (minimum 0, maximum 50), defined with + `guid` to the related product list. After product + + is successfully saved, complete list of related product is returned in + response. tags: - Products requestBody: @@ -8868,23 +10947,25 @@ paths: - data - errors additionalProperties: false - summary: 'Add product to product set' - operationId: add-product-to-product-set + summary: 'Add item to product-set' + operationId: add-item-to-product-set parameters: - name: guid in: path - description: 'Product guid' + description: 'Product guid - Must be `product-set` type.' required: true example: 93bc0dbe-7481-11e8-8216-002590dad85e schema: type: string - description: 'This method adding product defined by product variant `code` to the bundle (product set). Parent product must be set as `product-set` and is defined by `guid`. When successfully saved, complete list of products in the set is returned in response.' + description: |- + This method adding product defined by product variant `code` to the bundle (product set). Product defined in url by `guid`, must be set as `type` : `product-set`. + When successfully saved, complete list of products in the set is returned in response. tags: - Products requestBody: content: - application/vnd.shoptet.v1.0: + application/vnd.shoptet.v1.0+json: schema: type: object required: @@ -8934,23 +11015,25 @@ paths: - data - errors additionalProperties: false - summary: 'Set products in product set' - operationId: set-product-to-product-set + summary: 'Set product-set items' + operationId: set-product-set-items parameters: - name: guid in: path - description: 'Product guid' + description: 'Product guid - Must be `product-set` type.' required: true example: 93bc0dbe-7481-11e8-8216-002590dad85e schema: type: string - description: 'This method set given products (minimum 0, maximum 50), defined by product variant `code` to the bundle of products (product-set). Parent product must be set as `product-set` and is defined by `guid`. When successfully saved, complete list of products in the set is returned in response.' + description: |- + This method set given products (minimum 0, maximum 50), defined by product variant `code` to the bundle of products (product-set). + Product defined in url by `guid`, must be set as `type` : `product-set`. When successfully saved, complete list of products in the set is returned in response. tags: - Products requestBody: content: - application/vnd.shoptet.v1.0: + application/vnd.shoptet.v1.0+json: schema: type: object required: @@ -9420,7 +11503,9 @@ paths: additionalProperties: false summary: 'List of price lists' operationId: getListOfPriceLists - description: 'Listing of all price lists set up in e-shop. Does not contain the paging, always lists all price lists.' + description: |- + Listing of all price lists set up in e-shop. Does not contain the + paging, always lists all price lists. tags: - 'Price lists' parameters: @@ -9587,7 +11672,9 @@ paths: instance: 43/BILL - errorCode: invalid-request-data - message: "Input data for code '43/BIL' doesn't correct. Code skipped." + message: |- + Input data for code '43/BIL' doesn't correct. Code + skipped. instance: 43/BIL 400: description: 'Bad Request' @@ -9611,7 +11698,62 @@ paths: instance: '11' summary: 'Update pricelist' operationId: UpdatePricelist - description: "This endpoint allows updating price fields and other attributes from a pricelist of a product (variant).\nYou can request multiple updates at once; the maximum is 100 updates per request.\nThe request must contain a product variant code `code` and at least one of the `price`,\n `priceWithVat`, `priceWithoutVat`, `orderableAmount` or `sales` objects.\nSend only fields you want to change, the others will stay untouched. Be aware of the difference between\n\n- not providing a field: the field will not be changed\n\n- providing e. g. `data.price.buyPrice: null` will remove the price\n\nIn case the request will be properly formatted, but an error occurs for one of the records, the correct records\nwill be updated, the response will be `200 OK` and there will be records in the `errors` array for each failed\nrecord. If all records are incorrect, the response code will be `400 BAD REQUEST` instead.\n\nIf you set `includingVat` or `vatRate` field, current data for product (or variant) will be recalculated. (even through untouched by your request)\nObject `price` directly sets price of product, without recalculating.\nObject `priceWithVat` sets price of product, respecting it is price **with** VAT and thus recalculating if needed.\nObject `priceWithoutVat` sets price of product, respecting it is price **without** VAT and thus recalculating if needed.\n\nNote, that you can change `buyPrice` only for default price list! For others price lists, value stays `null`.\n\nFor non-vat payer e-shops, `vatRate` and `includingVat` fields are forbidden to use and fields `price`, `priceWithVat` and `priceWithoutVat`\nall works the same.\nIn order to change the currency of the prices, you will need to have the Currencies module (Cizí měny) activated on the customer's e-shop. Note that if you change the currency code of the price list, all prices will not be recalculated to the new currency; only the currency code will be changed." + description: |- + This endpoint allows updating price fields and other attributes from a + pricelist of a product (variant). + + You can request multiple updates at once; the maximum is 100 updates per + request. + + The request must contain a product variant code `code` and at least one + of the `price`, + `priceWithVat`, `priceWithoutVat`, `orderableAmount` or `sales` objects. + + Send only fields you want to change, the others will stay untouched. Be + aware of the difference between + + + - not providing a field: the field will not be changed + + + - providing e. g. `data.price.buyPrice: null` will remove the price + + + In case the request will be properly formatted, but an error occurs for + one of the records, the correct records + + will be updated, the response will be `200 OK` and there will be records + in the `errors` array for each failed + + record. If all records are incorrect, the response code will be `400 BAD + REQUEST` instead. + + + If you set `includingVat` or `vatRate` field, current data for product + (or variant) will be recalculated. (even through untouched by your + request) + + Object `price` directly sets price of product, without recalculating. + + Object `priceWithVat` sets price of product, respecting it is price + **with** VAT and thus recalculating if needed. + + Object `priceWithoutVat` sets price of product, respecting it is price + **without** VAT and thus recalculating if needed. + + + Note, that you can change `buyPrice` only for default price list! For + others price lists, value stays `null`. + + + For non-vat payer e-shops, `vatRate` and `includingVat` fields are + forbidden to use and fields `price`, `priceWithVat` and + `priceWithoutVat` + + all works the same. + + In order to change the currency of the prices, you will need to have the Currencies module (Cizí měny) activated on the customer's e-shop. + Note that if you change the currency code of the price list, all prices will not be recalculated to the new currency; only the currency code will be changed. tags: - 'Price lists' parameters: @@ -9972,11 +12114,15 @@ paths: errors: - errorCode: pricelist-blocked - message: 'Product import is running now. Removing pricelists has been temporarily prohibited.' + message: |- + Product import is running now. Removing pricelists has + been temporarily prohibited. instance: integration-call summary: 'Pricelist delete' operationId: deletePricelist - description: 'Deletion of pricelist can fail with error `423` in case of running import.' + description: |- + Deletion of pricelist can fail with error `423` in case of running + import. tags: - 'Price lists' parameters: @@ -10015,7 +12161,17 @@ paths: $ref: '#/components/schemas/Errors' summary: 'List of all price list details' operationId: getListOfAllPricelistDetails - description: "Using this endpoint, you can get list of all price list details with information on each price (like in Price list Detail endpoint) asynchronously. See how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our developer’s portal.\n\nResponse will be in [jsonlines](https://jsonlines.org/) format with each product taking one line of output file. One price list in response has the same format as price list detail response.\n\nResult file is compressed using GZIP." + description: |- + Using this endpoint, you can get list of all price list details with information on each price + (like in Price list Detail endpoint) asynchronously. See how + [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our developer’s portal. + + + Response will be in [jsonlines](https://jsonlines.org/) format with each product taking one line of output file. + One price list in response has the same format as price list detail response. + + + Result file is compressed using GZIP. tags: - 'Price lists' parameters: @@ -10079,14 +12235,18 @@ paths: - name: orderableMinAmountFrom in: query - description: 'Export price list items with orderable minimal amount amount after given value' + description: |- + Export price list items with orderable minimal amount amount after + given value example: '10' schema: type: number - name: orderableMinAmountTo in: query - description: 'Export price list items with orderable minimal amount before given value' + description: |- + Export price list items with orderable minimal amount before given + value example: '100' schema: type: number @@ -10100,14 +12260,18 @@ paths: - name: orderableMaxAmountFrom in: query - description: 'Export price list items with orderable maximal amount after given value' + description: |- + Export price list items with orderable maximal amount after given + value example: '20' schema: type: number - name: orderableMaxAmountTo in: query - description: 'Export price list items with orderable maximal amount before given value' + description: |- + Export price list items with orderable maximal amount before given + value example: '200' schema: type: number @@ -10295,7 +12459,24 @@ paths: additionalProperties: false summary: 'List of orders' operationId: getListOfOrders - description: "List of orders in e-shop and cash desks. Endpoint supports [pagination](#section/basic-principles-of-working-with-api/Paging). For default calls, it returns 20 orders,\nusing the parameter `?itemsPerPage=100`, you can request up to 100 orders at a time. Temporarily disabled, only 20 orders per page is supported. We apologize for the inconvenience.\n\nThe list can be filtered according to status, transport, payment, date of creation, order number and customer number.\n\nThe code (`code`) is the order identifier. Although this is usually a number, it is necessary to take into account that this might also include\nletters, dash, etc." + description: |- + List of orders in e-shop and cash desks. Endpoint supports + [pagination](#section/basic-principles-of-working-with-api/Paging). For default calls, it returns 20 orders, + + using the parameter `?itemsPerPage=100`, you can request up to 100 + orders at a time. Temporarily disabled, only 20 orders per page is + supported. We apologize for the inconvenience. + + + The list can be filtered according to status, transport, payment, date + of creation, order number and customer number. + + + The code (`code`) is the order identifier. Although this is usually a + number, it is necessary to take into account that this might also + include + + letters, dash, etc. tags: - Orders parameters: @@ -10314,7 +12495,9 @@ paths: - name: shippingCompanyCode in: query - description: 'Purchase order filtering, according to forwarder [company code](#tag/shipping-methods/getlistofshippingmethods).' + description: |- + Purchase order filtering, according to forwarder [company + code](#tag/shipping-methods/getlistofshippingmethods). schema: type: string - @@ -10326,13 +12509,17 @@ paths: - name: creationTimeFrom in: query - description: 'Purchase order filtering, according to date of creation. ISO 8601 format ("2017-12-12T22:08:01+0100").' + description: |- + Purchase order filtering, according to date of creation. ISO 8601 + format ("2017-12-12T22:08:01+0100"). schema: type: string - name: creationTimeTo in: query - description: 'Purchase order filtering, according to date of creation. ISO 8601 format ("2017-12-12T22:08:01+0100").' + description: |- + Purchase order filtering, according to date of creation. ISO 8601 + format ("2017-12-12T22:08:01+0100"). schema: type: string - @@ -10356,13 +12543,17 @@ paths: - name: email in: query - description: 'Purchase order filtering, according to customer e-mail. The accurate match is searched for, regardless of capitalization.' + description: |- + Purchase order filtering, according to customer e-mail. The accurate + match is searched for, regardless of capitalization. schema: type: string - name: phone in: query - description: 'Purchase order filtering, according to customer phone. International format only (+420123456789)' + description: |- + Purchase order filtering, according to customer phone. International + format only (+420123456789) schema: type: string - @@ -10374,19 +12565,25 @@ paths: - name: changeTimeFrom in: query - description: 'Purchase order filtering, according to date of last update. ISO 8601 format ("2017-12-12T22:08:01+0100").' + description: |- + Purchase order filtering, according to date of last update. ISO 8601 + format ("2017-12-12T22:08:01+0100"). schema: type: string - name: changeTimeTo in: query - description: 'Purchase order filtering, according to date of last update. ISO 8601 format ("2017-12-12T22:08:01+0100").' + description: |- + Purchase order filtering, according to date of last update. ISO 8601 + format ("2017-12-12T22:08:01+0100"). schema: type: string - name: sourceId in: query - description: 'Order source filtering according to source id. For more information, see List of order sources endpoint.' + description: |- + Order source filtering according to source id. For more information, + see List of order sources endpoint. schema: type: string - @@ -10870,7 +13067,296 @@ paths: additionalProperties: false summary: 'Order insertion' operationId: createOrder - description: "This endpoint enables insert the order into Shoptet, which was created in other system. You can use it for an import\nfrom an older e-shop solution, or to transfer orders from external sales channels.\nA large amount of info can be set, but for regular usage only a few attributes are needed. Values of other\nattributes are added as per their default values. The detailed information can be found in the right pane, after\nclicking on title \"Order insertion\" above (search for \"Request\" and \"Attributes” sections).\n\nRequest is sent in JSON format in its body. Simple example (detailed example can be found in call example in right pane):\n\n```\n{\n \"data\": {\n \"email\": \"foo@bar.cz\",\n \"externalCode\": \"123\",\n \"paymentMethodGuid\": \"6f2c8e36-3faf-11e2-a723-705ab6a2ba75\",\n \"shippingGuid\": \"8921cdc1-051b-11e5-a8d3-ac162d8a2454\",\n \"billingAddress\": {\n \"fullName\": \"Jan Novák\",\n \"street\": \"Rovná\",\n \"city\": \"Rovina\",\n \"zip\": \"12300\"\n },\n \"currency\": {\n \"code\": \"CZK\"\n },\n \"items\": [\n {\n \"itemType\": \"product\",\n \"code\": \"32/ZEL\",\n \"vatRate\": \"21.00\",\n \"itemPriceWithVat\": \"121.00\"\n },\n {\n \"itemType\": \"billing\",\n \"name\": \"Platba převodem\",\n \"vatRate\": \"21.00\",\n \"itemPriceWithVat\": \"0\"\n },\n {\n \"itemType\": \"shipping\",\n \"name\": \"PPL\",\n \"vatRate\": \"21.00\",\n \"itemPriceWithVat\": \"59.00\"\n }\n ]\n }\n}\n```\n\nWhether the field is mandatory, apart from the basic definition, also depends on whether the order was created via the cash desk\n(`cashDeskOrder: true`) or via e-shop. Some fields from invoicing, delivery and contact data\nare mandatory or optional, as per e-shop settings (see also e-shop administration `Settings > Customers > Mandatory fields`).\n\nWhen the order is created, it is checked, whether the e-shop includes products with the respective code (can be suppressed with\nGET parameter `suppressProductChecking=true`),\nthe products from the order are deducted from the stock (can be suppressed with the GET parameter `suppressStockMovements=true`),\n documentation is created for the order (can be suppressed with the GET parameter `suppressDocumentGeneration=true`),\na confirmation e-mail is sent (can be suppressed with the GET parameter `suppressEmailSending=true`) and a webhook is executed for the new order.\n**Parameters `suppressProductChecking=true` and `suppressStockMovements=true` are to be used only for orders that will not be changed or deleted in the future.\nEditing or deleting such an order can damage the consistency of warehousing.**\n\nParameter `suppressHistoricalMandatoryFields=true` can be used to disable mandatory fields checks, but only for \"historical\"\norders (`creationTime` is older than 24 hours). Keep in mind even historical orders should be kept consistent and complete\nas much as possible to allow their processing for statistics, volume calculations etc.\n\nSetting the mandatory items for invoicing and the delivery address can be different between individual e-shops. The mandatory items corresponds to the settings\nfor ordering from the basket.\n\nParameters `suppressHistoricalPaymentChecking` and `suppressHistoricalShippingChecking` allow corresponding field (`paymentMethodGuid` and/or `shippingGuid`)\nto be `null`. In that case, if an billing/shipping item is provided in `items` list, `name` field must be filled in that item.\n\nTo remove products from the stock, the shop (or product) setting as to whether the inventory can be negative or not is respected.\nIf a negative value is not permitted for shopping and the order cannot be covered from the current inventory, the order is not created and the API\nreturns an error message in the `errors` field.\n\nThe order's minimum size or maximum number of items as per the settings of e-shop are not checked.\n\nThe endpoint only checks the same parameters as the order detail.\n\nThe order can be inserted while using currencies setup in the eshop (see `/api/eshop`). The exchange rate related to the\neshop default currency is optional. If not provided, the current eshop exchange rate will be used.\nFor historical orders the exchange rate should be provided using the historical value of the order's creation date.\nShoptet eshops do not store historical exchange rates.\nWarning: for SK and CZ different exchange rate format is used. You should use the same form as you get from the endpoint\n`/api/eshop`. We will internally convert it to the correct format to be compatible with eshop statistics calculations.\nBecause of the conversion, the value of `exchangeRate` in the response will be different (inverse) to the one you had sent.\n\nWhen entering the order, the initial welcome e-mail is always sent. Even though the order status is set differently to the initial value,\nthe e-mail associated with a status change is not sent, but the system welcome e-mail is (to e-shop operator and customer).\n\nWhen creating the receipt (invoice, proforma invoice, delivery note) the receipt is created with the current date and the 14 days due date, even though\n`creationTime` is given from the past.\n\nExamples of how to work with the order and items statuses, and how to ensure the correct insertion of a discount, can be found in a\nseparate [article at developers.shoptet.com](https://developers.shoptet.com/api/documentation/creating-order/)\n\nAfter the order is successfully created, you will receive a response with a 201 code and a response structure matching the order detail,\nwhich is returned by `/api/orders/` endpoint.\n\n**Please note following rules**\n\n- `code` .. maxLength 10 characters\n\n- `email` .. maxLength 100 characters\n\n- `phone` .. maxLength 32 characters\n\n- `externalCode` .. maxLength 255 characters\n\n- `billingAddress.company` .. maxLength 100 characters\n\n- `billingAddress.fullName` .. maxLength 100 characters\n\n- `billingAddress.street` .. maxLength 100 characters\n\n- `billingAddress.houseNumber` .. maxLength 16 characters\n\n- `billingAddress.city` .. maxLength 100 characters\n\n- `billingAddress.district` .. maxLength 64 characters\n\n- `billingAddress.additional` .. maxLength 64 characters\n\n- `billingAddress.zip` .. maxLength 100 characters\n\n- `billingAddress.regionName` .. maxLength 128 characters\n\n- `billingAddress.regionShortcut` .. maxLength 16 characters\n\n- `billingAddress.companyId` .. maxLength 18 characters\n\n- `billingAddress.vatId` .. maxLength 16 characters\n\n- `billingAddress.taxId` .. maxLength 16 characters\n\n- `deliveryAddress.company` .. maxLength 255 characters\n\n- `deliveryAddress.fullName` .. maxLength 64 characters\n\n- `deliveryAddress.street` .. maxLength 100 characters\n\n- `deliveryAddress.houseNumber` .. maxLength 16 characters\n\n- `deliveryAddress.city` .. maxLength 100 characters\n\n- `deliveryAddress.district` .. maxLength 64 characters\n\n- `deliveryAddress.additional` .. maxLength 64 characters\n\n- `deliveryAddress.zip` .. maxLength 100 characters\n\n- `deliveryAddress.regionName` .. maxLength 128 characters\n\n- `deliveryAddress.regionShortcut` .. maxLength 16 characters\n\n- `notes.trackingNumber` .. maxLength 32 characters\n\n- `items.name` .. maxLength 250 characters\n\n- `items.variantName` .. maxLength 128 characters\n\n- `items.brand` .. maxLength 64 characters\n\n- `items.supplierName` .. maxLength 255 characters\n\n- `items.code` .. maxLength 64 characters\n\n- `items.additionalField` .. maxLength 255 characters\n\n- `items.amountUnit` .. maxLength 16 characters" + description: |- + This endpoint enables insert the order into Shoptet, which was created + in other system. You can use it for an import + + from an older e-shop solution, or to transfer orders from external sales + channels. + + A large amount of info can be set, but for regular usage only a few + attributes are needed. Values of other + + attributes are added as per their default values. The detailed + information can be found in the right pane, after + + clicking on title "Order insertion" above (search for "Request" and + "Attributes” sections). + + + Request is sent in JSON format in its body. Simple example (detailed + example can be found in call example in right pane): + + + ``` + + { + "data": { + "email": "foo@bar.cz", + "externalCode": "123", + "paymentMethodGuid": "6f2c8e36-3faf-11e2-a723-705ab6a2ba75", + "shippingGuid": "8921cdc1-051b-11e5-a8d3-ac162d8a2454", + "billingAddress": { + "fullName": "Jan Novák", + "street": "Rovná", + "city": "Rovina", + "zip": "12300" + }, + "currency": { + "code": "CZK" + }, + "items": [ + { + "itemType": "product", + "code": "32/ZEL", + "vatRate": "21.00", + "itemPriceWithVat": "121.00" + }, + { + "itemType": "billing", + "name": "Platba převodem", + "vatRate": "21.00", + "itemPriceWithVat": "0" + }, + { + "itemType": "shipping", + "name": "PPL", + "vatRate": "21.00", + "itemPriceWithVat": "59.00" + } + ] + } + } + + ``` + + + Whether the field is mandatory, apart from the basic definition, also + depends on whether the order was created via the cash desk + + (`cashDeskOrder: true`) or via e-shop. Some fields from invoicing, + delivery and contact data + + are mandatory or optional, as per e-shop settings (see also e-shop + administration `Settings > Customers > Mandatory fields`). + + + When the order is created, it is checked, whether the e-shop includes + products with the respective code (can be suppressed with + + GET parameter `suppressProductChecking=true`), + + the products from the order are deducted from the stock (can be + suppressed with the GET parameter `suppressStockMovements=true`), + documentation is created for the order (can be suppressed with the GET parameter `suppressDocumentGeneration=true`), + a confirmation e-mail is sent (can be suppressed with the GET parameter + `suppressEmailSending=true`) and a webhook is executed for the new + order. + + **Parameters `suppressProductChecking=true` and + `suppressStockMovements=true` are to be used only for orders that will + not be changed or deleted in the future. + + Editing or deleting such an order can damage the consistency of + warehousing.** + + + Parameter `suppressHistoricalMandatoryFields=true` can be used to + disable mandatory fields checks, but only for "historical" + + orders (`creationTime` is older than 24 hours). Keep in mind even + historical orders should be kept consistent and complete + + as much as possible to allow their processing for statistics, volume + calculations etc. + + + Setting the mandatory items for invoicing and the delivery address can + be different between individual e-shops. The mandatory items corresponds + to the settings + + for ordering from the basket. + + + Parameters `suppressHistoricalPaymentChecking` and + `suppressHistoricalShippingChecking` allow corresponding field + (`paymentMethodGuid` and/or `shippingGuid`) + + to be `null`. In that case, if an billing/shipping item is provided in + `items` list, `name` field must be filled in that item. + + + To remove products from the stock, the shop (or product) setting as to + whether the inventory can be negative or not is respected. + + If a negative value is not permitted for shopping and the order cannot + be covered from the current inventory, the order is not created and the + API + + returns an error message in the `errors` field. + + + The order's minimum size or maximum number of items as per the settings + of e-shop are not checked. + + + The endpoint only checks the same parameters as the order detail. + + + The order can be inserted while using currencies setup in the eshop (see + `/api/eshop`). The exchange rate related to the + + eshop default currency is optional. If not provided, the current eshop + exchange rate will be used. + + For historical orders the exchange rate should be provided using the + historical value of the order's creation date. + + Shoptet eshops do not store historical exchange rates. + + Warning: for SK and CZ different exchange rate format is used. You + should use the same form as you get from the endpoint + + `/api/eshop`. We will internally convert it to the correct format to be + compatible with eshop statistics calculations. + + Because of the conversion, the value of `exchangeRate` in the response + will be different (inverse) to the one you had sent. + + + When entering the order, the initial welcome e-mail is always sent. Even + though the order status is set differently to the initial value, + + the e-mail associated with a status change is not sent, but the system + welcome e-mail is (to e-shop operator and customer). + + + When creating the receipt (invoice, proforma invoice, delivery note) the + receipt is created with the current date and the 14 days due date, even + though + + `creationTime` is given from the past. + + + Examples of how to work with the order and items statuses, and how to + ensure the correct insertion of a discount, can be found in a + + separate [article at + developers.shoptet.com](https://developers.shoptet.com/api/documentation/creating-order/) + + + After the order is successfully created, you will receive a response + with a 201 code and a response structure matching the order detail, + + which is returned by `/api/orders/` endpoint. + + + **Please note following rules** + + + - `code` .. maxLength 10 characters + + + - `email` .. maxLength 100 characters + + + - `phone` .. maxLength 32 characters + + + - `externalCode` .. maxLength 255 characters + + + - `billingAddress.company` .. maxLength 100 characters + + + - `billingAddress.fullName` .. maxLength 100 characters + + + - `billingAddress.street` .. maxLength 100 characters + + + - `billingAddress.houseNumber` .. maxLength 16 characters + + + - `billingAddress.city` .. maxLength 100 characters + + + - `billingAddress.district` .. maxLength 64 characters + + + - `billingAddress.additional` .. maxLength 64 characters + + + - `billingAddress.zip` .. maxLength 100 characters + + + - `billingAddress.regionName` .. maxLength 128 characters + + + - `billingAddress.regionShortcut` .. maxLength 16 characters + + + - `billingAddress.companyId` .. maxLength 18 characters + + + - `billingAddress.vatId` .. maxLength 16 characters + + + - `billingAddress.taxId` .. maxLength 16 characters + + + - `deliveryAddress.company` .. maxLength 255 characters + + + - `deliveryAddress.fullName` .. maxLength 64 characters + + + - `deliveryAddress.street` .. maxLength 100 characters + + + - `deliveryAddress.houseNumber` .. maxLength 16 characters + + + - `deliveryAddress.city` .. maxLength 100 characters + + + - `deliveryAddress.district` .. maxLength 64 characters + + + - `deliveryAddress.additional` .. maxLength 64 characters + + + - `deliveryAddress.zip` .. maxLength 100 characters + + + - `deliveryAddress.regionName` .. maxLength 128 characters + + + - `deliveryAddress.regionShortcut` .. maxLength 16 characters + + + - `notes.trackingNumber` .. maxLength 32 characters + + + - `items.name` .. maxLength 250 characters + + + - `items.variantName` .. maxLength 128 characters + + + - `items.brand` .. maxLength 64 characters + + + - `items.supplierName` .. maxLength 255 characters + + + - `items.code` .. maxLength 64 characters + + + - `items.additionalField` .. maxLength 255 characters + + + - `items.amountUnit` .. maxLength 16 characters tags: - Orders parameters: @@ -11593,14 +14079,50 @@ paths: $ref: '#/components/schemas/Errors' summary: 'List of all orders' operationId: getListOfAllOrders - description: "Using this endpoint, you can get list of all orders with detailed info of each order (like in Order Detail endpoint) asynchronously. See how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our developer's portal.\n\nThe list may be filtered by date of creation and order code. The code is the order identifier. Although this is usually a number, it is necessary to take into account that this might also include letters, dash, etc.\n\nResponse will be in [jsonlines](https://jsonlines.org/) format with each order taking one line of output file. One order in response has the same format as order detail response (in `data` attribute)\n\nThis endpoint has several sections, which are exported only when requested in the `include` parameter (see [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)).\n\nInclude parameter | Meaning\n--- | ---\n`notes` | Order remarks, including up to six additional fields, which can be freely used by e-shop for its individual needs. The field names can be defined in administration and this section returns their names.\n`images` | Order images\n`shippingDetails` | Transport details\n`stockLocation` | Position in the stock\n`surchargeParameters` | Item surcharge parameters\n`productFlags` | Item product flags\nResult file is compressed using GZIP." + description: |- + Using this endpoint, you can get list of all orders with detailed info of each order (like in Order Detail endpoint) + asynchronously. See how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our + developer's portal. + + + The list may be filtered by date of creation and order code. The code is the order identifier. Although this is usually + a number, it is necessary to take into account that this might also include letters, dash, etc. + + + Response will be in [jsonlines](https://jsonlines.org/) format with each order taking one line of output file. + One order in response has the same format as order detail response (in `data` attribute) + + + This endpoint has several sections, which are exported only when requested in the `include` parameter (see + [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)). + + + Include parameter | Meaning + + --- | --- + + `notes` | Order remarks, including up to six additional fields, which can be freely used by e-shop for its individual needs. The field names can be defined in administration and this section returns their names. + + `images` | Order images + + `shippingDetails` | Transport details + + `stockLocation` | Position in the stock + + `surchargeParameters` | Item surcharge parameters + + `productFlags` | Item product flags + + Result file is compressed using GZIP. tags: - Orders parameters: - name: include in: query - description: 'Optional parts of response. Available values are `notes,images,shippingDetails,stockLocation,surchargeParameters`.' + description: |- + Optional parts of response. Available values are + `notes,images,shippingDetails,stockLocation,surchargeParameters`. schema: type: string - @@ -11618,7 +14140,9 @@ paths: - name: shippingCompanyCode in: query - description: 'Purchase order filtering, according to forwarder [company code](#tag/shipping-methods/getlistofshippingmethods).' + description: |- + Purchase order filtering, according to forwarder [company + code](#tag/shipping-methods/getlistofshippingmethods). schema: type: string - @@ -11630,13 +14154,17 @@ paths: - name: creationTimeFrom in: query - description: 'Purchase order filtering, according to date of creation. ISO 8601 format ("2017-12-12T22:08:01+0100").' + description: |- + Purchase order filtering, according to date of creation. ISO 8601 + format ("2017-12-12T22:08:01+0100"). schema: type: string - name: creationTimeTo in: query - description: 'Purchase order filtering, according to date of creation. ISO 8601 format ("2017-12-12T22:08:01+0100").' + description: |- + Purchase order filtering, according to date of creation. ISO 8601 + format ("2017-12-12T22:08:01+0100"). schema: type: string - @@ -11660,13 +14188,17 @@ paths: - name: email in: query - description: 'Purchase order filtering, according to customer e-mail. The accurate match is searched for, regardless of capitalization.' + description: |- + Purchase order filtering, according to customer e-mail. The accurate + match is searched for, regardless of capitalization. schema: type: string - name: phone in: query - description: 'Purchase order filtering, according to customer phone. International format only (+420123456789)' + description: |- + Purchase order filtering, according to customer phone. International + format only (+420123456789) schema: type: string - @@ -11678,19 +14210,25 @@ paths: - name: changeTimeFrom in: query - description: 'Purchase order filtering, according to date of last update. ISO 8601 format ("2017-12-12T22:08:01+0100").' + description: |- + Purchase order filtering, according to date of last update. ISO 8601 + format ("2017-12-12T22:08:01+0100"). schema: type: string - name: changeTimeTo in: query - description: 'Purchase order filtering, according to date of last update. ISO 8601 format ("2017-12-12T22:08:01+0100").' + description: |- + Purchase order filtering, according to date of last update. ISO 8601 + format ("2017-12-12T22:08:01+0100"). schema: type: string - name: sourceId in: query - description: 'Order source filtering according to source id. For more information, see List of order sources endpoint.' + description: |- + Order source filtering according to source id. For more information, + see List of order sources endpoint. schema: type: string - @@ -12175,7 +14713,105 @@ paths: additionalProperties: false summary: 'Order detail' operationId: getOrderDetail - description: "This endpoint has several sections, which are only sent when requested in the `include` parameter (see\n[Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)).\n\nValue | Section\n--------|------\n`notes` | Order remarks, including up to six additional fields, which can be freely used by e-shop for its individual needs. The field names can be defined in administration and this section returns their names.\n`images`| Order images\n`shippingDetails`| Transport details\n`stockLocation`| Position in the stock\n`surchargeParameters`| Item surcharge parameters\n`productFlags`| Item product flags\n\nReturns the detail for one order. In the `items` field, the individual items of the order, including transport and payment methods.\n\nThe product name and variants, weight, manufacturer and similar items are copied into the order items when the order is made.\n Even though the products are changed later in the shop, the orders are not affected. `productGuid` item contains\nGUID of purchased product. If this is changed or deleted, the order is not affected. You have to take into account that\n\n`productGuid` does not have to refer to an existing product. The same goes for the `code` item, containing the identification of a purchased\n\nvariant or product. You have to take into account that when deleting the product or changing the `code` of the product, the reference from the order\n\nis lost. In other words, you have to take into account the fact that the `code` or `productGuid` do not have to refer to one of the currently existing\n\nproducts (variant). They may also be `null`.\n\nIn most cases the items in the response are the same as you can see in the administration of PDF printout of an order.\n\nThere are however some advanced cases (in case of coupon discount with absolute value or in case of\n\na volume discount and products with multiple VAT rates in the order), in which case they are different:\n\n- Administration and PDF will show multiple rows for the discount – for each VAT rate one row and the price field split evenly.\n\n- The API response will return only one row indicating the total price of the discount.\n\nThe difference is based on how data is internally stored and presented. The API is bases more on internal storage principle,\n\nthere is however also an array `displayPrices`, which contains the presentation (printout) version of each item.\n\nIf you state the `include=images` parameter within the URL, the information about the main image for all products in the order\n will also be part of the response. For more information about access to images go to [Product images](#section/Product-images).\n\nIn the `shippingDetails` section, there is an information about shipping the order. `branchId` is used for the identification of the carrier's branch and\n\nnext fields are used for the detail of the branch (name, address, etc.). `carrierId` is used for the numeral identification of the carrier. Nowadays this field\n\nis used for Zasilkovna only and the value can be `null` for Czech Zasilkovna or integer for Zasilkovna in the other countries." + description: |- + This endpoint has several sections, which are only sent when requested + in the `include` parameter (see + + [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)). + + + Value | Section + + --------|------ + + `notes` | Order remarks, including up to six additional fields, which + can be freely used by e-shop for its individual needs. The field names + can be defined in administration and this section returns their names. + + `images`| Order images + + `shippingDetails`| Transport details + + `stockLocation`| Position in the stock + + `surchargeParameters`| Item surcharge parameters + + `productFlags`| Item product flags + + + Returns the detail for one order. In the `items` field, the individual + items of the order, including transport and payment methods. + + + The product name and variants, weight, manufacturer and similar items + are copied into the order items when the order is made. + Even though the products are changed later in the shop, the orders are not affected. `productGuid` item contains + GUID of purchased product. If this is changed or deleted, the order is + not affected. You have to take into account that + + + `productGuid` does not have to refer to an existing product. The same + goes for the `code` item, containing the identification of a purchased + + + variant or product. You have to take into account that when deleting the + product or changing the `code` of the product, the reference from the + order + + + is lost. In other words, you have to take into account the fact that the + `code` or `productGuid` do not have to refer to one of the currently + existing + + + products (variant). They may also be `null`. + + + In most cases the items in the response are the same as you can see in + the administration of PDF printout of an order. + + + There are however some advanced cases (in case of coupon discount with + absolute value or in case of + + + a volume discount and products with multiple VAT rates in the order), in + which case they are different: + + + - Administration and PDF will show multiple rows for the discount – for + each VAT rate one row and the price field split evenly. + + + - The API response will return only one row indicating the total price + of the discount. + + + The difference is based on how data is internally stored and presented. + The API is bases more on internal storage principle, + + + there is however also an array `displayPrices`, which contains the + presentation (printout) version of each item. + + + If you state the `include=images` parameter within the URL, the + information about the main image for all products in the order + will also be part of the response. For more information about access to images go to [Product images](#section/Product-images). + + + In the `shippingDetails` section, there is an information about shipping + the order. `branchId` is used for the identification of the carrier's + branch and + + + next fields are used for the detail of the branch (name, address, etc.). + `carrierId` is used for the numeral identification of the carrier. + Nowadays this field + + + is used for Zasilkovna only and the value can be `null` for Czech + Zasilkovna or integer for Zasilkovna in the other countries. tags: - Orders parameters: @@ -12728,7 +15364,60 @@ paths: additionalProperties: false summary: 'Order head change' operationId: updateOrderHead - description: "You can change basic info (head) of order with this method.\n\n**Please note following rules**\n\n- `email` .. maxLength 100 characters\n\n- `phone` .. maxLength 32 characters\n\n- `billingAddress.company` .. maxLength 100 characters\n\n- `billingAddress.fullName` .. maxLength 100 characters\n\n- `billingAddress.street` .. maxLength 100 characters\n\n- `billingAddress.houseNumber` .. maxLength 16 characters\n\n- `billingAddress.city` .. maxLength 100 characters\n\n- `billingAddress.district` .. maxLength 64 characters\n\n- `billingAddress.additional` .. maxLength 64 characters\n\n- `billingAddress.zip` .. maxLength 100 characters\n\n- `billingAddress.regionName` .. maxLength 128 characters\n\n- `billingAddress.regionShortcut` .. maxLength 16 characters\n\n- `billingAddress.companyId` .. maxLength 18 characters\n\n- `billingAddress.vatId` .. maxLength 16 characters\n\n- `billingAddress.taxId` .. maxLength 16 characters\n\n- `deliveryAddress.company` .. maxLength 255 characters\n\n- `deliveryAddress.fullName` .. maxLength 64 characters\n\n- `deliveryAddress.street` .. maxLength 100 characters\n\n- `deliveryAddress.houseNumber` .. maxLength 16 characters\n\n- `deliveryAddress.city` .. maxLength 100 characters\n\n- `deliveryAddress.district` .. maxLength 64 characters\n\n- `deliveryAddress.additional` .. maxLength 64 characters\n\n- `deliveryAddress.zip` .. maxLength 100 characters\n\n- `deliveryAddress.regionName` .. maxLength 128 characters\n\n- `deliveryAddress.regionShortcut` .. maxLength 16 characters" + description: |- + You can change basic info (head) of order with this method. + + **Please note following rules** + + - `email` .. maxLength 100 characters + + - `phone` .. maxLength 32 characters + + - `billingAddress.company` .. maxLength 100 characters + + - `billingAddress.fullName` .. maxLength 100 characters + + - `billingAddress.street` .. maxLength 100 characters + + - `billingAddress.houseNumber` .. maxLength 16 characters + + - `billingAddress.city` .. maxLength 100 characters + + - `billingAddress.district` .. maxLength 64 characters + + - `billingAddress.additional` .. maxLength 64 characters + + - `billingAddress.zip` .. maxLength 100 characters + + - `billingAddress.regionName` .. maxLength 128 characters + + - `billingAddress.regionShortcut` .. maxLength 16 characters + + - `billingAddress.companyId` .. maxLength 18 characters + + - `billingAddress.vatId` .. maxLength 16 characters + + - `billingAddress.taxId` .. maxLength 16 characters + + - `deliveryAddress.company` .. maxLength 255 characters + + - `deliveryAddress.fullName` .. maxLength 64 characters + + - `deliveryAddress.street` .. maxLength 100 characters + + - `deliveryAddress.houseNumber` .. maxLength 16 characters + + - `deliveryAddress.city` .. maxLength 100 characters + + - `deliveryAddress.district` .. maxLength 64 characters + + - `deliveryAddress.additional` .. maxLength 64 characters + + - `deliveryAddress.zip` .. maxLength 100 characters + + - `deliveryAddress.regionName` .. maxLength 128 characters + + - `deliveryAddress.regionShortcut` .. maxLength 16 characters tags: - Orders parameters: @@ -13748,7 +16437,9 @@ paths: - name: id in: path - description: 'order item id. Can be found in field `data.order.items.itemId` in Order detail. (number)' + description: |- + order item id. Can be found in field `data.order.items.itemId` in + Order detail. (number) required: true example: '198' schema: @@ -13960,7 +16651,9 @@ paths: - name: id in: path - description: 'order item id. Can be found in field `data.order.items.itemId` in Order detail. (number)' + description: |- + order item id. Can be found in field `data.order.items.itemId` in + Order detail. (number) required: true example: '198' schema: @@ -14447,7 +17140,33 @@ paths: additionalProperties: false summary: 'Order item surcharge parameters insertion' operationId: createOrderItemSurchargeParameters - description: "There is possibility to edit surcharge parameters related to order item. For that purpose, there is in get order item detail endpoint attribute `specificSurchargeParameters` which returned adjusted surcharge parameters data (see order item detail [endpoint](#tag/orders/getorderdetail))\n\nThis mean that `surchargeParameters` attribute in order detail is persistent and any adjustment in surcharge parameters appears in `specificSurchargeParameters`\n\nThis endpoint purpose is to add surcharge parameter in relation within order item.\nYou have to send one of attributes `parameterCode` with `valueIndex` or `name`. Cant send this attributes together.\nIf you post `parameterCode` and `valueIndex`, there will be validation, if surcharge parameter exits and if can be related\nto order item's product and price (if not send) will be added from surcharge parameter itself.\n\nOtherwise you can send attribute `name` instead, which could have any form, but has to be unique. If price is not send,\nthan it will be set to `0.00`." + description: |- + There is possibility to edit surcharge parameters related to order item. For that purpose, there is in + get order item detail endpoint attribute `specificSurchargeParameters` which returned adjusted surcharge + parameters data (see order item detail [endpoint](#tag/orders/getorderdetail)) + + + This mean that `surchargeParameters` attribute in order detail is persistent and any adjustment in + surcharge parameters appears in `specificSurchargeParameters` + + + This endpoint purpose is to add surcharge parameter in relation within + order item. + + You have to send one of attributes `parameterCode` with `valueIndex` or + `name`. Cant send this attributes together. + + If you post `parameterCode` and `valueIndex`, there will be validation, + if surcharge parameter exits and if can be related + + to order item's product and price (if not send) will be added from + surcharge parameter itself. + + + Otherwise you can send attribute `name` instead, which could have any + form, but has to be unique. If price is not send, + + than it will be set to `0.00`. tags: - Orders parameters: @@ -14535,7 +17254,9 @@ paths: additionalProperties: false summary: 'Order item surcharge parameters deletion' operationId: deleteOrderItemSurchargeParameters - description: 'You have to provide dynamically generated `relationId` which identify which surcharge parameter related to order item you want to delete.' + description: |- + You have to provide dynamically generated `relationId` which identify + which surcharge parameter related to order item you want to delete. tags: - Orders parameters: @@ -14558,7 +17279,9 @@ paths: - name: relationId in: path - description: 'key to identify, which surcharge parameter in relation to order item, should be delete' + description: |- + key to identify, which surcharge parameter in relation to order + item, should be delete required: true example: '04e876' schema: @@ -15864,11 +18587,18 @@ paths: errors: - errorCode: document-not-generated - message: 'Error while getting document type "order" with code "2018000004".' + message: |- + Error while getting document type "order" with code + "2018000004". instance: '2018000004' summary: 'Download order as PDF' operationId: downloadOrderAsPdf - description: "You can request the order as PDF file, response will be as application/octet-stream. You can download pdf documents\nonly one-by-one for every e-shop. Parallel requests end with `423 Locked` error." + description: |- + You can request the order as PDF file, response will be as + application/octet-stream. You can download pdf documents + + only one-by-one for every e-shop. Parallel requests end with `423 + Locked` error. tags: - Orders parameters: @@ -15960,7 +18690,18 @@ paths: additionalProperties: false summary: 'List of remarks for the order' operationId: getListOfRemarksForOrder - description: "The endpoint shows the order history which is displayed in Shoptet administration in the\n“History” tab, in the order detail. Thus they are the most important system actions that have affected the order (they cannot be\nchanged by the user) and then the notes added by the e-shop, primarily intended as messages between several employees,\nwhich may be needed to coordinate the order processing (these can be entered and deleted by the user)." + description: |- + The endpoint shows the order history which is displayed in Shoptet + administration in the + + “History” tab, in the order detail. Thus they are the most important + system actions that have affected the order (they cannot be + + changed by the user) and then the notes added by the e-shop, primarily + intended as messages between several employees, + + which may be needed to coordinate the order processing (these can be + entered and deleted by the user). tags: - Orders parameters: @@ -16021,7 +18762,7 @@ paths: - errorCode: order-history-item-exceeded-limit message: 'Order history item count limit exceeded (100) for order "2018000012".' - instance: 2018000012 + instance: '2018000012' 404: description: 'Not Found' content: @@ -16042,7 +18783,19 @@ paths: instance: '2018000012' summary: 'Insertion of remark to order' operationId: createOrderRemark - description: "This endpoint may be used to add the user remark into the order history.\nFor example the payment gateway may give the payment identification at its side, or\nadd the remarks during the process of payment or order processing. The remarks\nare displayed in administration, in the “History” tab, in the order detail,\ntogether with main system changes of the order." + description: |- + This endpoint may be used to add the user remark into the order history. + + For example the payment gateway may give the payment identification at + its side, or + + add the remarks during the process of payment or order processing. The + remarks + + are displayed in administration, in the “History” tab, in the order + detail, + + together with main system changes of the order. tags: - Orders parameters: @@ -16114,7 +18867,7 @@ paths: - errorCode: order-history-deletion-failed message: 'Cannot delete order history item "2073".' - instance: 2073 + instance: '2073' summary: 'Delete order history item' operationId: deleteOrderHistoryItem description: 'Delete order history item by primary key.' @@ -16181,7 +18934,38 @@ paths: instance: '2018000012' summary: 'Update remarks for the order' operationId: updateRemarksForOrder - description: "The endpoint enables the remarks and additional fields (index 1 - 6) to be updated for the order. Within a call, the update\nof more data can be called for.\n\nThe individual data object keys are not optional. Only the key values, which are included in the data object, will be updated.\n\nIf \"customerRemark\", \"trackingNumber\", \"eshopRemark\" have a value of NULL, the originally saved value will be deleted.\n\nFor additional fields (\"additionalFields” key) only the fields included in this field are updated.\n\nIf the key value is \"text\" for NULL additional field, the originally saved text in this field will be deleted.\n\nIf the non-existing key is entered, or the call is erroneous in another way, no item is updated.\n\n**Please note that `trackingNumber` cannot be longer than 32 characters.**\n**Please note that `additionalField` with index 1, 2 & 3 cannot be longer than 255 characters.**" + description: |- + The endpoint enables the remarks and additional fields (index 1 - 6) to + be updated for the order. Within a call, the update + + of more data can be called for. + + + The individual data object keys are not optional. Only the key values, + which are included in the data object, will be updated. + + + If "customerRemark", "trackingNumber", "eshopRemark" have a value of + NULL, the originally saved value will be deleted. + + + For additional fields ("additionalFields” key) only the fields included + in this field are updated. + + + If the key value is "text" for NULL additional field, the originally + saved text in this field will be deleted. + + + If the non-existing key is entered, or the call is erroneous in another + way, no item is updated. + + + **Please note that `trackingNumber` cannot be longer than 32 + characters.** + + **Please note that `additionalField` with index 1, 2 & 3 cannot be + longer than 255 characters.** tags: - Orders parameters: @@ -16720,7 +19504,72 @@ paths: instance: '2018000012' summary: 'Update of order status' operationId: updateOrderStatus - description: "The endpoint enables the order status, “paid” flag and payment method to be updated. This data must be set during a call.\nAll the fields to be updated are optional, but at least one has to be specified.\n\nIf the key value is \"text\" for NULL additional field, the originally saved text in this field will be deleted.\n\nIf a non-existing key is entered, or the call is erroneous in another way, no item is updated.\n\nIf you call the status setting within your request, which has \"set the order as paid\" in the definition, and at the same time you required\na change of `paid` to `false`, the order status will be carried out and the `paid` value set to `false`.\n\nIf the status definition includes sending an e-mail, such an e-mail will be sent. If not required, sending an e-mail can be suppressed with the\n`?suppressEmailSending=true` parameter. Similarly, sending information SMS messages when the order is changed (if set) can be suppressed\n with the `?suppressSmsSending=true` parameter. In analogy, if the status includes document generation (for example a proforma invoice),\nthe document will be generated (if not existent). The generation can be suppressed with the `?suppressDocumentGeneration=true` parameter.\n\nThis endpoint tries not to unnecessarily change the order status. If you try to set the status that the order already has, no change is done and no document is generated.\nWhen calling the same requests in parallel, there is the risk that there may be concurrence and related actions may be executed twice. Therefore we recommend calling this request from one source only, in a serial manner.\n\nOrder status change might imply automatic documents (e. g. invoice) generation. In exceptional cases the generation might fail,\nalthough the order status itself gets actually changed. In such case the API return status code 200 (OK), but in the `data` field\nyou can find the order details and in the `errors` array eventually details about the failed documents generation. The error\ncode is `document-not-generated`. Example of an error message:\n\n```\n\"errors\": [\n {\n \"errorCode\": \"document-not-generated\",\n \"message\": \"Delivery note belonging to order \\\"2020000149\\\" was not created. Generating document code failed.\",\n \"instance\": \"2020000149\"\n }\n]\n```" + description: |- + The endpoint enables the order status, “paid” flag and payment method to + be updated. This data must be set during a call. + + All the fields to be updated are optional, but at least one has to be + specified. + + + If the key value is "text" for NULL additional field, the originally + saved text in this field will be deleted. + + + If a non-existing key is entered, or the call is erroneous in another + way, no item is updated. + + + If you call the status setting within your request, which has "set the + order as paid" in the definition, and at the same time you required + + a change of `paid` to `false`, the order status will be carried out and + the `paid` value set to `false`. + + + If the status definition includes sending an e-mail, such an e-mail will + be sent. If not required, sending an e-mail can be suppressed with the + + `?suppressEmailSending=true` parameter. Similarly, sending information + SMS messages when the order is changed (if set) can be suppressed + with the `?suppressSmsSending=true` parameter. In analogy, if the status includes document generation (for example a proforma invoice), + the document will be generated (if not existent). The generation can be + suppressed with the `?suppressDocumentGeneration=true` parameter. + + + This endpoint tries not to unnecessarily change the order status. If you + try to set the status that the order already has, no change is done and + no document is generated. + + When calling the same requests in parallel, there is the risk that there + may be concurrence and related actions may be executed twice. Therefore + we recommend calling this request from one source only, in a serial + manner. + + + Order status change might imply automatic documents (e. g. invoice) + generation. In exceptional cases the generation might fail, + + although the order status itself gets actually changed. In such case the + API return status code 200 (OK), but in the `data` field + + you can find the order details and in the `errors` array eventually + details about the failed documents generation. The error + + code is `document-not-generated`. Example of an error message: + + + ``` + + "errors": [ + { + "errorCode": "document-not-generated", + "message": "Delivery note belonging to order \"2020000149\" was not created. Generating document code failed.", + "instance": "2020000149" + } + ] + + ``` tags: - Orders parameters: @@ -17015,7 +19864,19 @@ paths: additionalProperties: false summary: 'Last order changes' operationId: getLastOrderChanges - description: "The Endpoint is intended to determine the changes after you have loaded the complete list of orders and you need to know, if any of these has been changed (or deleted). Guaranteed history is 30 days, the older data are deleted progressively.\n\nEach order in the log is only mentioned with its last change. For example, if the order was modified and then deleted, the log will only show information about its deletion.\n\nCreation is considered as `edit` action. So, when there is a new item created, it will be displayed like `edit` action.\n\nEndpoint supports [pagination](#section/basic-principles-of-working-with-api/Paging)." + description: |- + The Endpoint is intended to determine the changes after you have loaded the complete list of orders and you need to know, + if any of these has been changed (or deleted). Guaranteed history is 30 days, the older data are deleted progressively. + + + Each order in the log is only mentioned with its last change. For example, if the order was modified and then deleted, + the log will only show information about its deletion. + + + Creation is considered as `edit` action. So, when there is a new item created, it will be displayed like `edit` action. + + + Endpoint supports [pagination](#section/basic-principles-of-working-with-api/Paging). tags: - Orders parameters: @@ -17057,7 +19918,9 @@ paths: additionalProperties: false summary: 'Get order gifts list' operationId: getOrderGiftsList - description: 'This endpoint allow get, add or delete order related gifts. Gifts is relation to product variant by its `code` identifier and is ordered by `priority` field' + description: |- + This endpoint allow get, add or delete order related gifts. Gifts is relation to product variant by its + `code` identifier and is ordered by `priority` field tags: - Orders parameters: @@ -17090,7 +19953,11 @@ paths: additionalProperties: false summary: 'Add order gift at the end of the list' operationId: addOrderGift - description: "Add order gift (product variant) at the end of the order gift list. Gift is defined by `code`.\n`code`, `orderPrice` and `currencyCode` is required." + description: |- + Add order gift (product variant) at the end of the order gift list. Gift + is defined by `code`. + + `code`, `orderPrice` and `currencyCode` is required. tags: - Orders requestBody: @@ -17211,7 +20078,12 @@ paths: additionalProperties: false summary: 'Get order gift settings' operationId: getOrderGiftSettings - description: "There are order gift setting, which influence general behaviour.\n- The behavior of the gifts - set if gifts are dependent on each product or whole order (stock dependent/independent) - Offer to wholesale customers - define if customer with wholesale module have gifts offer available - Gift to whole order or each product" + description: |- + There are order gift setting, which influence general behaviour. + + - The behavior of the gifts - set if gifts are dependent on each product or whole order (stock dependent/independent) + - Offer to wholesale customers - define if customer with wholesale module have gifts offer available + - Gift to whole order or each product tags: - Orders parameters: @@ -17257,7 +20129,9 @@ paths: additionalProperties: false summary: 'Update order gift settings' operationId: updateOrderGiftSettings - description: 'Method updates order gift settings. Every item in request body is optional, but at least one setting is required.' + description: |- + Method updates order gift settings. Every item in request body is + optional, but at least one setting is required. tags: - Orders requestBody: @@ -17396,7 +20270,14 @@ paths: additionalProperties: false summary: 'List of invoices' operationId: getListOfInvoices - description: "Returns the list of invoices with basic information. The list of invoices supports [paging](#section/basic-principles-of-working-with-api/Paging)\n\nThe code (`code`) is the invoice identifier. Although this is usually a number, it is necessary to take into account that this might also include letters, a dash, etc. Filtering uses string comparison with >=, <= operators." + description: |- + Returns the list of invoices with basic information. + The list of invoices supports [paging](#section/basic-principles-of-working-with-api/Paging) + + + The code (`code`) is the invoice identifier. Although this is usually a number, + it is necessary to take into account that this might also include + letters, a dash, etc. Filtering uses string comparison with >=, <= operators. tags: - Invoices parameters: @@ -17479,7 +20360,28 @@ paths: type: string summary: 'List of all invoices' operationId: getListOfAllInvoices - description: "Using this endpoint, you can get list of all invoices with detailed info of each invoice (like in Invoice Detail endpoint) asynchronously. See how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our developer's portal.\n\nResponse will be in [jsonlines](https://jsonlines.org/) format with each product taking one line of output file. One invoice in response has the same format as invoice detail response.\n\nResult file is compressed using GZIP.\n\nThis endpoint has several sections, which are only sent when requested in the `include` parameter (see [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)).\n\nValue | Section\n--------|------\n`surchargeParameters`| Item surcharge parameters" + description: |- + Using this endpoint, you can get list of all invoices with detailed info of each invoice (like in Invoice Detail endpoint) + asynchronously. See how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our + developer's portal. + + + Response will be in [jsonlines](https://jsonlines.org/) format with each product taking one line of output file. + One invoice in response has the same format as invoice detail response. + + + Result file is compressed using GZIP. + + + This endpoint has several sections, which are only sent when requested in the `include` parameter (see + [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)). + + + Value | Section + + --------|------ + + `surchargeParameters`| Item surcharge parameters tags: - Invoices parameters: @@ -17830,7 +20732,31 @@ paths: instance: '000000000633' summary: 'Invoice detail' operationId: getInvoiceDetail - description: "Detailed information about one invoice.\n\nIn most cases the items in the response are the same as you can see in the administration of PDF printout of an invoice. There are however some advanced cases (in case of coupon discount with absolute value or in case of a volume discount and products with multiple VAT rates in the invoice), in which case they are different:\n\n- Administration and PDF will show multiple rows for the discount – for each VAT rate one row and the price field split evenly. - API response will return only one row indication the total discount price.\n\nThe difference is based on how data is internally stored and presented. The API is bases more on internal storage principle, there is however also an array `displayPrices`, which contains the presentation (printout) form of each item.\n\nThis endpoint has several sections, which are only sent when requested in the `include` parameter (see [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)).\nValue | Section\n--------|------\n`surchargeParameters`| Item surcharge parameters" + description: |- + Detailed information about one invoice. + + + In most cases the items in the response are the same as you can see in the administration of PDF printout of an invoice. + There are however some advanced cases (in case of coupon discount with absolute value or in case of + a volume discount and products with multiple VAT rates in the invoice), in which case they are different: + + + - Administration and PDF will show multiple rows for the discount – for each VAT rate one row and the price field split evenly. + - API response will return only one row indication the total discount price. + + + The difference is based on how data is internally stored and presented. The API is bases more on internal storage principle, + there is however also an array `displayPrices`, which contains the presentation (printout) form of each item. + + + This endpoint has several sections, which are only sent when requested in the `include` parameter (see + [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)). + + Value | Section + + --------|------ + + `surchargeParameters`| Item surcharge parameters tags: - Invoices parameters: @@ -18039,7 +20965,9 @@ paths: - name: suppressExistenceCheck in: query - description: 'suppress checking of existing invoices per order (allows multiple invoices per order)' + description: |- + suppress checking of existing invoices per order (allows multiple + invoices per order) example: 'true' schema: type: string @@ -18310,11 +21238,15 @@ paths: errors: - errorCode: proof-payments-already-linked-to-invoice - message: 'Proof payment with code "O-2017000017-01" is already linked to the invoice "%s".' + message: |- + Proof payment with code "O-2017000017-01" is already linked + to the invoice "%s". instance: data.proofPaymentCodes - errorCode: proof-payments-closed - message: 'Proof payment with code "O-2017000044-01" is closed. Unlock proof payment first.' + message: |- + Proof payment with code "O-2017000044-01" is closed. Unlock + proof payment first. instance: O-2017000044-01 schema: type: object @@ -18332,11 +21264,15 @@ paths: errors: - errorCode: proof-payments-not-related-to-order - message: 'Proof payment with code "O-2017000017-01" is not related to the order with code "2017000044".' + message: |- + Proof payment with code "O-2017000017-01" is not related to + the order with code "2017000044". instance: data.proofPaymentCodes - errorCode: proof-payments-and-invoice-has-different-currency - message: 'Proof payment with code "O-2017000017-01" is not in the same currency as the invoice "2017100013".' + message: |- + Proof payment with code "O-2017000017-01" is not in the same + currency as the invoice "2017100013". instance: data.proofPaymentCodes - errorCode: proof-payments-invalid @@ -18351,7 +21287,19 @@ paths: $ref: '#/components/schemas/Errors' summary: 'Invoice link proof payments' operationId: invoiceLinkProofPayments - description: "Linking proof payments to invoice. Proof payments must be related to the order, must be in same currency as the order, must be valid and cannot be linked to another invoice.\n\nThis endpoint has several sections, which are only sent when requested in the `include` parameter (see [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)).\nValue | Section\n--------|------\n`surchargeParameters`| Item surcharge parameters" + description: |- + Linking proof payments to invoice. Proof payments must be related to the order, must be in same currency + as the order, must be valid and cannot be linked to another invoice. + + + This endpoint has several sections, which are only sent when requested in the `include` parameter (see + [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)). + + Value | Section + + --------|------ + + `surchargeParameters`| Item surcharge parameters tags: - Invoices parameters: @@ -18437,11 +21385,17 @@ paths: errors: - errorCode: document-not-generated - message: 'Error while getting document type "invoice" with code "2018000004".' + message: |- + Error while getting document type "invoice" with code + "2018000004". instance: '2018000004' summary: 'Download invoice as PDF' operationId: downloadInvoiceAsPdf - description: 'You can request the invoice as PDF file, response will be as application/octet-stream. You can download pdf documents only one-by-one for every e-shop. Parallel requests end with `423 Locked` error.' + description: |- + You can request the invoice as PDF file, response will be as + application/octet-stream. You can download pdf documents + only one-by-one for every e-shop. Parallel requests end with `423 + Locked` error. tags: - Invoices parameters: @@ -18492,11 +21446,17 @@ paths: errors: - errorCode: document-not-generated - message: 'Error while getting document type "invoice" with code "2018000004".' + message: |- + Error while getting document type "invoice" with code + "2018000004". instance: '2018000004' summary: 'Download invoice as ISDOC' operationId: downloadInvoiceAsIsdoc - description: 'You can request the invoice as ISDOC file, response will be as application/octet-stream. You can download pdf documents only one-by-one for every e-shop. Parallel requests end with `423 Locked` error.' + description: |- + You can request the invoice as ISDOC file, response will be as + application/octet-stream. You can download pdf documents + only one-by-one for every e-shop. Parallel requests end with `423 + Locked` error. tags: - Invoices parameters: @@ -18560,7 +21520,20 @@ paths: additionalProperties: false summary: 'Last invoice changes' operationId: getLastInvoiceChanges - description: "Returns the list of invoices, which were changed (added/changed or deleted). Endpoint is intended to determine the changes after you have loaded the complete list of invoices and you need to know if any of these was been changed (or deleted). Guaranteed history is 30 days, the older data are deleted progressively.\n\nEach invoice in the log is only mentioned with its last change. For example, if the invoice was modified and then deleted, the log will only show information about its deletion.\n\nCreation is considered as `edit` action. So, when there is a new item created, it will be displayed like `edit` action.\n\nEndpoint supports [pagination](#section/basic-principles-of-working-with-api/Paging)." + description: |- + Returns the list of invoices, which were changed (added/changed or deleted). Endpoint is intended to determine + the changes after you have loaded the complete list of invoices and you need to know if any of these was been changed (or + deleted). Guaranteed history is 30 days, the older data are deleted progressively. + + + Each invoice in the log is only mentioned with its last change. For example, if the invoice was modified and then deleted, + the log will only show information about its deletion. + + + Creation is considered as `edit` action. So, when there is a new item created, it will be displayed like `edit` action. + + + Endpoint supports [pagination](#section/basic-principles-of-working-with-api/Paging). tags: - Invoices parameters: @@ -18663,7 +21636,9 @@ paths: additionalProperties: false summary: 'List of proforma invoices' operationId: getListOfProformaInvoices - description: 'Returns the list of proforma invoices. Supports the [pagination](#section/basic-principles-of-working-with-api/Paging).' + description: |- + Returns the list of proforma invoices. Supports the + [pagination](#section/basic-principles-of-working-with-api/Paging). tags: - 'Proforma invoices' parameters: @@ -18682,13 +21657,17 @@ paths: - name: creationTimeFrom in: query - description: 'filtering items created after or same as requested datetime. ISO 8601 format ("2017-12-12T22:08:01+0100").' + description: |- + filtering items created after or same as requested datetime. ISO + 8601 format ("2017-12-12T22:08:01+0100"). schema: type: string - name: creationTimeTo in: query - description: 'filtering items created before or same as requested datetime. ISO 8601 format ("2017-12-12T22:08:01+0100")' + description: |- + filtering items created before or same as requested datetime. ISO + 8601 format ("2017-12-12T22:08:01+0100") schema: type: string - @@ -18890,7 +21869,17 @@ paths: instance: '000000000633' summary: 'Proforma invoice detail' operationId: getProformaInvoiceDetail - description: "Additional information about one proforma invoice.\nThis endpoint has several sections, which are only sent when requested in the `include` parameter (see [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)).\nValue | Section\n--------|------\n`surchargeParameters`| Item surcharge parameters" + description: |- + Additional information about one proforma invoice. + + This endpoint has several sections, which are only sent when requested in the `include` parameter (see + [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)). + + Value | Section + + --------|------ + + `surchargeParameters`| Item surcharge parameters tags: - 'Proforma invoices' parameters: @@ -18951,11 +21940,18 @@ paths: errors: - errorCode: document-not-generated - message: 'Error while getting document type "proformaInvoice" with code "2018000035".' + message: |- + Error while getting document type "proformaInvoice" with + code "2018000035". instance: '2018000035' summary: 'Download proforma invoice as PDF' operationId: downloadProformaInvoicePdf - description: "You can request the proforma invoice as PDF file, response will be as application/octet-stream. You can download pdf documents\nonly one-by-one for every e-shop. Parallel requests end with `423 Locked` error." + description: |- + You can request the proforma invoice as PDF file, response will be as + application/octet-stream. You can download pdf documents + + only one-by-one for every e-shop. Parallel requests end with `423 + Locked` error. tags: - 'Proforma invoices' parameters: @@ -19120,7 +22116,9 @@ paths: - name: issueDate in: query - description: 'filtering according to date on which was proof payment issued. In ISO 8601 format. Optional.' + description: |- + filtering according to date on which was proof payment issued. In + ISO 8601 format. Optional. required: false example: '2024-12-24T15:22:02+0200' schema: @@ -19409,7 +22407,9 @@ paths: errors: - errorCode: proof-payments-closed - message: 'Proof payment with code "P--0000000000-1" is closed. Unlock proof payment first.' + message: |- + Proof payment with code "P--0000000000-1" is closed. Unlock + proof payment first. instance: P--0000000000-1 schema: type: object @@ -19420,7 +22420,15 @@ paths: $ref: '#/components/schemas/Errors' summary: 'Proof payment update' operationId: updateProofPayment - description: "If the proof payment is closed, response code `409` is returned and the document cannot be updated. Proof payment is closed if:\n\n- proof payment is/was linked to the invoice or\n\n- there is a manual lock of proof payment." + description: |- + If the proof payment is closed, response code `409` is returned and the + document cannot be updated. Proof payment is closed if: + + + - proof payment is/was linked to the invoice or + + + - there is a manual lock of proof payment. tags: - 'Proof payments' parameters: @@ -19581,7 +22589,9 @@ paths: errors: - errorCode: proof-payments-closed - message: 'Proof payment with code "P--0000000000-1" is closed. Unlock proof payment first.' + message: |- + Proof payment with code "P--0000000000-1" is closed. Unlock + proof payment first. instance: P--0000000000-1 schema: type: object @@ -19592,7 +22602,15 @@ paths: $ref: '#/components/schemas/Errors' summary: 'Proof payment deletion' operationId: deleteProofPayment - description: "If the proof payment is closed, response code `409` is returned and the document cannot be deleted. Proof payment is closed if:\n\n- proof payment is/was linked to the invoice or\n\n- there is a manual lock of proof payment." + description: |- + If the proof payment is closed, response code `409` is returned and the + document cannot be deleted. Proof payment is closed if: + + + - proof payment is/was linked to the invoice or + + + - there is a manual lock of proof payment. tags: - 'Proof payments' parameters: @@ -19758,7 +22776,9 @@ paths: errors: - errorCode: proof-payments-not-found - message: 'Proof payment with proforma invoice code "2015000170" not found.' + message: |- + Proof payment with proforma invoice code "2015000170" not + found. instance: '2015000170' schema: type: object @@ -19891,23 +22911,33 @@ paths: errors: - errorCode: proof-payments-unable-to-open - message: 'Unable to open proof payment with code "P--0000000000-1". Document is linked to invoice.' + message: |- + Unable to open proof payment with code "P--0000000000-1". + Document is linked to invoice. instance: P--0000000000-1 - errorCode: proof-payments-unable-to-close - message: 'Unable to close proof payment with code "P--0000000000-1". Document is not valid.' + message: |- + Unable to close proof payment with code "P--0000000000-1". + Document is not valid. instance: P--0000000000-1 - errorCode: proof-payments-unable-to-close - message: 'Unable to close proof payment with code "P--0000000000-1". Document is linked to invoice.' + message: |- + Unable to close proof payment with code "P--0000000000-1". + Document is linked to invoice. instance: P--0000000000-1 - errorCode: proof-payments-unable-to-unlink - message: 'Unable to unlink proof payment with code "P--0000000000-1". Document is not linked to invoice.' + message: |- + Unable to unlink proof payment with code "P--0000000000-1". + Document is not linked to invoice. instance: P--0000000000-1 - errorCode: invalid-request-data - message: 'Unable to update proof payment with code "P--0000000000-1". An exception occurred.' + message: |- + Unable to update proof payment with code "P--0000000000-1". + An exception occurred. instance: P--0000000000-1 schema: type: object @@ -19918,7 +22948,26 @@ paths: $ref: '#/components/schemas/Errors' summary: 'Proof payment document settings' operationId: proofPaymentDocumentSettings - description: "Using this endpoint, you can unlink an invoice from a proof of payment. After successfully unlinking the invoice, the price of the linked\ninvoice will be recalculated and increased by the price of the proof of payment.\nLinking of the invoice to the proof of payment is not possible at this endpoint.\n\nYou can also close a proof of payment with this endpoint. You can open a proof of payment if it is not linked to any invoice.\nOtherwise, a response code 409 is returned and the document cannot be closed.\n\nImportant note: If the document is closed, the invoice or proof of payment may have already been sent to the customer!" + description: |- + Using this endpoint, you can unlink an invoice from a proof of payment. + After successfully unlinking the invoice, the price of the linked + + invoice will be recalculated and increased by the price of the proof of + payment. + + Linking of the invoice to the proof of payment is not possible at this + endpoint. + + + You can also close a proof of payment with this endpoint. You can open a + proof of payment if it is not linked to any invoice. + + Otherwise, a response code 409 is returned and the document cannot be + closed. + + + Important note: If the document is closed, the invoice or proof of + payment may have already been sent to the customer! tags: - 'Proof payments' parameters: @@ -19987,7 +23036,12 @@ paths: instance: P-2014000004-01 summary: 'Download proof of payment as PDF' operationId: downloadProofOfPaymentPdf - description: "You can request the proof of payment as PDF file, response will be as application/octet-stream. You can download pdf documents\nonly one-by-one for every e-shop. Parallel requests end with `423 Locked` error." + description: |- + You can request the proof of payment as PDF file, response will be as + application/octet-stream. You can download pdf documents + + only one-by-one for every e-shop. Parallel requests end with `423 + Locked` error. tags: - 'Proof payments' parameters: @@ -20039,13 +23093,20 @@ paths: properties: changeType: type: string - description: 'type of event that happened with the document. Possible values are following: `add`, `edit`, `delete`.' + description: |- + type of event that happened with the document. + Possible values are following: `add`, `edit`, + `delete`. changeTime: type: string - description: 'date and time when the event happened. ISO 8601 format ("2017-12-12T22:08:01+0100").' + description: |- + date and time when the event happened. ISO 8601 + format ("2017-12-12T22:08:01+0100"). code: type: string - description: 'identifier (number) of the document, which can be used to query about the details.' + description: |- + identifier (number) of the document, which can be + used to query about the details. required: - changeType - changeTime @@ -20088,7 +23149,19 @@ paths: additionalProperties: false summary: 'Last proof payments changes' operationId: getLastProofPaymentsChanges - description: "Returns the list of proof payments, which were changed. The Endpoint is intended to determine the changes after you have loaded the list of proof payments and you need to know the changes. The guaranteed history of changes is 30 days.\n\nEach proof payment is only given in the listing with its last change. For example, if the proof payment was modified and then deleted, the listing will only show information about its deletion.\n\nCreation is considered as `edit` action. So, when there is a new item created, it will be displayed like `edit` action.\n\nEndpoint supports [paging](#section/basic-principles-of-working-with-api/Paging)" + description: |- + Returns the list of proof payments, which were changed. The Endpoint is intended to determine + the changes after you have loaded the list of proof payments and you need to know the changes. The guaranteed history of changes is 30 days. + + + Each proof payment is only given in the listing with its last change. For example, if the proof payment was modified and then deleted, + the listing will only show information about its deletion. + + + Creation is considered as `edit` action. So, when there is a new item created, it will be displayed like `edit` action. + + + Endpoint supports [paging](#section/basic-principles-of-working-with-api/Paging) tags: - 'Proof payments' parameters: @@ -20224,14 +23297,18 @@ paths: - name: creationTimeFrom in: query - description: 'date of credit note creation, in ISO 8601 format, lower limit. Optional.' + description: |- + date of credit note creation, in ISO 8601 format, lower limit. + Optional. example: '2017-02-28T17:04:47+0100' schema: type: string - name: creationTimeTo in: query - description: 'date of credit note creation, in ISO 8601 format, upper limit. Optional.' + description: |- + date of credit note creation, in ISO 8601 format, upper limit. + Optional. example: '2028-02-28T17:04:47+0100' schema: type: string @@ -20274,7 +23351,17 @@ paths: $ref: '#/components/schemas/Errors' summary: 'List of all credit notes' operationId: getListOfAllCreditNotes - description: "Additional information about one credit notes.\nThis endpoint has several sections, which are only sent when requested in the `include` parameter (see [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)).\nValue | Section\n--------|------\n`surchargeParameters`| Item surcharge parameters" + description: |- + Additional information about one credit notes. + + This endpoint has several sections, which are only sent when requested in the `include` parameter (see + [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)). + + Value | Section + + --------|------ + + `surchargeParameters`| Item surcharge parameters tags: - 'Credit notes' parameters: @@ -20635,7 +23722,17 @@ paths: instance: '000000000633' summary: 'Credit note detail' operationId: getCreditNoteDetail - description: "Additional information about one credit note.\nThis endpoint has several sections, which are only sent when requested in the `include` parameter (see [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)).\nValue | Section\n--------|------\n`surchargeParameters`| Item surcharge parameters" + description: |- + Additional information about one credit note. + + This endpoint has several sections, which are only sent when requested in the `include` parameter (see + [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)). + + Value | Section + + --------|------ + + `surchargeParameters`| Item surcharge parameters tags: - 'Credit notes' parameters: @@ -21247,7 +24344,15 @@ paths: additionalProperties: false summary: 'Credit note from invoice creation' operationId: createCreditNoteFromInvoice - description: "Creating credit note from existing invoice.\n\nIt will create a credit note from the given invoice. It will automatically take all invoice items and add them to the credit note. If you want to add just some items from the invoice or different amount, use the parameter `items`. This parameter will allow you to generate credit note only with provided items." + description: |- + Creating credit note from existing invoice. + + + It will create a credit note from the given invoice. It will + automatically take all invoice items and add them to the credit note. If + you want to add just some items from the invoice or different amount, + use the parameter `items`. This parameter will allow you to generate + credit note only with provided items. tags: - 'Credit notes' parameters: @@ -21360,6 +24465,7 @@ paths: - isValid - invoiceCode - orderCode + - proofPaymentCode - creationTime - changeTime - dueDate @@ -21393,8 +24499,10 @@ paths: examples: - true invoiceCode: - type: string - description: 'invoice number. Caution! This does not have to be just a number, it can also contain letters, a dash, etc.' + type: + - string + - 'null' + description: 'invoice number (can be `null`). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.' examples: - '2017200011' orderCode: @@ -21404,6 +24512,13 @@ paths: description: 'purchase order number (can be `null`). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.' examples: - '2017000017' + proofPaymentCode: + type: + - string + - 'null' + description: 'proof payment code (can be `null`). Caution! This does not have to be just a number, it can also contain letters, a dash, etc.' + examples: + - P--2017200011-1 creationTime: $ref: '#/components/schemas/typeDateTime' description: 'date of issue, in ISO 8601 format' @@ -21515,8 +24630,6 @@ paths: description: 'VAT mode, can be null, possible values: `Normal`, `One Stop Shop`, `Mini One Stop Shop`, `Reverse charge`, `Outside the EU`' examples: - Normal - amountRefunded: - $ref: '#/components/schemas/typePrice' errors: $ref: '#/components/schemas/Errors' required: @@ -21550,7 +24663,11 @@ paths: instance: P-2014000004-01 summary: 'Credit note from proof of payment' operationId: createCreditNoteFromProofOfPayment - description: "Creating credit note from existing proof of payment.\nIt will create a credit note from the given proof of payment. It will automatically take all proof of payment items and add them to the credit note." + description: |- + Creating credit note from existing proof of payment. + + It will create a credit note from the given proof of payment. It will + automatically take all proof of payment items and add them to the credit note. tags: - 'Credit notes' - 'Proof payments' @@ -21567,7 +24684,7 @@ paths: $ref: '#/components/parameters/DefaultContentType' requestBody: content: - application/vnd.shoptet.v1.0: + application/vnd.shoptet.v1.0+json: schema: type: object required: @@ -21942,7 +25059,10 @@ paths: additionalProperties: false summary: 'Update of credit note item' operationId: updateCreditNoteItem - description: "Updates credit note item. It's not possible to change `productType` property and it's not possible to update credit note item of another type then `product` or `product-set`." + description: |- + Updates credit note item. It's not possible to change `productType` + property and it's not possible to update credit note item of another + type then `product` or `product-set`. tags: - 'Credit notes' parameters: @@ -21957,7 +25077,9 @@ paths: - name: id in: path - description: 'credit note item id. Can be found in field `data.creditNote.items.itemId` in Credit note detail. (number)' + description: |- + credit note item id. Can be found in field + `data.creditNote.items.itemId` in Credit note detail. (number) required: true example: '198' schema: @@ -22084,7 +25206,9 @@ paths: instance: integration-call summary: 'Deletion of credit note item' operationId: deleteCreditNoteItem - description: "Deletes credit note item. It's not possible to delete credit note item of another type then `product` or `product-set`." + description: |- + Deletes credit note item. It's not possible to delete credit note item + of another type then `product` or `product-set`. tags: - 'Credit notes' parameters: @@ -22099,7 +25223,9 @@ paths: - name: id in: path - description: 'credit note item id. Can be found in field `data.creditNote.items.itemId` in Credit note detail. (number)' + description: |- + credit note item id. Can be found in field + `data.creditNote.items.itemId` in Credit note detail. (number) required: true example: '198' schema: @@ -22145,11 +25271,18 @@ paths: errors: - errorCode: document-not-generated - message: 'Error while getting document type "creditNote" with code "0000000002".' + message: |- + Error while getting document type "creditNote" with code + "0000000002". instance: '0000000002' summary: 'Download credit note as PDF' operationId: downloadCreditNotePdf - description: "You can request the credit note as PDF file, response will be as application/octet-stream. You can download pdf documents\nonly one-by-one for every e-shop. Parallel requests end with `423 Locked` error." + description: |- + You can request the credit note as PDF file, response will be as + application/octet-stream. You can download pdf documents + + only one-by-one for every e-shop. Parallel requests end with `423 + Locked` error. tags: - 'Credit notes' parameters: @@ -22213,7 +25346,21 @@ paths: additionalProperties: false summary: 'Last credit note changes' operationId: getLastCreditNoteChanges - description: "Returns the list of credit notes, which were changed. The Endpoint is intended to determine the changes after you have loaded the list of credit notes and you need to know the changes. The guaranteed history of changes is 30 days.\n\nEach credit note is only given in the listing with its last change. For example, if the credit note was modified and then deleted, the listing will only show information about its deletion.\n\nCreation is considered as `edit` action. So, when there is a new item created, it will be displayed like `edit` action.\n\nEndpoint supports [pagination](#section/basic-principles-of-working-with-api/Paging)." + description: |- + Returns the list of credit notes, which were changed. The Endpoint is intended to determine + the changes after you have loaded the list of credit notes and you need to know the changes. + The guaranteed history of changes is 30 days. + + + Each credit note is only given in the listing with its last change. For example, if the credit note was + modified and then deleted, the listing will only show information about its deletion. + + + Creation is considered as `edit` action. So, when there is a new item created, it will be displayed + like `edit` action. + + + Endpoint supports [pagination](#section/basic-principles-of-working-with-api/Paging). tags: - 'Credit notes' parameters: @@ -22352,7 +25499,15 @@ paths: instance: instance summary: 'List of all delivery notes' operationId: getListOfAllDeliveryNotes - description: "Using this endpoint, you can get list of all delivery notes with detailed info of each delivery note (like in delivery Note Detail endpoint) asynchronously. See how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our developer's portal.\n\nResponse will be in [jsonlines](https://jsonlines.org/) format with each product taking one line of output file. One delivery note in response has the same format as delivery note detail response." + description: |- + Using this endpoint, you can get list of all delivery notes with detailed info of each delivery note + (like in delivery Note Detail endpoint) asynchronously. + See how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our + developer's portal. + + + Response will be in [jsonlines](https://jsonlines.org/) format with each product taking one line of output file. + One delivery note in response has the same format as delivery note detail response. tags: - 'Delivery notes' parameters: @@ -22538,7 +25693,17 @@ paths: instance: '000000000633' summary: 'Detail of delivery note' operationId: getDetailOfDeliveryNote - description: "Additional information about one delivery note.\nThis endpoint has several sections, which are only sent when requested in the `include` parameter (see [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)).\nValue | Section\n--------|------\n`surchargeParameters`| Item surcharge parameters" + description: |- + Additional information about one delivery note. + + This endpoint has several sections, which are only sent when requested in the `include` parameter (see + [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)). + + Value | Section + + --------|------ + + `surchargeParameters`| Item surcharge parameters tags: - 'Delivery notes' parameters: @@ -22598,11 +25763,18 @@ paths: errors: - errorCode: document-not-generated - message: 'Error while getting document type "deliveryNote" with code "0000000001".' + message: |- + Error while getting document type "deliveryNote" with code + "0000000001". instance: '0000000001' summary: 'Download delivery note as PDF' operationId: downloadDeliveryNoteAsPdf - description: "You can request the delivery note as PDF file, response will be as application/octet-stream. You can download pdf documents\nonly one-by-one for every e-shop. Parallel requests end with `423 Locked` error." + description: |- + You can request the delivery note as PDF file, response will be as + application/octet-stream. You can download pdf documents + + only one-by-one for every e-shop. Parallel requests end with `423 + Locked` error. tags: - 'Delivery notes' parameters: @@ -22647,7 +25819,9 @@ paths: additionalProperties: false summary: 'List of stocks' operationId: getListOfStocks - description: 'Returns the list of stocks. There are usually not many stocks, therefore the endpoint returns all of them without [paging](#section/basic-principles-of-working-with-api/Paging).' + description: |- + Returns the list of stocks. There are usually not many stocks, therefore the endpoint returns all of + them without [paging](#section/basic-principles-of-working-with-api/Paging). tags: - Stocks parameters: @@ -22747,7 +25921,12 @@ paths: type: - string - 'null' - description: "Can have the following values: \n - `admin` if the change was invoked by the e-shop administrator \n - `customer` if the change was invoked by the e-shop customer \n - e-mail or `null` for all other cases. \n Upon a change invoked by a REST API request, the form of the e-mail is generated as per template `api.service-{service-id}@{e-shop-domain}." + description: |- + Can have the following values: + - `admin` if the change was invoked by the e-shop administrator + - `customer` if the change was invoked by the e-shop customer + - e-mail or `null` for all other cases. + Upon a change invoked by a REST API request, the form of the e-mail is generated as per template `api.service-{service-id}@{e-shop-domain}. examples: - novak@shoptet.cz changeTime: @@ -22786,7 +25965,14 @@ paths: additionalProperties: false summary: 'Stock movements' operationId: getStockMovements - description: "It returns the list of changes in product quantity, which were done within one stock. Supports the [paging](#section/basic-principles-of-working-with-api/Paging) `movements`.\nThis endpoint supports optional parts using the `include` parameter (see [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)). Please note that there is some performance penalty associated with the usage of \"orderCode\" `include` and/or query `parameter`." + description: |- + It returns the list of changes in product quantity, which were done + within one stock. Supports the [paging](#section/basic-principles-of-working-with-api/Paging) `movements`. + + This endpoint supports optional parts using the `include` parameter (see + [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)). Please note that there is some + performance penalty associated with the usage of "orderCode" `include` + and/or query `parameter`. tags: - Stocks parameters: @@ -22801,14 +25987,18 @@ paths: - name: lastId in: query - description: 'ID of last transfered record. If missing, the older records are sent.' + description: |- + ID of last transfered record. If missing, the older records are + sent. example: '45' schema: type: number - name: changeTimeFrom in: query - description: 'Date of move, in ISO 8601 format, lower limit. It is not possible to use it as break poit, it is not unique value. Optional.' + description: |- + Date of move, in ISO 8601 format, lower limit. It is not possible to + use it as break poit, it is not unique value. Optional. example: '2021-03-01T00:00:00+0100' schema: type: string @@ -22885,11 +26075,59 @@ paths: errors: - errorCode: stock-change-not-allowed - message: 'Stock change not allowed for product set "82". Skipped.' + message: |- + Stock change not allowed for product set "82". + Skipped. instance: '82' summary: 'Update quantity in stock' operationId: updateQuantityInStock - description: "Endpoint enables the quantity of product in stock (relative and absolute) to be changed. Within a call, the update\nof multiple products at once can be requested (max. 100 products/variants).\n\nIn case an error occurs for one of the records, the correct records will be updated, the response will be `200 OK`\nand there will be records in the `errors` array for each failed record. If all records are incorrect, the response\ncode will be `400 BAD REQUEST` instead.\n\nItem `productCode` is mandatory. Then one of the three items has to be provided:\n\n- `amountChange` to increase or decrease amount available for ordering/physically on stock (relative change)\n\n- `quantity` to set amount available for ordering (absolute amount)\n\n- `realStock` to set amount physically stored in a warehouse (absolute amount)\n\nThe difference between `quantity` and `realStock` is amount of goods requested by the pending orders (so called \"claim\").\n\n`amount for ordering` = `realStock` - `claim`\n\nThe claim cannot be changed explicitly, it is updated when a new order is submitted or an order is sent out. Please note,\nthat the stock amount cannot be changed for product sets, where the amount is calculated dynamically from the individual\nproducts in the set. Trying to change the amount of product set will result in an error." + description: |- + Endpoint enables the quantity of product in stock (relative and + absolute) to be changed. Within a call, the update + + of multiple products at once can be requested (max. 100 + products/variants). + + + In case an error occurs for one of the records, the correct records will + be updated, the response will be `200 OK` + + and there will be records in the `errors` array for each failed record. + If all records are incorrect, the response + + code will be `400 BAD REQUEST` instead. + + + Item `productCode` is mandatory. Then one of the three items has to be + provided: + + + - `amountChange` to increase or decrease amount available for + ordering/physically on stock (relative change) + + + - `quantity` to set amount available for ordering (absolute amount) + + + - `realStock` to set amount physically stored in a warehouse (absolute + amount) + + + The difference between `quantity` and `realStock` is amount of goods + requested by the pending orders (so called "claim"). + + + `amount for ordering` = `realStock` - `claim` + + + The claim cannot be changed explicitly, it is updated when a new order + is submitted or an order is sent out. Please note, + + that the stock amount cannot be changed for product sets, where the + amount is calculated dynamically from the individual + + products in the set. Trying to change the amount of product set will + result in an error. tags: - Stocks parameters: @@ -23091,7 +26329,20 @@ paths: additionalProperties: false summary: 'Product supplies in stock' operationId: getProductSuppliesInStock - description: "Returns the product supplies in stock for all products in a specific stock, contains GUID, code and quantity in stock for a specific product variant. It is possible to filter the specific GUID of a product, possibly a variant code. The endpoint supports [paging](#section/basic-principles-of-working-with-api/Paging), in case of filtering, the amount of items per page increases.\n\nThis endpoint supports optional parts using the `include` parameter (see [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)). The `changeTime` item is always temporarily returned, however as of 16. 3. 2019 only upon using the `include` parameter.\n\nIf you defined the `include=changeTime` parameter within the URL, the response will also contain the time when the last quantity in stock was changed." + description: |- + Returns the product supplies in stock for all products in a specific stock, contains GUID, code and quantity + in stock for a specific product variant. It is possible to filter the specific GUID of a product, possibly + a variant code. The endpoint supports [paging](#section/basic-principles-of-working-with-api/Paging), + in case of filtering, the amount of items per page increases. + + + This endpoint supports optional parts using the `include` parameter (see + [Requested sections](#section/basic-principles-of-working-with-api/Section-on-demand)). The `changeTime` item + is always temporarily returned, however as of 16. 3. 2019 only upon using the `include` parameter. + + + If you defined the `include=changeTime` parameter within the URL, the response will also contain the time + when the last quantity in stock was changed. tags: - Stocks parameters: @@ -23120,13 +26371,19 @@ paths: - name: onlyWithClaim in: query - description: 'whether only products with claim greater than 0 should be returned. Defaults to `false`' + description: |- + whether only products with claim greater than 0 should be returned. + Defaults to `false` schema: type: boolean - name: changedFrom in: query - description: "return only product supplies, which amount has been changed since date value of this parameter.\n\n \nIt support maximum of 30 days in history. (optional, string). ISO 8601 format (\"2017-12-12T22:08:01+0100\"). Optional.\n" + description: | + return only product supplies, which amount has been changed since date value of this parameter. + + + It support maximum of 30 days in history. (optional, string). ISO 8601 format ("2017-12-12T22:08:01+0100"). Optional. schema: type: string - @@ -23513,7 +26770,9 @@ paths: errors: - errorCode: brand-used-by-products - message: 'Brand "1e3f3f3f-3f3f-63ca-b93f-02423f1f0005" cannot be deleted, because some products are assigned to it.' + message: |- + Brand "1e3f3f3f-3f3f-63ca-b93f-02423f1f0005" cannot be + deleted, because some products are assigned to it. instance: 1e3f3f3f-3f3f-63ca-b93f-02423f1f0005 schema: type: object @@ -23524,7 +26783,12 @@ paths: $ref: '#/components/schemas/Errors' summary: 'Deletion of brand' operationId: deleteBrand - description: "If the brand cannot be deleted, because it is used by some product, a 409 code is returned.\nOptional parameter `deleteUsed` with `true` value allows deletion of brand used by products." + description: |- + If the brand cannot be deleted, because it is used by some product, a + 409 code is returned. + + Optional parameter `deleteUsed` with `true` value allows deletion of + brand used by products. tags: - Brands parameters: @@ -23576,7 +26840,32 @@ paths: additionalProperties: false summary: 'BATCH creation of brands' operationId: createBrandBatch - description: "This endpoint allows you to create multiple brands at once. Batch creation is processed asynchronously in same way as for example products snapshot,\nbut it does not have `resultUrl` in response. Instead, you can check attribute `log` which contains successfully created brands and errors.\n\nSee how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our developer's portal.\n\nFile with data for update must be in JSONL ([jsonlines](https://jsonlines.org/)) format. Each line must contain one brand in JSON format. Maximum size of file is 100MB.\nStructure of JSON row is same as structure of JSON for single brand creation above.\n\nAsynchronous job process jsonl file row by row and try to validate and save data. If there is any error, row is skipped and error is logged, but it does not stop processing of other rows. In Log, every product is identified by its position in file (starting from 1)." + description: |- + This endpoint allows you to create multiple brands at once. Batch + creation is processed asynchronously in same way as for example products + snapshot, + + but it does not have `resultUrl` in response. Instead, you can check + attribute `log` which contains successfully created brands and errors. + + + See how [Asynchronous + requests](https://developers.shoptet.com/asynchronous-requests/) work on + our developer's portal. + + + File with data for update must be in JSONL + ([jsonlines](https://jsonlines.org/)) format. Each line must contain one + brand in JSON format. Maximum size of file is 100MB. + + Structure of JSON row is same as structure of JSON for single brand + creation above. + + + Asynchronous job process jsonl file row by row and try to validate and + save data. If there is any error, row is skipped and error is logged, + but it does not stop processing of other rows. In Log, every product is + identified by its position in file (starting from 1). tags: - Brands requestBody: @@ -23671,7 +26960,9 @@ paths: - name: email in: query - description: 'filtering as per customer’s e-mails. An accurate match is searched for, regardless of capitalization.' + description: |- + filtering as per customer’s e-mails. An accurate match is searched + for, regardless of capitalization. schema: type: string - @@ -23878,7 +27169,13 @@ paths: - name: suppressMandatoryFieldsCheck in: query - description: 'suppress checking if new customer has filled all mandatory fields from eshop settings `Settings -> Customers -> Mandatory fields`. Suppressing this check can cause worse customer experience in order process for customers without all mandatory fields! However this can be useful for migration customers from older system without all necessary fields.' + description: |- + suppress checking if new customer has filled all mandatory fields + from eshop settings `Settings -> Customers -> Mandatory fields`. + Suppressing this check can cause worse customer experience in order + process for customers without all mandatory fields! However this can + be useful for migration customers from older system without all + necessary fields. example: 'false' schema: type: string @@ -24005,7 +27302,17 @@ paths: $ref: '#/components/schemas/Errors' summary: 'List of all customers' operationId: getListOfAllCustomers - description: "Using this endpoint, you can get list of all customers with detailed info of each customer (like in Customer Detail endpoint) asynchronously. See how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our developer's portal.\n\nResponse will be in [jsonlines](https://jsonlines.org/) format with each product taking one line of output file. One product in response has the same format as product detail response (in `data.customer` attribute)\n\nResult file is compressed using GZIP." + description: |- + Using this endpoint, you can get list of all customers with detailed info of each customer (like in Customer Detail endpoint) + asynchronously. See how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our + developer's portal. + + + Response will be in [jsonlines](https://jsonlines.org/) format with each product taking one line of output file. + One product in response has the same format as product detail response (in `data.customer` attribute) + + + Result file is compressed using GZIP. tags: - Customers parameters: @@ -24229,7 +27536,7 @@ paths: 404: description: 'Not Found' content: - application/json: + 'application/vnd.shoptet.v1.0+json; charset=utf-8': schema: type: object properties: @@ -24242,7 +27549,9 @@ paths: errors: - errorCode: customer-not-found - message: 'Customer with guid "157e7215-9035-11e4-a769-ac162d8a2454" not found.' + message: |- + Customer with guid "157e7215-9035-11e4-a769-ac162d8a2454" + not found. instance: 157e7215-9035-11e4-a769-ac162d8a2454 summary: 'Customer detail' operationId: getCustomerDetail @@ -25905,7 +29214,21 @@ paths: additionalProperties: false summary: 'Last customer changes' operationId: getLastCustomerChanges - description: "Returns the list of customers who have been changed (added/changed or deleted). The Endpoint is intended to determine the changes after you have loaded the complete list of customers and you need to know, if any of these has been changed (or added or deleted). Guaranteed history is 30 days, the older data are deleted progressively.\n\nEach customer in the log is only mentioned with their last change. For example, if the customer was modified and then deleted, the log will only show information about the deletion.\nCreation is considered as `edit` action. So, when there is a new item created, it will be displayed like `edit` action.\n\nEndpoint supports [paging](#section/basic-principles-of-working-with-api/Paging)." + description: |- + Returns the list of customers who have been changed (added/changed or deleted). The Endpoint is intended + to determine the changes after you have loaded the complete list of customers and you need to know, if + any of these has been changed (or added or deleted). Guaranteed history is 30 days, the older data are + deleted progressively. + + + Each customer in the log is only mentioned with their last change. For example, if the customer was modified + and then deleted, the log will only show information about the deletion. + + Creation is considered as `edit` action. So, when there is a new item created, it will be displayed like + `edit` action. + + + Endpoint supports [paging](#section/basic-principles-of-working-with-api/Paging). tags: - Customers parameters: @@ -26155,7 +29478,10 @@ paths: additionalProperties: false summary: 'Listing of codes' operationId: getListingOfHtmlCodes - description: "This lists currently defined HTML codes for this addon, in all possible locations. Each addon sees only “its own” codes,\n it cannot see other codes of other addons, not even from the same developer. Also, it does not see the code inserted within the administration." + description: |- + This lists currently defined HTML codes for this addon, in all possible + locations. Each addon sees only “its own” codes, + it cannot see other codes of other addons, not even from the same developer. Also, it does not see the code inserted within the administration. tags: - Templates parameters: @@ -26221,11 +29547,22 @@ paths: errors: - errorCode: template-include-location-invalid - message: 'Invalid location code: does-not-exist. Possible values: common-header, common-footer, order-confirmed' + message: |- + Invalid location code: does-not-exist. Possible values: + common-header, common-footer, order-confirmed instance: location summary: 'Inserting and editing codes' operationId: createAndEditHtmlCodes - description: "This adds new or changes the current (if exists) HTML code. It is possible to enter 1-3 changes at a time (typically\n3 possible locations). If the value already exists, it is simply overwritten. The limit for HTML code is 8192 characters. In case that any\nof the requirements fail, the detailed information is returned in the`errors` field." + description: |- + This adds new or changes the current (if exists) HTML code. It is + possible to enter 1-3 changes at a time (typically + + 3 possible locations). If the value already exists, it is simply + overwritten. The limit for HTML code is 8192 characters. In case that + any + + of the requirements fail, the detailed information is returned in + the`errors` field. tags: - Templates requestBody: @@ -26287,14 +29624,21 @@ paths: additionalProperties: false summary: 'Removal of code' operationId: deleteHtmlCode - description: "This call can be used to delete the existing code from the given location. if the code for the given `location` (position) does not exist, the\nAPI returns `404 NOT FOUND`" + description: |- + This call can be used to delete the existing code from the given + location. if the code for the given `location` (position) does not + exist, the + + API returns `404 NOT FOUND` tags: - Templates parameters: - name: location in: path - description: 'supported values: `common-header`, `common-footer`, `order-confirmed`' + description: |- + supported values: `common-header`, `common-footer`, + `order-confirmed` required: true example: common-header schema: @@ -26336,14 +29680,18 @@ paths: additionalProperties: false summary: 'Gaining the information about payment' operationId: getInformationAboutPayment - description: 'Returns the URL, at which the payment gateway shall redirect the users after completion of operation and order number.' + description: |- + Returns the URL, at which the payment gateway shall redirect the users + after completion of operation and order number. tags: - 'Payment gateways' parameters: - name: paymentCode in: path - description: "the payment code identifies the payment of a single order,\nit is generated when the order is completed and received by the payment gateway upon redirection from the e-shop to the payment gateway.\n" + description: | + the payment code identifies the payment of a single order, + it is generated when the order is completed and received by the payment gateway upon redirection from the e-shop to the payment gateway. required: true example: os8FtURz7PpO46Z87euEAoBAn9RClB2d schema: @@ -26416,18 +29764,27 @@ paths: errors: - errorCode: invalid-request-data - message: 'Does not have a value in the enumeration ["FAILED","OK","PENDING"]' + message: |- + Does not have a value in the enumeration + ["FAILED","OK","PENDING"] instance: data.status summary: 'Payment status update' operationId: updatePaymentStatus - description: "Payment status update via the payment gateway. The `paymentCode` is the identifier. Payment status can be updated when the payment has been successfully recorded.\n**Please note that `message` can not be longer than 255 characters.**" + description: |- + Payment status update via the payment gateway. The `paymentCode` is the + identifier. Payment status can be updated when the payment has been + successfully recorded. + + **Please note that `message` can not be longer than 255 characters.** tags: - 'Payment gateways' parameters: - name: paymentCode in: path - description: "payment code identifies the payment of a single order,\nit is generated when the order is completed and received by the payment gateway upon redirection from e-shop to the payment gateway.\n" + description: | + payment code identifies the payment of a single order, + it is generated when the order is completed and received by the payment gateway upon redirection from e-shop to the payment gateway. required: true example: os8FtURz7PpO46Z87euEAoBAn9RClB2d schema: @@ -26497,7 +29854,12 @@ paths: additionalProperties: false summary: 'Overview of registered webhooks' operationId: getOverviewOfRegisteredWebhooks - description: "Returns the list of webhooks, registered by the specific addon for a single e-shop. It is therefore bound to the specific installation.\nThe addon does not have any access to another addon (not even for the same e-shop, or two addons from the same developer)." + description: |- + Returns the list of webhooks, registered by the specific addon for a + single e-shop. It is therefore bound to the specific installation. + + The addon does not have any access to another addon (not even for the + same e-shop, or two addons from the same developer). tags: - Webhooks parameters: @@ -26530,7 +29892,26 @@ paths: additionalProperties: false summary: 'Registration of new webhook' operationId: registerNewWebhook - description: "Registers the webhook. For a single event (`event`, for example `order:create`) **ONLY ONE** URL can be registered.\nIf you try to enter the webhook for an `event` that already exists, you will\n receive error `422` with message `Webhook already exists for this event`. Successful creation (registration) of webhook is signaled by code `201`. The endpoint returns the info\non the created webhook. One of the items is `id`, which is assigned to the webhook and is used for its identification\nupon change or deletion.\n\nThe supported event can be found in code list Webhook event types.\n\nIt is possible to enter up to 50 webhooks using a single call.\n**Please note that `url` cannot be longer than 2000 characters.**" + description: |- + Registers the webhook. For a single event (`event`, for example + `order:create`) **ONLY ONE** URL can be registered. + + If you try to enter the webhook for an `event` that already exists, you + will + receive error `422` with message `Webhook already exists for this event`. Successful creation (registration) of webhook is signaled by code `201`. The endpoint returns the info + on the created webhook. One of the items is `id`, which is assigned to + the webhook and is used for its identification + + upon change or deletion. + + + The supported event can be found in code list Webhook event types. + + + It is possible to enter up to 50 webhooks using a single call. + + **Please note that `url` cannot be longer than 2000 characters.** tags: - Webhooks requestBody: @@ -26672,7 +30053,12 @@ paths: instance: '999' summary: 'Update of existing webhook' operationId: updateExistingWebhook - description: "Modification of the existing webhook. The `id` of the webhook serves as the identifier. Using just one call, only one webhook can be modified.\n\n**Please note that `url` cannot be longer than 2000 characters.**" + description: |- + Modification of the existing webhook. The `id` of the webhook serves as + the identifier. Using just one call, only one webhook can be modified. + + + **Please note that `url` cannot be longer than 2000 characters.** tags: - Webhooks parameters: @@ -26786,7 +30172,15 @@ paths: additionalProperties: false summary: 'Generating of signature key' operationId: generateWebhookSignatureKey - description: "The endpoint call does not require any body. The endpoint always generates a new signature key\nfor calculating the digest mentioned in the HTTP header of the notification – `Shoptet-Webhook-Signature`. The same key\nis to be used during check after the receipt of notification. For more information see https://developers.shoptet.com/webhooks/#signature" + description: |- + The endpoint call does not require any body. The endpoint always + generates a new signature key + + for calculating the digest mentioned in the HTTP header of the + notification – `Shoptet-Webhook-Signature`. The same key + + is to be used during check after the receipt of notification. For more + information see https://developers.shoptet.com/webhooks/#signature tags: - Webhooks parameters: @@ -26823,7 +30217,14 @@ paths: additionalProperties: false summary: 'Webhook notification' operationId: getWebhookNotification - description: "Returns the notification (invoking) list of webhooks and provides information about these. If you do not have a registered webhook, and the given event happens (for example creation of an order), the registered URLs are called. A notification about a call contains information about the webhook that requested the call, the URL called, the time, delivery status, number of delivery attempts and other information.\n\nIt is possible to request 7 days history of notification." + description: |- + Returns the notification (invoking) list of webhooks and provides information about these. If you do not have + a registered webhook, and the given event happens (for example creation of an order), the registered URLs are + called. A notification about a call contains information about the webhook that requested the call, the URL + called, the time, delivery status, number of delivery attempts and other information. + + + It is possible to request 7 days history of notification. tags: - Webhooks parameters: @@ -26844,14 +30245,19 @@ paths: - name: active in: query - description: 'flag that the notification was not delivered yet, and the number of attempts did not reach the maximum amount. The notification will be resent to the target URL' + description: |- + flag that the notification was not delivered yet, and the number of + attempts did not reach the maximum amount. The notification will be + resent to the target URL example: 'true' schema: type: boolean - name: from in: query - description: 'DateTime for the log, up to the present, which we are interested in. `+` in the time zone designation, html shall be coded as `%2B`.' + description: |- + DateTime for the log, up to the present, which we are interested in. + `+` in the time zone designation, html shall be coded as `%2B`. example: '2018-05-28T14:17:00+02:00' schema: type: string @@ -26989,7 +30395,11 @@ paths: additionalProperties: false summary: 'List of shipping methods' operationId: getListOfShippingMethods - description: "Endpoint returns a list of all available shipping methods and details of their settings. Does not use paging,\nit always returns all methods at once." + description: |- + Endpoint returns a list of all available shipping methods and details of + their settings. Does not use paging, + + it always returns all methods at once. tags: - 'Shipping methods' parameters: @@ -27079,7 +30489,42 @@ paths: additionalProperties: false summary: 'Adding a shipping method' operationId: createShippingMethod - description: "Adds a new shipping method for the specific e-shop.\nShould you wish to implement an addon implementing a shipping method, contact our partner support and request the creation\nof a new \"shipping company code\" identifier.\n\nThe request body includes the mandatory attributes `name` and `shippingMethodCode` (or deprecated `shippingCompanyCode`). The other parameters are not\nmandatory and their default values will be used:\n\n- `description` - `null`\n\n- `visibility` - `false`\n\n- `wholesale` - `false`\n\n- `logo` - `null`\n\n- `minimalShippingPrice` - `0.00`\n\nSend the logo of the shipping method as the file content, encoded with base64, in `data.logo.content` request item.\n\n**Please note that `name` cannot be longer than 255 characters.**" + description: |- + Adds a new shipping method for the specific e-shop. + + Should you wish to implement an addon implementing a shipping method, + contact our partner support and request the creation + + of a new "shipping company code" identifier. + + + The request body includes the mandatory attributes `name` and + `shippingMethodCode` (or deprecated `shippingCompanyCode`). The other + parameters are not + + mandatory and their default values will be used: + + + - `description` - `null` + + + - `visibility` - `false` + + + - `wholesale` - `false` + + + - `logo` - `null` + + + - `minimalShippingPrice` - `0.00` + + + Send the logo of the shipping method as the file content, encoded with + base64, in `data.logo.content` request item. + + + **Please note that `name` cannot be longer than 255 characters.** tags: - 'Shipping methods' requestBody: @@ -27304,7 +30749,10 @@ paths: errors: - errorCode: shipping-request-not-found - message: 'Unknown shippingGuid "97a4b2da-6f2e-11e4-877e-ac162d8a2455" or shippingRequestCode "5ee3b74071f72c460757155cb0ae0aaa".' + message: |- + Unknown shippingGuid + "97a4b2da-6f2e-11e4-877e-ac162d8a2455" or + shippingRequestCode "5ee3b74071f72c460757155cb0ae0aaa". instance: 'shippingGuid, shippingRequestCode' 408: description: 'Request Timeout' @@ -27322,7 +30770,9 @@ paths: errors: - errorCode: cart-data-missing - message: 'Cart data of "10c50b2f9dde1e9b1050623586547d9f" from CMS is missing' + message: |- + Cart data of "10c50b2f9dde1e9b1050623586547d9f" from CMS + is missing instance: shippingRequest summary: 'Shipping request for getting cart details' operationId: getShippingRequestForCartDetails @@ -27390,7 +30840,10 @@ paths: errors: - errorCode: shipping-request-not-found - message: 'Unknown shippingGuid "97a4b2da-6f2e-11e4-877e-ac162d8a2455" or shippingRequestCode "5ee3b74071f72c460757155cb0ae0aaa".' + message: |- + Unknown shippingGuid + "97a4b2da-6f2e-11e4-877e-ac162d8a2455" or + shippingRequestCode "5ee3b74071f72c460757155cb0ae0aaa". instance: 'shippingGuid, shippingRequestCode' 408: description: 'Request Timeout' @@ -27408,7 +30861,9 @@ paths: errors: - errorCode: cart-data-missing - message: 'Cart data of "10c50b2f9dde1e9b1050623586547d9f" from CMS is missing' + message: |- + Cart data of "10c50b2f9dde1e9b1050623586547d9f" from CMS + is missing instance: shippingRequest summary: 'Update shipping price & data' operationId: updateShippingData @@ -27686,11 +31141,16 @@ paths: errors: - errorCode: shipping-request-not-found - message: 'Unknown shippingGuid "97a4b2da-6f2e-11e4-877e-ac162d8a2455" or shippingRequestCode "5ee3b74071f72c460757155cb0ae0aaa".' + message: |- + Unknown shippingGuid + "97a4b2da-6f2e-11e4-877e-ac162d8a2455" or + shippingRequestCode "5ee3b74071f72c460757155cb0ae0aaa". instance: 'shippingGuid, shippingRequestCode' summary: 'Shipping request for getting status of order' operationId: getShippingRequestForGettingOrderStatus - description: 'Endpoint returns status of order related to `shippingRequestCode` & `shippingGuid`' + description: |- + Endpoint returns status of order related to `shippingRequestCode` & + `shippingGuid` tags: - 'Shipping requests' parameters: @@ -27841,7 +31301,10 @@ paths: additionalProperties: false summary: 'Listing of payment methods' operationId: getListingOfPaymentMethods - description: 'The endpoint returns the listing of all available payment methods and details about their settings. Paging is not used, it always returns all methods at once.' + description: |- + The endpoint returns the listing of all available payment methods and + details about their settings. Paging is not used, it always returns all + methods at once. tags: - 'Payment methods' parameters: @@ -27940,7 +31403,38 @@ paths: additionalProperties: false summary: 'Adding the payment methods' operationId: createPaymentMethod - description: "Adds the new payment method for the specific e-shop.\n\n**If you are a Premium client, contact your Account or Onboarding manager and request the creation of a new gateway identifier. New payment gateway has to be approved by Shoptet and client needs to be familiar with the terms of payment in advance.**\n\nThe request body includes the mandatory attributes `name` and `paymentType`. The other parameters are not mandatory and their default values will be used:\n\n- `description` - `null`\n\n- `visibility` - `false`\n\n- `wholesale` - `false`\n\n- `logo` - `null`\n\nSend the logo of the payment gateway as the file content, encoded with base64, in `data.logo.content` request item.\n\n**Please note that `name` cannot be longer than 255 characters.**" + description: |- + Adds the new payment method for the specific e-shop. + + + **If you are a Premium client, contact your Account or Onboarding + manager and request the creation of a new gateway identifier. New + payment gateway has to be approved by Shoptet and client needs to be + familiar with the terms of payment in advance.** + + + The request body includes the mandatory attributes `name` and + `paymentType`. The other parameters are not mandatory and their default + values will be used: + + + - `description` - `null` + + + - `visibility` - `false` + + + - `wholesale` - `false` + + + - `logo` - `null` + + + Send the logo of the payment gateway as the file content, encoded with + base64, in `data.logo.content` request item. + + + **Please note that `name` cannot be longer than 255 characters.** tags: - 'Payment methods' requestBody: @@ -28035,7 +31529,9 @@ paths: additionalProperties: false summary: 'Payment method deletion' operationId: deletePaymentMethod - description: "Deletes payment method by guid. Only payment methods related to your addon may be deleted. Private API tokens aren't currently supported." + description: |- + Deletes payment method by guid. Only payment methods related to your + addon may be deleted. Private API tokens aren't currently supported. tags: - 'Payment methods' parameters: @@ -28219,7 +31715,10 @@ paths: additionalProperties: false summary: 'Listing of e-mail distribution lists' operationId: getListingOfEmailDistributionLists - description: 'The e-mail distribution list named "newsletters" is the system one and is always available (if the e-shop has the module installed). This e-mail distribution list includes the e-mails of all customers who agreed to receiving e-mails.' + description: |- + The e-mail distribution list named "newsletters" is the system one and is always available + (if the e-shop has the module installed). This e-mail distribution list includes the e-mails + of all customers who agreed to receiving e-mails. tags: - 'E-mail distribution lists' parameters: @@ -28343,7 +31842,15 @@ paths: additionalProperties: false summary: 'Detail of e-mail distribution list' operationId: getDetailOfEmailDistributionList - description: "This endpoint returns a list of e-mail addresses of the distribution list.\n\nUpon initial call, it returns up to 500 e-mail addresses; using the `?itemsPerPage=20` parameter, you can requests any number of records per page, up to 500 items limit.\n\nEndpoint supports [paging](#section/basic-principles-of-working-with-api/Paging)." + description: |- + This endpoint returns a list of e-mail addresses of the distribution list. + + + Upon initial call, it returns up to 500 e-mail addresses; using the `?itemsPerPage=20` parameter, you can + requests any number of records per page, up to 500 items limit. + + + Endpoint supports [paging](#section/basic-principles-of-working-with-api/Paging). tags: - 'E-mail distribution lists' parameters: @@ -28403,7 +31910,21 @@ paths: additionalProperties: false summary: 'Distribution list e-mails insertion' operationId: createEmailsDistributionList - description: "This endpoint allows you to add new e-mail addresses to the distribution list identified by its `code`. In the response you will receive structured info about the result of the insertion. In the `emailsInserted`\nkey there will be a list of e-mails successfully inserted, in the `emailsExisting` key, there will be a list of skipped e-mails, because there were already in the list. In the\n`emailsInvalid` key, there will be a list of invalid e-mails (wrong format or non-existing MX domain record) and finally in the `errorMessages` key, there will be a list of error messages\ngenerated for invalid e-mails." + description: |- + This endpoint allows you to add new e-mail addresses to the distribution + list identified by its `code`. In the response you will receive + structured info about the result of the insertion. In the + `emailsInserted` + + key there will be a list of e-mails successfully inserted, in the + `emailsExisting` key, there will be a list of skipped e-mails, because + there were already in the list. In the + + `emailsInvalid` key, there will be a list of invalid e-mails (wrong + format or non-existing MX domain record) and finally in the + `errorMessages` key, there will be a list of error messages + + generated for invalid e-mails. tags: - 'E-mail distribution lists' parameters: @@ -28486,7 +32007,22 @@ paths: additionalProperties: false summary: 'Last changes in distribution list' operationId: getLastChangesInDistributionList - description: "Endpoint is intended to determine the changes after you load the complete e-mail list and you need to know if any of these e-mails were added or removed. Guaranteed history is 30 days, the older data are deleted progressively.\n\nEach e-mail on single e-mail list is only mentioned with its last change, within the log. For example, if the e-mail is deleted and then added again, the log will only show information about its addition. The e-mail lists are not dependant on each other (removing an e-mail from one list does not cause any change in another list, unless the e-mail was originally included in both).\n\n**For \"created\" action, we use `edit` change type.**\n\nEndpoint supports [paging](#section/basic-principles-of-working-with-api/Paging)." + description: |- + Endpoint is intended to determine the changes after you load the complete e-mail list and you need to know + if any of these e-mails were added or removed. Guaranteed history is 30 days, the older data are deleted + progressively. + + + Each e-mail on single e-mail list is only mentioned with its last change, within the log. For example, + if the e-mail is deleted and then added again, the log will only show information about its addition. + The e-mail lists are not dependant on each other (removing an e-mail from one list does not cause any + change in another list, unless the e-mail was originally included in both). + + + **For "created" action, we use `edit` change type.** + + + Endpoint supports [paging](#section/basic-principles-of-working-with-api/Paging). tags: - 'E-mail distribution lists' parameters: @@ -28539,7 +32075,21 @@ paths: additionalProperties: false summary: 'List of discount coupons' operationId: getListOfDiscountCoupons - description: "List of discount coupons within the e-shop. The list is paged at 1000 coupons. The discount coupons can be filtered according to the date of creation, validity, repeatability of usage or their template.\n\nIf absolute price is used, the amount is interpreted with the default VAT rate of the eshop (in administration:\n\nSettings » Basic Settings » Tax Classes). It can be retrieved using endpoint Eshop Info, array `taxClasses`.\n\nThe same is valid for minimum price." + description: |- + List of discount coupons within the e-shop. The list is paged at 1000 coupons. + The discount coupons can be filtered according to the date of creation, validity, + repeatability of usage or their template. + + + If absolute price is used, the amount is interpreted with the default + VAT rate of the eshop (in administration: + + + Settings » Basic Settings » Tax Classes). It can be retrieved using + endpoint Eshop Info, array `taxClasses`. + + + The same is valid for minimum price. tags: - 'Discount coupons' parameters: @@ -28709,7 +32259,14 @@ paths: additionalProperties: false summary: 'Discount coupons insertion' operationId: createDiscountCoupons - description: "This endpoint allows you to insert specific discount coupons into Shoptet. Request is sent in JSON format in its body.\n\nIt is good to compare count of requested coupons with count of cooupons in response as it can be different. It is because of request validation, where it ignores invalid coupons." + description: |- + This endpoint allows you to insert specific discount coupons into + Shoptet. Request is sent in JSON format in its body. + + + It is good to compare count of requested coupons with count of cooupons + in response as it can be different. It is because of request validation, + where it ignores invalid coupons. tags: - 'Discount coupons' requestBody: @@ -28854,7 +32411,17 @@ paths: $ref: '#/components/schemas/Errors' summary: 'List of all discount coupons' operationId: getListOfAllDiscountCoupons - description: "Using this endpoint, you can get list of all discount coupons with detailed info of each discount coupon asynchronously. See how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our developer's portal.\n\nResponse will be in [jsonlines](https://jsonlines.org/) format with each product taking one line of output file. One discount coupon in response has the same format as one discount coupon item form list response.\n\nResult file is compressed using GZIP." + description: |- + Using this endpoint, you can get list of all discount coupons with detailed info of each discount coupon + asynchronously. See how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) + work on our developer's portal. + + + Response will be in [jsonlines](https://jsonlines.org/) format with each product taking one line of output file. + One discount coupon in response has the same format as one discount coupon item form list response. + + + Result file is compressed using GZIP. tags: - 'Discount coupons' parameters: @@ -28932,7 +32499,10 @@ paths: - name: shippingPrice in: query - description: 'How the transport prices are calculated: according to the cart before discounts (beforeDiscount), according to the displayed value of the cart (cart), or free (free)' + description: |- + How the transport prices are calculated: according to the cart + before discounts (beforeDiscount), according to the displayed value + of the cart (cart), or free (free) required: true example: cart schema: @@ -29034,7 +32604,12 @@ paths: instance: AB12345 summary: 'Discount coupon deletion' operationId: deleteDiscountCoupon - description: "Deletes discount coupon as per entered `code`. If successful, returns the code 200.\nIf the discount coupon does not exist within the e-shop, a 404 code is returned." + description: |- + Deletes discount coupon as per entered `code`. If successful, returns + the code 200. + + If the discount coupon does not exist within the e-shop, a 404 code is + returned. tags: - 'Discount coupons' parameters: @@ -29171,7 +32746,10 @@ paths: additionalProperties: false summary: 'Discount coupons set creation' operationId: createDiscountCouponsSet - description: 'This endpoint allows you to create set of discount coupons for Shoptet.It is good to compare count of requested coupons with count of cooupons in response as it can be different. It is because of request validation, where it ignores invalid coupons.' + description: |- + This endpoint allows you to create set of discount coupons for Shoptet.It is good to compare count of requested + coupons with count of cooupons in response as it can be different. It is because of request validation, + where it ignores invalid coupons. tags: - 'Discount coupons' requestBody: @@ -29506,7 +33084,9 @@ paths: additionalProperties: false summary: 'Templates of discount coupons' operationId: getTemplatesOfDiscountCoupons - description: 'Templates of discount coupons within the e-shop. All templates are listed at a time. Without possibility of paging or filtering.' + description: |- + Templates of discount coupons within the e-shop. All templates are listed at a time. Without possibility of + paging or filtering. tags: - 'Discount coupons' parameters: @@ -29730,7 +33310,9 @@ paths: errors: - errorCode: discount-coupon-template-not-found - message: 'Discount coupon template "bffa3b98-d968-11e0-b04f-57a43310b768" was not found.' + message: |- + Discount coupon template + "bffa3b98-d968-11e0-b04f-57a43310b768" was not found. instance: bffa3b98-d968-11e0-b04f-57a43310b768 409: description: Conflict @@ -29748,11 +33330,22 @@ paths: errors: - errorCode: discount-coupon-template-used - message: 'Discount coupon template "bffa3b98-d968-11e0-b04f-57a43310b768" cannot be deleted because it is used.' + message: |- + Discount coupon template + "bffa3b98-d968-11e0-b04f-57a43310b768" cannot be deleted + because it is used. instance: bffa3b98-d968-11e0-b04f-57a43310b768 summary: 'Discount coupons template deletion' operationId: deleteDiscountCouponsTemplate - description: "Deletes discount coupon template as per entered `guid`. If successful, returns the code 200.\nIf the discount coupon template does not exist within the e-shop, a 404 code is returned.\nIf the discount coupon template cannot be deleted, because it is used as template of discount coupon, a 409 code is returned." + description: |- + Deletes discount coupon template as per entered `guid`. If successful, + returns the code 200. + + If the discount coupon template does not exist within the e-shop, a 404 + code is returned. + + If the discount coupon template cannot be deleted, because it is used as + template of discount coupon, a 409 code is returned. tags: - 'Discount coupons' parameters: @@ -29875,7 +33468,9 @@ paths: - name: customerGroupCode in: query - description: 'customer group code, possible values can be get by customer group list endpoint' + description: |- + customer group code, possible values can be get by customer group + list endpoint example: retail schema: type: string @@ -30371,7 +33966,9 @@ paths: additionalProperties: false summary: 'X + Y discounts settings' operationId: getXYDiscountsSettings - description: 'Lists & updates settings of X + Y discounts. Please note, that `enableInCashdesk` setting is not supported on HU projects.' + description: |- + Lists & updates settings of X + Y discounts. + Please note, that `enableInCashdesk` setting is not supported on HU projects. tags: - 'X + Y discounts' parameters: @@ -30439,7 +34036,9 @@ paths: errors: - errorCode: invalid-request-data - message: 'Does not have a value in the enumeration ["all-categories","primary-category",null]' + message: |- + Does not have a value in the enumeration + ["all-categories","primary-category",null] instance: data.categoryTargeting schema: type: object @@ -30453,11 +34052,28 @@ paths: errors: - errorCode: invalid-request-data - message: 'Does not have a value in the enumeration ["all-categories","primary-category",null]' + message: |- + Does not have a value in the enumeration + ["all-categories","primary-category",null] instance: data.categoryTargeting summary: 'X + Y discount settings update' operationId: updateXYDiscountSettings - description: "Updates settings for X + Y discounts. All settings are optional, but at least one should be present.\nPlease note, that updating \"enableInCashdesk\" setting on HU projects will throw an exception.\n\nIf you're targeting a discount to a specific category, right now, we only include products that have\nthat category as their primary one. If you want to include all products in that category in the discount,\nnot just the ones in the primary category, please use `categoryTargeting` attribute with `all-categories` value." + description: |- + Updates settings for X + Y discounts. All settings are optional, but at + least one should be present. + + Please note, that updating "enableInCashdesk" setting on HU projects + will throw an exception. + + + If you're targeting a discount to a specific category, right now, we + only include products that have + + that category as their primary one. If you want to include all products + in that category in the discount, + + not just the ones in the primary category, please use + `categoryTargeting` attribute with `all-categories` value. tags: - 'X + Y discounts' requestBody: @@ -30539,7 +34155,9 @@ paths: additionalProperties: false summary: 'List of articles' operationId: getListOfArticles - description: 'Returns a list of articles with basic info. Supports [paging](#section/basic-principles-of-working-with-api/Paging)' + description: |- + Returns a list of articles with basic info. + Supports [paging](#section/basic-principles-of-working-with-api/Paging) tags: - Articles parameters: @@ -30591,7 +34209,7 @@ paths: instance: type: string example: - data: 'null' + data: null errors: - errorCode: invalid-request-data @@ -30748,7 +34366,18 @@ paths: $ref: '#/components/schemas/Errors' summary: 'List of all articles' operationId: getListAllArticles - description: "Using this endpoint, you can get list of all articles with detailed info of each article (like in Detail of article endpoint) asynchronously. See how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our developer's portal.\n\nResponse will be in [jsonlines](https://jsonlines.org/) format with each product taking one line of output file. One article in response has the same format as article detail response.\n\nResult file is compressed using GZIP." + description: |- + Using this endpoint, you can get list of all articles with detailed info of each article + (like in Detail of article endpoint) asynchronously. + See how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our + developer's portal. + + + Response will be in [jsonlines](https://jsonlines.org/) format with each product taking one line of output file. + One article in response has the same format as article detail response. + + + Result file is compressed using GZIP. tags: - Articles parameters: @@ -30896,7 +34525,7 @@ paths: instance: type: string example: - data: 'null' + data: null errors: - errorCode: invalid-request-data @@ -31137,7 +34766,7 @@ paths: instance: type: string example: - data: 'null' + data: null errors: - errorCode: invalid-request-data @@ -31154,7 +34783,7 @@ paths: - Articles requestBody: content: - application/vnd.shoptet.v1.0: + application/vnd.shoptet.v1.0+json: schema: type: object required: @@ -31324,9 +34953,10 @@ paths: example: data: null errors: - errorCode: article-section-not-found - message: 'Article section with ID "123" not found.' - instance: 123 + - + errorCode: article-section-not-found + message: 'Article section with ID "123" not found.' + instance: '123' summary: 'Detail of article section' operationId: getDetailOfArticleSection description: 'Returns a detail of the article section.' @@ -31380,9 +35010,10 @@ paths: example: data: null errors: - errorCode: article-section-not-found - message: 'Article section with ID "123" not found.' - instance: 123 + - + errorCode: article-section-not-found + message: 'Article section with ID "123" not found.' + instance: '123' summary: 'Update of article section' operationId: updateArticleSection description: 'Updates the article section.' @@ -31401,7 +35032,7 @@ paths: - Articles requestBody: content: - application/vnd.shoptet.v1.0: + application/vnd.shoptet.v1.0+json: schema: type: object required: @@ -31521,6 +35152,90 @@ paths: description: "flag indicating, whether the article section can be viewed by everyone (value of the flag is: `all`), by logged in users only ('logged-in'), or by logged out users only ('logged-out')" examples: - logged-in + delete: + responses: + 200: + description: OK + content: + 'application/vnd.shoptet.v1.0+json; charset=utf-8': + schema: + type: object + properties: + data: + type: 'null' + additionalProperties: false + errors: + $ref: '#/components/schemas/Errors' + required: + - data + - errors + additionalProperties: false + 404: + description: 'Not Found' + content: + 'application/vnd.shoptet.v1.0+json; charset=utf-8': + example: + data: null + errors: + - + errorCode: article-section-not-found + message: 'Article section with ID "123" not found.' + instance: '123' + schema: + type: object + properties: + data: + type: 'null' + errors: + $ref: '#/components/schemas/Errors' + 409: + description: Conflict + content: + 'application/vnd.shoptet.v1.0+json; charset=utf-8': + example: + data: null + errors: + - + errorCode: article-section-contains-articles + message: 'Article section "683" cannot be deleted, because it contains 4 article(s) that would be deleted.' + instance: '683' + schema: + type: object + properties: + data: + type: 'null' + errors: + $ref: '#/components/schemas/Errors' + summary: 'Deletion of article section' + operationId: deleteArticleSection + description: |- + If the article section cannot be deleted, because it contains article(s), a + 409 code is returned. + + Optional parameter `force` with `true` value allows deletion of article section including permanent deletion of + article(s) having this section set as default. + tags: + - Articles + parameters: + - + name: articleSectionId + in: path + description: 'article section ID' + required: true + example: '1' + schema: + type: number + - + name: force + in: query + description: 'allows deletion of article section that contains article(s) if set to `true`' + required: false + example: 'true' + schema: + type: boolean + default: 'false' + - + $ref: '#/components/parameters/DefaultContentType' /api/pages: get: responses: @@ -31740,14 +35455,18 @@ paths: additionalProperties: false summary: 'List of jobs' operationId: getListOfJobs - description: 'List of jobs in queue. Using the "status" parameter to filter by completed|pending|running|failed|expired|killed. Without this filter it will show all statuses. Also you can filter results depends on time of creation and completion.' + description: |- + List of jobs in queue. Using the "status" parameter to filter by completed|pending|running|failed|expired|killed. + Without this filter it will show all statuses. Also you can filter results depends on time of creation and completion. tags: - 'Job endpoints' parameters: - name: status in: query - description: 'supported values: `completed`, `pending`, `running`, `failed`, `expired`, `killed`' + description: |- + supported values: `completed`, `pending`, `running`, `failed`, + `expired`, `killed` example: completed schema: type: string @@ -31877,7 +35596,10 @@ paths: errors: - errorCode: job-detail-try-counter-exceeded-limit - message: 'You have exceeded the limit of job detail request for unprocessed job "1xv8s4c". Please wait for job:finished event after job is completed!' + message: |- + You have exceeded the limit of job detail request for + unprocessed job "1xv8s4c". Please wait for job:finished + event after job is completed! instance: 1xv8s4c 404: description: 'Not Found' @@ -31899,7 +35621,15 @@ paths: instance: 1xv8s4c summary: 'Job detail' operationId: getJobDetail - description: "Returns information about job. If job is completed, it will contain additional information about job result.\n\nReturns 404 if job does not exist.\nReturns 403 response if job detail of unprocessed job is requested more than 10 times." + description: |- + Returns information about job. If job is completed, it will contain + additional information about job result. + + + Returns 404 if job does not exist. + + Returns 403 response if job detail of unprocessed job is requested more + than 10 times. tags: - 'Job endpoints' parameters: @@ -31951,7 +35681,9 @@ paths: additionalProperties: false summary: 'List of uploaded files' operationId: getListOfUploadedFiles - description: 'Retrieves your uploaded files that can be copied in supported endpoints to entities within e-shop.' + description: |- + Retrieves your uploaded files that can be copied in supported endpoints + to entities within e-shop. tags: - Files parameters: @@ -31985,7 +35717,69 @@ paths: additionalProperties: false summary: 'File upload' operationId: uploadFile - description: "Performes file upload asynchronously.\nPlease note that order of files matter (result of job respects the order of images in request).\n\nIn case of specifying filename, keep in mind that extension is checked whether it respects file type.\n\nThe result can be found in job detail in `resultUrl`. The result is formed as normal API response:\n\n```\n{\n \"data\": {\n \"images\":[\n {\n \"index\": 0,\n \"md5\": \"072c1a2005e17dcd3a3cca3d2c769264\",\n \"name\": \"kocka.png\",\n \"created\": \"2023-01-16T13:19:32+0100\",\n \"sourceUrl\": \"https://example.com/image.png\"\n }\n ]\n },\n \"errors\": [\n {\n \"errorCode\": \"file-upload-extension-mismatch\",\n \"message\": \"File extension png mismatch mime type image\\/jpeg of uploaded file (correct should be jpg).\",\n \"instance\": \"data[1]\"\n }\n ]\n}\n```\n\nIn the result's `images` section, there are successfully uploaded images with their info and with `index` field which is order of the image in the request (0-based indexing).\n\nIn the result's `errors` section, there are errors which occured during some images upload and with number in brackets in `data[0]` in `instance`, which is order of the image in the request (0-based indexing).\n\nSee more about file upload in the [files section of documentation](#section/Basic-principles-of-working-with-API/Files)\n\nSee how [Asynchronous requests](https://developers.shoptet.com/asynchronous-requests/) work on our developer's portal.\n\nCurrently maximum of 50 files can be uploaded in one request. Current filesize limit per file is 2MB." + description: |- + Performes file upload asynchronously. + + Please note that order of files matter (result of job respects the order + of images in request). + + + In case of specifying filename, keep in mind that extension is checked + whether it respects file type. + + + The result can be found in job detail in `resultUrl`. The result is + formed as normal API response: + + + ``` + + { + "data": { + "images":[ + { + "index": 0, + "md5": "072c1a2005e17dcd3a3cca3d2c769264", + "name": "kocka.png", + "created": "2023-01-16T13:19:32+0100", + "sourceUrl": "https://example.com/image.png" + } + ] + }, + "errors": [ + { + "errorCode": "file-upload-extension-mismatch", + "message": "File extension png mismatch mime type image\/jpeg of uploaded file (correct should be jpg).", + "instance": "data[1]" + } + ] + } + + ``` + + + In the result's `images` section, there are successfully uploaded images + with their info and with `index` field which is order of the image in + the request (0-based indexing). + + + In the result's `errors` section, there are errors which occured during + some images upload and with number in brackets in `data[0]` in + `instance`, which is order of the image in the request (0-based + indexing). + + + See more about file upload in the [files section of + documentation](#section/Basic-principles-of-working-with-API/Files) + + + See how [Asynchronous + requests](https://developers.shoptet.com/asynchronous-requests/) work on + our developer's portal. + + + Currently maximum of 50 files can be uploaded in one request. Current + filesize limit per file is 2MB. tags: - Files requestBody: @@ -32104,7 +35898,10 @@ paths: additionalProperties: false summary: 'List of available endpoints' operationId: getListOfAvailableEndpoints - description: 'List of endpoints available within the systems. Using the "status" parameter, you can list the approved endpoints, or endpoints pending approval. In default state, without the parameter, the endpoint returns the approved endpoints.' + description: |- + List of endpoints available within the systems. Using the "status" parameter, you can list the approved + endpoints, or endpoints pending approval. In default state, without the parameter, the endpoint returns + the approved endpoints. tags: - 'System endpoints' parameters: @@ -34387,7 +38184,13 @@ components: - 'null' description: 'product description. May contain html.' examples: - - "

As it is often the case with jackets for kids, the emphasis is primarily on durability and quality workmanship. It is clear that it will be put through its paces, which the manufacturer has borne in mind. As previously stated, the manufacturer could also afford a less conservative design for a kids product, combining bold colors with a company logo on the front and back.

\n\n
    \n\t
  • Body - 60% Nylon, 40% wool
    • \n
  • Inside - 100% Polyester
    • \n
" + - |- +

As it is often the case with jackets for kids, the emphasis is primarily on durability and quality workmanship. It is clear that it will be put through its paces, which the manufacturer has borne in mind. As previously stated, the manufacturer could also afford a less conservative design for a kids product, combining bold colors with a company logo on the front and back.

+ +
    +
  • Body - 60% Nylon, 40% wool
    • +
  • Inside - 100% Polyester
    • +
metaDescription: type: - string @@ -37615,96 +41418,3 @@ components: description: 'remark for the discount coupon.' examples: - 'Note: This is a test discount coupon' -security: - - - shoptetAccessToken: [] - - - shoptetPrivateApiToken: [] -tags: - - - name: Eshop - description: 'This endpoint is used for general information about the e-shop settings.' - - - name: Products - description: 'Product endpoints are used for managing products in the e-shop and also for its related modules.' - - - name: 'Price lists' - description: 'Price lists are used for setting up different prices for products for different customer groups.' - - - name: Orders - description: 'Order endpoints are used for managing orders in the e-shop.' - - - name: Invoices - description: 'Invoice endpoints are used for managing invoices in the e-shop.' - - - name: 'Proforma invoices' - description: "Proforma invoice endpoints are used for managing proforma invoices in the e-shop.\n\nThe code (`code`) is the proforma invoice identifier. Although this is usually a number, it is necessary to take into account that this might also include\nletters, a dash, etc." - - - name: 'Credit notes' - description: "Credit note endpoints are used for managing credit notes in the e-shop.\nThe code (`code`) is the credit note identifier. Although this is usually a number, it is necessary to take into account that this might also include\nletters, a dash, etc." - - - name: 'Delivery notes' - description: "Delivery note endpoints are used for managing delivery notes in the e-shop.\n\nThe code (`code`) is the credit notes identifier. Although this is usually a number, it is necessary to take into account that this might also include\nletters, a dash, etc." - - - name: 'Proof payments' - description: 'The code (`code`) is the proof payments identifier. Although this is usually a number, it is necessary to take into account that this might also include letters, a dash, etc.' - - - name: Stocks - description: 'Stock endpoints are used for managing stocks in the e-shop.' - - - name: Suppliers - description: 'Supplier endpoints are used for managing suppliers in the e-shop.' - - - name: Brands - description: "Brand endpoints are used for managing brands in the e-shop.\n\n**Please note**, the **field `code` is deprecated** - use `indexName` instead. Parameter `code` accepts both: guid string style, e.g. `d467bfbe-4334-11ef-ad70-0242ac1f0005`, and index name string style, e.g. `willy-wonka`. **The index name string style is deprecated** - use guid style." - - - name: Customers - description: 'Customer endpoints are used for managing customers in the e-shop.' - - - name: Templates - description: "In the last Shoptet version, it is not possible to change the e-shop design via API. However, it is possible to include HTML codes\ninto previously defined places. This enables the code or link to a file containing additional CSS styles or JavaScript codes to be entered.\nThe same functionality is now included within the e-shop administration (`/admin/html-kody/`, `HTML code` tab).\n\nThere are 3 possible locations, where HTML codes can be inserted:\n\n* `common-header` - the code will be inserted into each e-shop page header (``)\n\n* `common-footer` - the code will be inserted into each e-shop page foot (before end ``)\n\n* `order-confirmed` - the code will be inserted in the page confirming the order (the \"thank you page\")\n\nThe inserted codes may come from 3 sources, and they are included in the following order:\n1. Codes from addons (the addon defines HTML codes to be inserted for anybody, who installs the addon). If there are more of these, they are inserted progressively, the order cannot be relied upon.\n2. Codes entered via API. Each addon can insert only one code into each location. If there are more of these addons, the codes will be inserted progressively, one after another, the order cannot be relied upon.\n3. The code entered in the administration GUI (`/admin/html-kody/`, `HTML code` tab)." - - - name: 'Payment gateways' - description: "API endpoints for integration of payment gateways.\n\n**If you are a Premium client, contact your Account or Onboarding manager. New payment gateway has to be approved by Shoptet and client needs to be familiar with the terms of payment in advance**." - - - name: Webhooks - description: "API endpoints for webhook servicing. It offers the possibility to read, add, change and delete the registered webhooks. Furthermore, it offers\na list of notifications about invoked webhooks and their status.\n\nThe webhooks are HTTP calls, which send HTTPs calls to registered subscribers if a specific event happens,\nfor example creating an order. Then the information, in JSON format, is delivered to the defined URL.\n\n```javascript\n{\n \"eshopId\": 222651,\n \"event\": \"order:create\",\n \"eventCreated\": \"2019-01-08T15:13:39+0100\",\n \"eventInstance\": \"2018000057\"\n}\n```\n\nThe meaning of individual items:\n\n* `eshopId` - number of the e-shop, where the event happened\n\n* `event` - event which invoked the call (see code list Webhook event types)\n\n* `eventCreated` - accurate time, when the event happened\n\n* `eventInstance` - reference to a specified entity - according to the context, order number, invoice number, product GUID, etc.\n\nFor more information about the function of webhooks, see https://developers.shoptet.com/webhooks/." - - - name: 'Shipping methods' - description: 'Shipping methods endpoints are used for managing shipping methods in the e-shop.' - - - name: 'Shipping requests' - description: 'Shipping requests endpoints are used for managing shipping requests in the e-shop.' - - - name: 'Payment methods' - description: 'Payment methods endpoints are used for managing payment methods in the e-shop.' - - - name: 'Unsubscribed emails' - description: 'This functionality allows you to manage a list of email addresses that opted out of receiving marketing communications in compliance with legal requirements, including the possibility of comparing any further mailings with this list to exclude opt-out contacts.' - - - name: 'E-mail distribution lists' - description: 'The functionality is subject to module activation [Mass e-mailing](https://doplnky.shoptet.cz/hromadne-rozesilani-emailu) within the e-shop. The addon using this endpoint must therefore have this module defined as dependency.' - - - name: 'Discount coupons' - description: 'Discount coupons endpoints are used for managing discount coupons in the e-shop.' - - - name: 'X + Y discounts' - description: 'X + Y discounts endpoints are used for managing X + Y discounts in the e-shop.' - - - name: Articles - description: 'Article endpoints are used for managing articles in the e-shop.' - - - name: Pages - description: 'Page endpoints are used for managing pages in the e-shop.' - - - name: Discussions - description: 'Discussion endpoints are used for managing discussions in the e-shop.' - - - name: 'Job endpoints' - description: 'Job endpoints are used for managing asynchronous jobs in the e-shop.' - - - name: Files - description: 'File endpoints are used for managing files in the e-shop.' - - - name: 'System endpoints' - description: 'This endpoints are used for obtaining information for endpoints in API.' diff --git a/openapi/redocly.yaml b/openapi/redocly.yaml index 9e1a3fd..882fe70 100644 --- a/openapi/redocly.yaml +++ b/openapi/redocly.yaml @@ -7,6 +7,7 @@ extends: rules: no-ambiguous-paths: off # Disable this rule because it needs rework our full API routing operation-4xx-response: off # Disable this rule we have a lot of missing 4xx responses + info-license: off rule/tag-description: subject: type: Tag @@ -15,6 +16,17 @@ rules: defined: true pattern: /^[A-Z0-9*].*\.$/s message: Tag description is missing or not start with a capital letter and end with a full stop. + request-mime-type: + severity: error + allowedValues: + - application/vnd.shoptet.v1.0+json + response-mime-type: + severity: error + allowedValues: + - application/vnd.shoptet.v1.0+json; charset=utf-8 + - application/vnd.shoptet.v1.0+json + no-invalid-media-type-examples: + severity: error mockServer: - off: true + off: true # Disable the mock server - currently not working with our vendor content-types