Shoptet API (1.0.0)

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. 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://<eshop-address.tld>/action/ApiOAuthServer/getAccessToken address with HTTP header Authorization: Bearer <OAuth access token>.

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 headerShoptet-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. Your request will be queued and you

receive only job identification in the response. You will be notified using a

webhook 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 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 and 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 aSunset 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. 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.

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 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)

    "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 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

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

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 - openapi.yaml ) into your postman client

Fork Shoptet API Collection from Shoptet Public API Workspace (recommended)

See Shoptet Public API Workspace.

Also check postman documentation for more details: Fork a collection.

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 file from our developers repository.
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

Click the Shoptet API collection name.
Go to Authorization tab.
Set your access token into the value of Shoptet-Access-Token key.
Go to Variables tab.
You can set baseUrl variable here.

Last changes

Last API changes are published on the [API news] page (https://developers.shoptet.com/category/api/).

Download OpenAPI description

openapi.json

openapi.yaml

Servers

https://api.myshoptet.com/

Eshop

This endpoint is used for general information about the e-shop settings.

Operations

Eshop info

Request

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.

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.

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

Query

includestring

Sections to include

Example: include=orderAdditionalFields,orderStatuses,paymentMethods,shippingMethods,imageCuts,countries,cashDesk,languages

Headers

Content-Typestringrequired

Default application/vnd.shoptet.v1.0

curl -i -X GET \
  'https://api.myshoptet.com/api/eshop?include=string' \
  -H 'Content-Type: application/vnd.shoptet.v1.0' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE'

Responses

Bodyapplication/vnd.shoptet.v1.0+json; charset=utf-8

dataobjectrequired

data.contactInformationobjectrequired

data.contactInformation.eshopIdintegerrequired

e-shop ID

data.contactInformation.eshopNamestringrequired

name of the e-shop

data.contactInformation.eshopCategorystring or nullrequired

category of the e-shop

data.contactInformation.urlstringrequired

e-shop domain

data.contactInformation.eshopTitlestringrequired

name of the store

data.contactInformation.eshopSubtitlestring or nullrequired

subtitle of the store

data.contactInformation.contactPersonstring or nullrequired

contact person (e-shop owner)

data.contactInformation.emailstring or nullrequired

contact person email

data.contactInformation.phonestring or nullrequired

contact person phone

data.contactInformation.mobilePhonestring or nullrequired

contact person mobile phone

data.contactInformation.skypeAccountstring or nullrequired

contact person skype account

data.contactInformation.contactPhotoUrlstring or nullrequired

contact person photo URL

data.billingInformationobject

data.settingsobjectrequired

data.settings.vatPayerbooleanrequired

flag, whether the e-shop is a VAT payer

data.settings.cashDeskOnlybooleanrequired

flag, whether the e-shop is operated exclusively in cash desk mode

data.settings.trackStockClaimsbooleanrequired

flag, activate stock claim count

data.settings.maxProductAmountintegerrequired

maximum number of products allowed

data.settings.maxEmailAmountintegerrequired

maximum number of e-mails allowed

data.settings.defaultPricelistobject(pricelist)required

default pricelist

data.settings.defaultPricelist.idintegerrequired

price list identifier

data.settings.defaultPricelist.namestringrequired

price list name

data.settings.eshopLanguagestringrequired

default language code of the e-shop

data.settings.timezonestringrequired

e-shop timezone

data.settings.dateFormatstringrequired

eshop date format

data.settings.timeFormatstringrequired

eshop time format

data.settings.internalsstringrequired

e-shop language internals - shows eshop internal language settings, that can change some behavior like EET, vat/tax, ...

data.settings.exchangeRateFlipbooleanrequired

rate flipping

data.settings.negativeStockAmountstringrequired

determines if negative stock buying is allowed. Possible values: allowed, no-show-product (no, but still show product), no-hide-navigation (no, show product, hide in navigation), no-hide-product (no, hide product)

Enum"allowed""no-show-product""no-hide-navigation""no-hide-product"

data.settings.ossboolean

Determines if eshop has the OSS (One stop shop) tax mode enabled, this affects behavior of VAT rates in the order.

data.currenciesArray of objectsrequired

data.currencies[].codestringrequired

currency (ISO format 3 characters)

data.currencies[].titlestringrequired

currency name

data.currencies[].isDefaultbooleanrequired

flag, whether this is the default shop currency

data.currencies[].isDefaultAdminbooleanrequired

flag, whether this is the default administration currency

data.currencies[].isDefaultDocumentsbooleanrequired

flag, whether this is the default documents (invoicing) currency

data.currencies[].isVisiblebooleanrequired

flag, whether the currency is visible in the e-shop

data.currencies[].exchangeRatestring(typeExchangeRate)^[0-9]+\.[0-9]{8}$required

currency rate of the receipt for the default currency of the shop. This value is saved together with the price and reflects the historical value valid in the instant of the order creation. If the shop changes the default currency, the value still refers to the original currency!

data.currencies[].priorityintegerrequired

currency priority

data.currencies[].displayobjectrequired

data.currencies[].display.textstringrequired

currency symbol

data.currencies[].display.locationstringrequired

position of currency symbol, possible values are (left) and (right)

Enum"left""right"

data.currencies[].display.decimalsSeparatorstringrequired

currency display decimal separator

data.currencies[].display.thousandsSeparatorstring or nullrequired

currency display thousands separator

data.currencies[].priceDecimalPlacesintegerrequired

number of decimal places

data.currencies[].documentPriceDecimalPlacesintegerrequired

number of decimal places

data.currencies[].roundingstringrequired

way of rounding, possible values are (none), (up), (down) and (math)

Enum"none""up""down""math"

data.currencies[].minimalOrderValuestring or null(typePrice)^(-)?[0-9]+\.[0-9]{2}$required

minimal order value

data.currencies[].bankAccountobjectrequired

data.currencies[].bankAccount.accountNumberstring or nullrequired

account number

data.currencies[].bankAccount.ibanstring or nullrequired

IBAN

data.currencies[].bankAccount.bicstring or nullrequired

BIC

data.taxClassesArray of objectsrequired

data.taxClasses[].titlestringrequired

descriptive name of tax rate

data.taxClasses[].ratesArray of objectsrequired

the list of tax rate zones

data.taxClasses[].rates[].zonestringrequired

zone name

data.taxClasses[].rates[].vatRatestring(typeVatRate)^[0-9]+\.[0-9]{2}$required

VAT rate

data.taxClasses[].isDefaultbooleanrequired

flag, whether the default VAT rate is for e-shop

data.activeModulesArray of objectsrequired

data.activeModules[].titlestringrequired

module descriptive name

data.activeModules[].namestringrequired

module identifier

data.urlsArray of objectsrequired

data.urls[].identstringrequired

URL identifier

data.urls[].urlstringrequired

URL (correct form based on e-shop and administration)

data.socialNetworksobject

data.orderAdditionalFieldsArray of objects

data.orderStatusesobject

order statuses, must be requested using include=orderStatuses

data.paymentMethodsobject

data.shippingMethodsobject

available transport options, must be requested using include=shippingMethods

data.imageCutsArray of objects

the information on image cuts must be requested using include=imageCuts

data.languagesArray of objects

supported languages in eshop

data.trialboolean

flag, whether the e-shop is in trial mode

data.countriesArray of objects

the information on countries must be requested using include=countries

data.cashDeskobject

eshop cash desk configuration

errorsArray of objects or null(Errors)required

errors[].errorCodestringrequired

Short text error identification

errors[].messagestringrequired

Descriptive error message

errors[].instancestringrequired

Identification of the entity referenced

Response

application/vnd.shoptet.v1.0+json; charset=utf-8

{
  "data": {
    "contactInformation": { … },
    "billingInformation": { … },
    "settings": { … },
    "currencies": [ … ],
    "taxClasses": [ … ],
    "activeModules": [ … ],
    "urls": [ … ],
    "socialNetworks": { … },
    "orderAdditionalFields": [ … ],
    "orderStatuses": { … },
    "paymentMethods": { … },
    "shippingMethods": { … },
    "imageCuts": [ … ],
    "languages": [ … ],
    "trial": false,
    "countries": [ … ],
    "cashDesk": { … }
  },
  "errors": [
    { … }
  ]
}

E-shop design

Request

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.

Headers

Content-Typestringrequired

Default application/vnd.shoptet.v1.0

curl -i -X GET \
  https://api.myshoptet.com/api/eshop/design \
  -H 'Content-Type: application/vnd.shoptet.v1.0' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE'

Responses

Bodyapplication/vnd.shoptet.v1.0+json; charset=utf-8

dataobjectrequired

data.templateobjectrequired

e-shop template

data.template.namestringrequired

template name, enum value [swing, jazz, funk, pop, rock, soul, techno, echo, tango, waltz, classic, step, custom]

data.template.colorVariantstringrequired

code for a specific color variant of a template

data.layoutobjectrequired

page layout

data.layout.homepagestringrequired

product detail, enum value [list, listImage, catalog2, catalog3, catalog4]

Enum"list""listImage""catalog2""catalog3""catalog4"

data.layout.subPagestringrequired

subpage, enum value [list, listImage, catalog2, catalog3, catalog4]

Enum"list""listImage""catalog2""catalog3""catalog4"

data.layout.productDetailstringrequired

product detail, enum value [list, listImage, catalog2, catalog3, catalog4]

Enum"list""listImage""catalog2""catalog3""catalog4"

data.colorSchemeobjectrequired

data.colorScheme.conversionColorstringrequired

conversion color

data.colorScheme.conversionColorHoverstringrequired

conversion color upon cursor hovering

data.colorScheme.color1stringrequired

primary color of e-shop

data.colorScheme.color2stringrequired

primary color upon cursor hovering

data.colorScheme.color3stringrequired

secondary e-shop color (can be null - not for all templates)

data.colorScheme.color4stringrequired

secondary e-shop color upon cursor hovering (can be null - not for all templates)

data.fontsobjectrequired

data.fonts.headingstringrequired

data.fonts.textstringrequired

data.headerobjectrequired

data.header.backgroundImagestring or nullrequired

background image (can be null)'

data.header.imagestring or nullrequired

header image (can be null)

data.header.logostring or nullrequired

e-shop logo in header (can be null)

data.header.colorstring or nullrequired

Header background color for templates Techno, Tango, Classic, Step and Disco (can be null)

data.backgroundobjectrequired

data.background.enabledbooleanrequired

flag, whether background is enabled

data.background.colorobject or nullrequired

data.background.color.enabledbooleanrequired

flag, whether the background color is on

data.background.color.colorstring or nullrequired

background color (can be null)

data.background.imageobject or nullrequired

data.background.image.urlstring or nullrequired

background image URL (can be null)

data.background.image.attachmentstringrequired

mounting, enum value [scroll, fixed]

Enum"scroll""fixed"

data.background.image.positionstringrequired

location, enum value [center, tile]

Enum"center""tile"

errorsArray of objects or null(Errors)required

errors[].errorCodestringrequired

Short text error identification

errors[].messagestringrequired

Descriptive error message

errors[].instancestringrequired

Identification of the entity referenced

Response

application/vnd.shoptet.v1.0+json; charset=utf-8

{
  "data": {
    "template": { … },
    "layout": { … },
    "colorScheme": { … },
    "fonts": { … },
    "header": { … },
    "background": { … }
  },
  "errors": [
    { … }
  ]
}

E-shop mandatory fields

Request

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.

Headers

Content-Typestringrequired

Default application/vnd.shoptet.v1.0

curl -i -X GET \
  https://api.myshoptet.com/api/eshop/customer-fields \
  -H 'Content-Type: application/vnd.shoptet.v1.0' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE'

Responses

Bodyapplication/vnd.shoptet.v1.0+json; charset=utf-8

dataobjectrequired

data.billingAddressobjectrequired

invoicing address

data.billingAddress.companystring(typeCustomerFieldValue)required

company name, enum [required, optional, hidden]