Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The Mediablob API 1.0 is based on xml.
While the original transport was only over SOAP, Mediablob now supports async posting of xml files over https. This method is much easier to use, and returns control faster to your application.
While there are no immediate plans to remove the legacy soap support, the async https transport is highly recommended for new api development.
There are two available endpoints; one for development and testing, and the other for production use.
Development: https://api.test2.mediablob.com/api/xml
Production: https://api.mediablob.com/api/xml
Since the api supports standard http requests, it is easy to connect any environment to the api once you have your account details.
An effective way of testing the Mediablob integration is by using Chrome with the extension Talend API Tester.
Install the addon.
Open the new app from the upper right corner of Chrome.
Select the Method, i.e. POST and fill in the url to the endpoint
Add an Authentication request header that conforms to the credentials provided by Shoppa, i.e Authentication: Basic dXNlcm5hbWU6cGFzc3dvcmQ=.
Add a proper Content-Type request header that describes what content is provided in the request body, if any. i.e. Content-Type: application/xml.
Fill in the request body, if needed. When submitting xml to the /api/xml enpoint, the content shall not be manually xml-encoded (something that was required when using SOAP).
Click Send to post the xml file to the endpoint.
Shoppa also provides C# source code for a sample application that uploads xml files to the api.
There are two available endpoints; one for development and testing, and the other for production use.
Development: http://ws.test2.mediablob.com/services/products.asmx
Production: http://ws.mediablob.com/services/products.asmx
You can open the endpoint urls in a standard browser and read about the provided functions.
Since the api supports standard soap requests, it is easy to connect any environment to the api once you have your account details.
An effective way of testing the Mediablob integration is by using Chrome with the extension Wizdler.
Install the addon.
Browse to the wsdl-definition of the webserver at http://ws.test2.mediablob.com/services/products.asmx?WSDL.
Click on the Wizdler icon in the addons toolbar and select the function you want to call.
Rewrite the example content in the browser window.
Click GO to post the xml file to the service.
Await the service response.
Shoppa also provides C# source code for a sample application that uploads xml files to the api.
Use the development endpoint for development and integration testing. The test environments have additional data format validation that gives better developer feedback. By working in a testing sandbox, you ensure any errors can be detected without affecting production users.
Switch to the production endpoint when uploaded data shall be seen by the end users.
The environments can of course be used in parallel. Just understand that testing and production environments are completely separated.
You will need a username and password to access any services in the Mediablob api. You also need to know your customer id(s) for many operations.
Accounts to the test and production environments are provided by the Shoppa Support Centre. Ask your Shoppa representative to request an account on your behalf.
Mediablob API is the developer interface for storing product information in the Shoppa eco-system.
The api comes in several versions. All api versions are both forward and backwards compatible with any version of the Shoppa Client, but to take full advantage of the latest functionality of Shoppa Client, your Mediablob integration must use the latest api version.
All xml schema definitions (xsd) can be downloaded at XSD
An integral part of the Shoppa eco-system is the customer tree. All users belong to a customer node, which in turn has a parent node. All customer nodes for a tree in this way, with one parent and optionally multiple children.
The customer tree is created by Shoppas specialists together with the customer. Contact Shoppa Support Centre if you need to update the customer tree.
Any product or storeinfo-object created at a node is available to all lower levels, provided it is not restriced by country code.
A customer can also get access to content from an external customer node if a reference is created to that node. This is used for instance to provide supplier information to several different companies. Customer references can only be created and removed by Shoppas solution architects.
All information in Mediablob is based around a product. Products support different languages and can be restricted to a specific country.
A product has several named text fields. Allowed field names are defined in the Fields page and are used by Tags in Shoppa templates to display the correct product information.
At a customer level, the product stores up to one text and one image per field and language code.
The same picture can be assigned to several fields and different pictures can be assigned to the same field, but for different language codes. This is especially useful for images with embedded texts.
Products can be partially overridden at any customer level. This information is then used for all customer node further down the tree. If an overriden text is later deleted, the original text is restored.
The Product primarily stores static information that is not bound by time. When a product is updated the change is visible immediately to all users and remains the same until the product is changed again. Thus, products shall not contain volatile information such as price. Such properties should be handled by StoreInfo objects.
Existing products can be enriched for specific customers and timespans.
While any text or picture of a product can be overridden, StoreInfo objects typically describe pricelists or campaigns. StoreInfo is perfect for tracking different product prices per store.
It is important to create the products before relating to them in StoreInfo objects.
As stated before, any product field can have one picture assigned to it. The same picture can be referenced by many fields, and many products, in several languages.
Pictures are uploaded to Mediablob by calling UploadImage2 or UploadAndClipImage. When an image is uploaded, its md5 hashCode is returned. Use this hashCode as future reference in products.
To reduce bandwidth usage, api users are encouraged to calculate the md5 hash code themselves and check if the image exists in Mediablob through the ImageExists or ImageExistsMd5 functions prior to uploading images.
Note: Images are always hashed before being processed by Mediablob services, so it can be correctly precalculated before uploading.
Note: It is not possible to delete images in Mediablob through the API.
NOTE: This describes schema version 1.7.
A product has codes, texts and pictures. The texts and pictures can be defined for multiple languages. For each product a set of complement products can also be defined.
Note that all used languageCodes must be registered on the account used to upload the information to Mediablob. Please check your account details with your Shoppa representative if you are unsure.
Lets build a product from scratch and see how different requiements evolve its xml definition.
Lets say our customerId is 1143 and we have a product with only some basic information:
brand: Orrefors
name: Champagneglas
sku: 65467-14
ean code: 123456789012
This corresponding xml format is:
A product must always have at least one text section. Brand and name are required for new products. In the example above the product is described in the Swedish language.
We extend the product with additional sales arguments and a unit for prices:
short sales argument: Exklusivt tvåpack. En perfekt bröllopspresent.
long sales argument: Efva Attling är en juveldesigner som har använt sin rika erfarenhet och expertis för att skapa glaskonst. Hennes tredje glas är ett maskulint martiniglas med en silverring.
unit: st
The xml for describing the product now becomes:
To protect content against xml formatting constraints, the & character is xml encoded. This follows the xml specification and must be used for any content.
We decide to support English too. The xml gets extended with an additional <text /> section. We also start the product with a generic language text xx with generic text for all languages unless overridden.
Even without actual such texts, we recommend always including a row for xx to prevent duplicate products in the future.
Finally, we add pictures to the swedish brand and productName fields. English users do not get to see any pictures for now.
As you can see, the pictures are referenced by a hashCode. What hashCode to use will be described in detail in the Pictures section.
Pictures require a countryCode. This is a legacy construct and is easily created by lowercasing the last two characters of the languageCode.
The hashCode returned from the picture uploader is based on md5, but formatted as a guid. The difference is big or little endianess. If you prefer to reference the picture by its md5 code, you can use the md5 attribute instead:
Instead of referencing an image by hashCode or md5, you can provide a public uri from where Mediablob can download the picture for you. Mediablob will only use the same uri once, so you must ensure the uri is unique for each picture. Avoid using this scheme unless you are using a picture database that ensure unique uri's per picture.
In the sample above, Mediblob would keep using the original downloaded picture even if the content of the uri changes.
While our SOAP based webservice will remain in operation for some time longer, it is no longer being maintained and will not be updated with bug fixes, etc. If you are already using the SOAP based service we recommend that you switch over to using our REST based service at your earliest convenience. If you are integrating your system to ours for the first time, we strongly urge you to use the REST based service, not the SOAP based one.
The SOAP specific documentation will remain online as long as we accept SOAP requests, only as a convenience to our customers currently using it. Again, if you are building a new integration, use REST instead.
Soap is a standard protocol that will not be discussed in detail here. There are some peculiarities to know about when integrating with Mediablob though; specifically Mediablobs use of an <AuthHeader /> section.
Another quirk, that is handled automatically by tools such as Visual Studio, is that xml content must be xml-encoded.
Mediablob does not use any cookies or other common login mechanisms to validate access. Instead Mediablob expects an AuthHeader section in the soap header.
The AuthHeader looks like this:
The username and password authenticates the user. Mediablob then verifies the users privileges and authorizes the rest of the request.
The customerId is used to instruct Mediablob which customer node the uploaded xml file relates to. The customerId can either be a ShoppaID assigned by Shoppa when the customer node was created, or an ExternalID assigned to each store by the customer.
Contact Shoppa Service Center to change what ExternalID to use for different stores.
The customerId must always be for or below the node the user logs in to. To prevent pre-generated xml-files to be uploaded to the wrong account by mistake, the customerId must correspond with the customerId of the uploaded xml file.
The content of any xml element must be xml encoded. This is achieved by replacing each character with its encoded counterpart. Thus, in the Mediablob product xml you would need to encode the product text Köp & vinn! as Köp & vinn!.
Xml encoding is automatically handled by high-level frameworks like C# and Java. You only need think about this when you create your xml file manually.
What can be a bit confusing is when you wrap the Mediablob xml in soap. Since your xml file is content in a soap element, it needs to be xml encoded, including any text you encoded inside your xml. The product text above would then become Köp &amp; vinn!.
Mediablob also requires an xml declaration line at the top.
Lets say we want to upload the following product definition:
Using the following user details:
username: demouser1
password: Not_a_real_password
ShoppaID: 1143
Encoded and wrapped in a valid soap request this becomes:
Copy this text and POST it with Wizdler to Mediablobs development endpoint. You should get the following response with status code 200 if you did it right:
An authorization is necessary for the request towards Shoppa's REST API or SOAP protocol. The documentation provides a description on how to receive credentials for an integration user
Integration users and customer nodes are managed set up and managed by Shoppa. Contact your Shoppa representative if you need help with the management.
An integration user consists of four parameters that are necessary for the integration purpose. The parameters are "username", "password", "languageCode", and "countryCode".
Username and password are used to authenticate your requests. They are part of the authentication header.
LanguageCode and countryCode values determine which languages and countries you can store Mediablob data on. These values are used in the Shoppa XML's to decide where to store the data and who should be able to access it.
Customer nodes always consists of a ShoppaID which is an auto incremental value. Each customer node has the option for a custom ExternalID value. Either value can be used when uploading Shoppa XML's to decide where the data should be stored.
List of all available schema versions for each XML type.
PUT https://api.mediablob.com/api/xml
Available Shoppa XML's can be found at XML structure
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
SessionId example:
PUT https://api.mediablob.com/api/xml/custom
Custom XML's will be passed through one or several XSLT schemas before being uploaded to the service bus queue. XSLTs are uploaded by Shoppa. To upload or change an XSLT, contact your Shoppa representative for help.
SessionId example:
GET https://api.mediablob.com/api/xml/{date}
Id: SessionId for the message. File: Link to the upoaded file. Result: Route to retrieve the result file. See #api-statusfor more information. Errors:
GET https://api.mediablob.com/api/status/{sessionId}/done
{sessionId} corresponds to the hashcode returned by a 202 Accepted response in #api-xml
GET https://api.mediablob.com/api/status/{sessionId}/result
{sessionId} corresponds to the hashcode returned by a 202 Accepted response in #api-xml
Response header contains a parameter "Location". The parameter contains an URL to the error message.
POST https://api.mediablob.com/api/images
Upload one or more images to Mediablob as multipart form data objects. If this image already exists, the
In C# you need to add the images to a MultipartFormDataContent object, which you add to an HttpClient call. The response contains the Mediablob id for each image, which you can use to reference the images in further integrations.
If your image has a clipping path you can add these parameters to the call to tell our rest endpoint which clipping path you want to use. The invert parameter is there to make it possible to invert the clipping path.
HEAD https://api.mediablob.com/api/images/{Mediablob-hashcode}
Verify that an image exists in Mediablob by using the Mediablob-hashcode that was returned when the image was originally uploaded.
GET https://api.mediablob.com/api/images
Find the Mediablob-hashcode for an image that has been previously uploaded. You need to provide one of md5 or uri query parameter, but not both in the request.
The Mediablob-hashcode is returned in the response if it is successful, which you can use to reference the image in further integrations.
Sometimes you need to delete existing products or parts of a product, or you want to make sure any existing information is removed and not merged with the new information. Below we describe the different approaches you can use to solve this.
You delete a product field by simply assigning it as an empty field.
Lets say we want to delete the infoshort field we added in Adding a new text field. We can do that by sending the following xml:
Note however that in case this product was overloaded from another customer node, the original text will now be visible again. If you actually want the field to be empty, regardless of what has been defined at a higher level, you need to write an empty space to the field, like this:
The space inside the field content is mandatory here. If the field is empty the original content will be visible again.
To remove an entire language from our example product, we add a <text/> section with the attribute delete="true":
There is no reason to add text fields to a deleted <text /> section since the import will simply ignore them.
If you want to replace all texts for a specific language and make sure there are no legacy fields left behind, you need to write a delete-section followed by the new <text /> section:
Make sure the delete comes first, or your newly added texts will be deleted too!
Sometimes you want to delete an entire product, with all texts, codes and picture references. This is done with the following xml:
As before, if the product is owned by another customer, the product will still be visible with its original content.
This describes .
While most product information is static over time, prices are not. Stores have different prices for the same product and prices change at different times. This information is stored in pricelists which is one kind of StoreInformation package.
In contrast to products and campaigns, pricelists are not automatically inherited along the customer tree. A store uses the pricelist named STANDARD from its own node by default, but a named pricelist from a parent node can be explicitly selected instead.
Pricelists are described by packages with a name and a start date, but no stop date. If no name is provided, the default name STANDARD is assumed. If you also provide a package id, you can later use this to refer to that package instead of using name + start date.
Mediablob primarily identifies packages by id + countryCode. If id is not provided, the package is identified by name + countryCode. We recommend using the id for identification when possible. This behaviour is different from previous versions of the api and should be considered when updating existing integrations.
Prices are changed by sending a new package with the same name for a later date.
Lets build a pricelist from scratch and see how it evolves with different requirements.
Lets say store S123 wants to sell our sample product for 205 SEK. The price is valid from September 21st, 2008. The corresponding xml format for creating a standard pricelist is:
Some stores may use a mutual pricelist. In this case HQ wants to publish a named pricelist the stores can subscribe to. We create the same pricelist above as a named pricelist. We use an id from the HQ ERP system for future tracking and updates. Here is the xml we need:
Now we want to add two other products to the named pricelist. The xml for this is:
After this, the pricelist contains three priced products.
We finally decide to restructure our pricelist system and want to delete a pricelist completely. We do this by setting the delete attribute but omitting the startDate. The xml for this is simply:
In addition to deleting a complete pricelist you also have the option to remove a selection of products from the existing pricelist. Instead of defining the delete attribute in the package tag, it will be set in the product tag. The xml for this is simply:
Future price changes requires the use of StoreInfo schema version 1.6 or higher and is only supported by Shoppa versions 2.25 or higher.
Assume we have the following base price list to begin with. It has a start date of 2020-01-01
From 2020-01-15 we want to increase the price of product 111111 to 59.95 SEK. We also want to lower the price of 222222 to 19.95 and 444444 to 69.95 two weeks later.
Here we have to refer to the same package ID as the base price list if the changes are to be combined with the base price list at desired change date. Each package startdate in the XML defines when the changes will apply.
We have therefore created one package with startdate 2020-01-15 and one with startdate 2020-02-01 for the respective price changes.
The price of the product 333333remains the same at each change date.
If we want to reduce a price during a short period of time, for e.g. under a two month time. Afterwards we are to set the old price back again. We can not set a stopdate for the reduced price, instead we have to send the higher price on new.
The product will now be on a reduced priced during the two months between 2020-02-01 and 2020-03-31. At 2020-04-01 th eproduct will return to its original price.
It is possible to remove a previously uploaded package in case it was incorrect. This will remove all price changes that were set to occur at the specific date.
We delete the price changes above for 2020-02-01 with this xml:
The price change at 2020-01-15 will still be in effect.
To remove individual products from future price changes, use the delete attribute on the product element, like so:
We have now deleted the change for product 444444.The change for product 222222 at 2020-02-01 will still remain.
Here we will send in a few price changes for the product 111111 over a period of time. We will have price changes at each package startdate.
To remove all future price changes for product 111111we have to delete the product from each future price change package with the same startdate defined as when the change were to occur.
The XML will look like this:
Assuming we don't know when all the price changes for a product occurs, we can delete all prices for a product by sending in the product with an empty price value. The startdate of the package will determine from which date the prices are deleted.
All future price changes and the current price for product 111111 are now deleted, starting 2020-01-15.
Here we have a price change for 2020-02-01. After a while it is decided that the product should have another price from the same startdate. Correcting the price change is accomplished by setting the new price for the same startdate.
At 2020-02-01 the product will now have a price of 24.95 instead of the original 19.95.
Some time passes and we have made multiple changes to our pricelists at different times. For some reason we may have the need to replace all prices in a pricelist with new prices. Some products may no longer be relevant for example. We do this by setting the fullPackage attribute like this:
Now there will no longer be a price for product 333333 or 444444 starting from 2020-04-15.
Products have a number of fields in which you can enter information about the product. This document provides a short summary of the fields common to all users. New, specialized, fields can be created on a customer basis, contact your Shoppa representative for more information.
When creating a new product, there are certain fields that must be defined:
Brand
Product name
At least one Code field (see below)
Code fields are special, in that their values must be unique. That is, no two of your products may contain the same value in, for example, their Code 1 field. The uniqueness constraint does not carry over multiple fields, e.g. one products Code 1 can be the same as another products Code 3 without issue. The constraint also doesn't carry over between customers, i.e. one of your products may have the same Code 1 as a product belonging to another customer.
| Identifier | Data Type | Recommendation |
|---|
Price fields are only available in price lists and campaigns. They can therefore only be integrated using the storeinformation XML.
Pictures can be attached to any fields, but we do have some recommendations, i.e. the main product picture should go in the 'product name' field. These recommendations are listed below.
Primary image - productname
Secondary image - techname
Third image - infoshort
Fourth image - infolong
There are additional fields with no intended use case. These can be used if there are no other suiting fields available.
For every product we can assign a list of complement products. The complements are displayed in Shoppa when the base product is displayed and can be automatically assigned to templates to easily build multi-product signs.
Note: Just because product A assigns product B as a complement does not mean the opposite is true. You must explicitly assign all relationships you want to use.
Lets assign a complement product to our sample product:
You can of course assign complement products at the same time you create your product or modify other properties of it. The only requirement is that the complement product already exists in Mediablob.
If you send a <complementProducts /> list as above, the new complements will be merged with any existing complements and make the list of complements longer. If you instead want to replace the existing complements with a new list, you need to set replace="true":
The above xml effectively deletes complement 65468-3, since it is no longer part of the list.
If you want to delete all existing complements for a product, you set delete="true" on the <complementProducts /> section:
Note that deleting the complements list does not delete the product itself.
When you want to extend a product with additional information you simply send the product information you have with an existing product identifier.
The extended information can be anything; an additional language, an extra product code or picture references.
You can also reference the product by its ean code instead, by replacing the first line with <product id="123456789012" idType="EAN13">. As you see, any code can be used as long as it is unique to the product.
Continuing on the section Extending product information, English could have been added to the existing product by sending only this xml:
As you see, adding a field or an entire extra language is essentially the same. Just reference the product by its identifier and add the missing information.
As stated initially, all products at a top customer node are available to all children. This means there is usually no need to add products at a store level. Instead the products are added to the HQ node or any branch-nodes in between HQ and the stores used for segmentation of information.
In some instances a store or branch-node needs to replace a certain part of a product. This is achieved by sending the same kind of update mentioned above, but for another customerId. Customer id´s are defined in the SOAP metadata and described in detain in a later chapter.
Campaigns describe temporary prices used at one or more stores for a specific time period. Campaigns are usually used to show customers the original price and how much they save during the campaign. For this reason, campaigns are layered on top of the stores pricelist when used by Shoppa.
Like pricelists, campaigns are described in a StoreInformation package. Campaigns are always created with a start- and a stopdate and they always need a name that can be used in Shoppa Client to select it.
As with pricelists, campaigns can be identified with name, startDate and countryCode, but for simplicity we recommend using a reliable id instead.
A campaign can not be converted to a pricelist and vice versa. If you create the wrong kind of package you need to delete the package and create a new one from scratch.
Lets make a 50% off campaign for our sample glass 65467-14 from October 1st - 4th. The xml for this is:
We decide to postpone our campaign one day and extend it to a full week. If we simply set a new startDate we would update product prices at that date rather than of changing the startdate of the entire campaign. Moving the campaign thus requires us to use the attribute newStartDate:
What campaigns to run in an organization may be known a long time at HQ, but it may be sensitive to tell the stores too early and risk informing customers and competitors. By setting the visibleStartDate attribute you decide how long beforehand the stores see the campaign. All users at HQ still see the campaign in their clients and can validate its content.
Similarly, some stores may want access to campaigns after they formally end, to run them a little longer and get rid of excess stock. To keep the campaign visible in Shoppa Client after the campaign ends you set the visibleStopDate attribute.
A product can have complement products assigned to it specifically in a campaign. You can also assign campaign information to the complement products as you are assigning them. Note that values cannot be set with the value attribute, they have to be contained by the field element.
You should also add the attribute complementBehaviour to the product element. This takes one of three values and determines the way complement products are added and/or removed. The accepted values are replace, delete and merge. They do the following:
Replace: Removes all existing complement products and replaces them with the new ones. This is the default option.
Delete: Removes all existing complement products. Any new complement products will be ignored.
Merge: Adds the new complement products to the set of existing ones.
If a campaign should be removed completely, that can be achieved by setting the delete attribute in the package tag. We refer to the campaign by defining the corresponding id, startDate, and stopDate. The xml for this is simply:
If we instead only want to remove a selection of products from the campaign, we set the delete attribute in the product tag. The xml for this is simply:
Local prices in combination with central prices requires the use of Shoppa version 2.25 or higher.
Pricelists on a store level overrides central prices only if the store is subscribed to the central pricelist, both pricelists have the same package ID, and the local pricelist does not have the name "STANDARD"
All future price change functionality is applicable for local overridden pricelists as well as central pricelists.
Locally overridden prices for a product will always trumf any centrally price changes for the same product.
Here we have a central pricelist stored on a HQ level.
In one of the stores we have different prices for the products with ID 222222 and 333333. We will therefore only send the price changes to the local pricelist.
Store1 will now have the local prices in addition to central prices that are not overridden. The other stores will receive all the prices from the Central Pricelist.
If a local price stops being active and we want the central price to be used again, it can be accomplished by deleting the local price from its pricelist.
Here we have deleted the product with ID 222222 from the local pricelist. Store1 will now receive a price for the product from the Central Pricelist. Other local price overrides will still remain.
This describes .
A signorder file can reference a number of products, which display groups that should be used to print them, and how many copies should be printed. Additionally you can specify values for the product fields (e.g. price, text1, etc.). Note that these values will not override existing product fields, but will only populate empty fields. The exception to this is the price field, which will override existing prices.
Other notes:
To specify values for code fields (Code1, EAN13, etc.) you need to use the <code> element, rather than the <field> element.
To get multiple products onto one template they need to be grouped in a products element. Which display group to use should then be specified for the products element, and not the individual product elements. In this case the product elements need to have the productIndex attribute, in order to specify which product index to use in the template(s).
The usageDate attribute can be used to get prices from future dates. If omitted, todays date will be used.
If the autoPrint attribute is false, there is no need to specify display groups.
Display groups are managed through the Shoppa client. Each display group can reference multiple layouts and formats of multiple templates, and also a different number of copies for each. The most common use case is one copy of one format/layout/template.
The file DisplayGroups.xml is located in the sub folder Schemas in the hot folder. It is automatically generated by the Shoppa client, and contains information about the available display groups. It could look something like this:
Each group has a name, an Id and at least one member, groups without members are omitted from the file. Each member references a template, a layout, a format and a number of copies.
The Shoppa application can accept sign orders from external applications for printing. The sign order is an XML file which follows a predefined XML schema. The external application or PDA places the XML file in a predefined “hot folder” and Shoppa imports the file from this folder. The sign order can include one or many products. Each defined product can have text fields like name, brand, description, price and so on. The sign order has an auto print option. If this option is activated Shoppa will put all products on a predefined template and automatically send them for printing. When the auto print option is disabled Shoppa will show the products in a list for further action by user.
A few things are needed in order to use the local integration functionality:
The correct Add Ons for your enterprise and store level accounts. If you don't already have these, contact your Shoppa representative.
The location of the hot folder needs to be specified in the Shoppa configuration file, see below.
One or more display groups need to be created, preferably on an enterprise level account.
The location of the hot folder needs to be specified in Shoppas configuration file (shoppa2.exe.config). The relevant section is this:
If this setting does not already exist, add it in the <Shoppa.PL.Windows.Properties.Settings> section. If the folder does not already exist, the Shoppa client will create it on startup.
In order to send a signorder file to Shoppa, simply place it in the hotfolder, either by hand for testing purposes, or use another appliction.
The folder will contain three or four subfolders, depending on the version of the Shoppa client.
In Shoppa 2.25 and newer, finished files will be moved to the archive folder after three days. Older versions do not do this, and the archive folder is not created.
If a something goes wrong when processing a signorder file it will be moved to the error folder, along with a .txt file containing an error message. A timestamp will be appended to the name of the signorder and the corresponding error file will have the same name, except for being a .txt file rather than an .xml file.
When a signorder is successfully processed it is moved to the finished folder. A timestamp will be appended to the name of the file.
There are several use cases for the signorder functionality. These are a few examples.
An application running on a handheld device can read the DisplayGroups.xml file if the hot folder is placed on a shared network drive and dynamically generate a list of available print options. The user can scan barcodes to select products and choose which template to use while out and about in the store. The application can generate a signorder and place it in the hot folder, and the selected signs will be printed through a computer running Shoppa. The user can then collect a stack of printed signs from the printer and start putting them up.
An application running on the same workstation as the Shoppa client can generate a list of products to print based on whatever business logic is available to it. The application can place a file in the hot folder and the user can access the list in Shoppa and create the required signs.
Uploading an image to Shoppa's central database will result in the picture passing through an image handling before the image is stored on Shoppa's servers.
Uploading images to Shoppa's central database can be done in two ways. Either the image is uploaded by itself or the image is uploaded with an URI in the Mediablob.xml.
To optimize speed of the whole workflow from creating templates to printing in the stores, Shoppa automatically reduces image sizes if needed. Images larger than 2025 x 2025 pixels or 1 MB are compressed when imported to Shoppa's central database.
With the add-on "Bigger Pictures" you can import images up to 4000x4000 pixels or 3MB. Contact Shoppa for more information on how to enable it.
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Identifier | Data type | Text recommendation |
|---|
| Identifier | Data type | Use case |
|---|
| Identifier | Data type |
|---|
The Schemas folder contains a file called DisplayGroups.xml that describes the available .
Authorization*
String
Basic authentication using the integration user credentials.
customerId*
String
ShoppaID or ExternalID for the customer node.
customerIdType*
String
"ShoppaID" or "ExternalID". Should be correspondant to the id used as customerId.
Text
String
File
Object
Authorization*
String
Basic authentication using the integration user credentials.
customerId*
String
ShoppaID or ExternalID for the customer node.
customerIdType*
String
"ShoppaID" or "ExternalID". Should be correspondant to the id used as customerId.
Text
String
File
Object
Authorization*
String
Basic authentication using the integration user credentials.
customerId*
String
ShoppaID or ExternalID for the customer node.
customerIdType*
String
"ShoppaID" or "ExternalID". Should be correspondant to the id used as customerId.
invert
String
True if the inside of the clipping path shall be removed instead of kept. Defaults to False.
clippingpath
String
The name of the clipping path to be used. Defaults to not use clipping paths.
Authorization*
String
Basic authentication using the integration user credentials.
customerId*
String
ShoppaID or ExternalID for the customer node.
customerIdType*
String
"ShoppaID" or "ExternalID". Should be correspondant to the id used as customerId.
file
Object
Binary image data. Repeat for each image to be uploaded. The parameter name is not used.
Authorization*
String
Basic authentication using the integration user credentials.
customerId*
String
ShoppaID or ExternalID for the customer node.
customerIdType*
String
"ShoppaID" or "ExternalID". Should be correspondant to the id used as customerId.
md5
String
The md5 hash of the original image.
uri
String
An external uri from which the image was originally fetched. Images can be fetched from external uri's during product xml uploads.
Authorization*
String
Basic authentication using the integration user credentials.
customerId*
String
ShoppaID or ExternalID for the customer node.
customerIdType*
String
"ShoppaID" or "ExternalID". Should be correspondant to the id used as customerId.
code1 | String | Primary article number |
code2 | String | Additional article number |
code3 | String | Additional article number |
code4 | String | Additional article number |
code5 | String | Additional article number |
code6 | String | Additional article number |
ean8 | String | EAN 8 code |
ean13 | String | EAN 13 code |
amount | Double | Amount of the product in the packaging |
brand | String | The brand of the product |
color | String | The color of the product |
campaignstartdate | String | Campaign start date. YYYY-MM-DD format should be used. |
campaignstopdate | String | Campaign stop date. YYYY-MM-DD format should be used. |
comparefactor | Double | Compare factor of the product. Used to calculate the comparison price |
compareunit | String | Unit for the compare factor. It will be displayed as the comaprison price unit |
comparisonprice | String | The already calculated comparison price. Send both the price and unit as it should be displayed. |
corp | String | The corporation that owns the brand of the product |
countryoforigin | String | The country of origin of the product |
depth | String | The depth measurement of the product |
diameter | String | The diameter measurement of the prodct |
discountpercent | Double | The products discount, in percent. Should be used in campaigns |
discountsum | Double | The product discount, in monetary units. Should be used in campaigns |
effect | String | The power consumption of the product |
elearning | String | URL to a website that explains more about the product. |
from | String |
height | String | The height measurement of the product |
infolong | String | A more detailed description of the product. Recomended length is 200 - 400 characters. Supports line breaks |
infoshort | String | A short description of the product that highlights specific characteristics or differenses to similar products. Recomended length is 20 - 50 characters. |
ingredients | String | Ingredients used in the product |
inventory | String | Information used during inventory and ordering of the product |
keywords | String | Keywords used while searching for the product. These words usually are not available in the product text description, e.g. misspelled words or synonyms |
lastupdated | String | The date when the product information was last updated |
length | String | The length measurement of the prodct |
model | String | Model name of the product |
multi | Integer | The amount of items in a multi offer |
multi2 | Integer | Used in X for Y promotions where the value corresponds to Y. |
packsize | Integer | The number of products in i multipack. |
page | String | The page number where the product appeared in advertising material |
productname | String | The name of the product. Recomended length is 10 - 20 characters |
properties | String | Describes qualities, attributes or distinctive features of the product, eg. characteristic attributes such as the density or strength of a material |
refund | Double | The monetary refund for the product |
salespackageunit | String | The unit in which the product is sold. Used if the unit differs from the products "unit" value. |
salespackageunitbefore | String | Used to store the original 'sales package unit' if it is changed for a campaign |
salesrule | Integer | Used to control behavior in dynamic templates, mostly in campaigns. Send one of the values 1 - 16 |
salesruleb | Integer | Used to control behavior in dynamic templates, mostly in campaigns. Send one of the values 1 - 17 |
salesrulec | Integer | Used to control behavior in dynamic templates, mostly in campaigns. Send one of the values 1 - 15 |
salesruled | Integer | Used to control behavior in dynamic templates, mostly in campaigns. Send one of the values 1 - 15 |
salong | String | A longer selling text. Recomended length is 200 - 400 characters |
sashort | String | A short selling text, e.g. a pay off text. Recomended length is 20 - 50 characters |
seals | String | One of six fields used for enviromental symbols, fair trade symbols and general pictograms. Recomended length for text in this field is 10 - 20 characters. |
seals2 | String | One of six fields used for enviromental symbols, fair trade symbols and general pictograms. Recomended length for text in this field is 10 - 20 characters. |
seals3 | String | One of six fields used for enviromental symbols, fair trade symbols and general pictograms. Recomended length for text in this field is 10 - 20 characters. |
seals4 | String | One of six fields used for enviromental symbols, fair trade symbols and general pictograms. Recomended length for text in this field is 10 - 20 characters. |
seals5 | String | One of six fields used for enviromental symbols, fair trade symbols and general pictograms. Recomended length for text in this field is 10 - 20 characters. |
seals6 | String | One of six fields used for enviromental symbols, fair trade symbols and general pictograms. Recomended length for text in this field is 10 - 20 characters. |
spec | String | The technical specifications of the product |
subbrand | String | The second brand of the product, if such exists |
target | String | The target audience of the product |
techname | String | The technical name of the product |
treatment | String | Recommendations on how to treat the product after purchase. Recomended length is 200 - 400 characters |
unit | String | Describes the unit used in conjunction with 'amount' |
videourl | String | Used with digital signage. The URL of a video clip to use |
volume | String | The volume measurement of the product |
warranty | String | Information about the warranty of the product |
weight | String | The weight measurement of the product |
width | String | The width measurement of the product |
price | Double | The price of the product |
pricebefore | Double | The regular price of the product. This is automatically set by Shoppa if a campaign price is available |
pricecombined | Double | The price of a package deal |
pricelowest | Double | Lowest price of the product within 30 days of the campaign period. Used in purpose of the EU price information law |
pricerecommended | Double | The recommended price of the product |
priceto | Double | The upper limit of the price range of the product, if one exists |
text1 | String |
text2 | String |
text3 | String |
text4 | String |
text5 | String |
text6 | String |
text7 | String |
text8 | String |
text9 | String |
text10 | String |
text11 | String |
text12 | String |
text13 | String |
text14 | String |
text15 | String |
text16 | String |
text17 | String |
text18 | String |
text19 | String |
text20 | String |
text21 | String |
text22 | String |
text23 | String |
text24 | String |
text25 | String |
text26 | String |
text27 | String |
text28 | String |
text29 | String |
text30 | String |
This describes Product Group schema version 1.1.
Product groups is used for creating a hierarchy of products. It makes it easier for the users to do the search by brand or by product type. Much like pricelists, product groups are not inherited along the customer tree automatically, only stores that subscribe to the the product groups can see them.
Managing the product group subscriptions cannot currently be done through the API, it needs to be done through Mediablob.
Subscribing to product groups is all or nothing, the store either has access to the full set of product groups, or none at all.
Use the function call UploadProductGroupsXml to upload your product group xml.
The product groups are a hierarchy where each group can contain a number of subgroups, which in turn can have their own subgroups, etc. Each group must have its own unique ID. Shoppa places no particular restrictions on these ID:s, so we recommend that you mirror existing ID:s in whichever system you are using. Each group must also contain at least one text element, specifiying the name of the group. The group names can be specified by language, so that different users can have different group names, but bear in mind that the group structure and its contents will be the same.
The full definition of the product groups is done in two parts: first the structure is defined as per above, and then the products are assigned to their groups using the groups ID. Note that a product can belong to multiple groups.
The group structure cannot be edited. If a change is required you need to send the entire structure again. Note that products can still be added to groups without having to resend the entire structure.
The documentation is based on FreeImage version 3.18.0
RGB – Indexed and 8 bits (per channel).
Supports transparency RGB – Indexed
RGB / CMYK / Grayscale Recommended format for product images that don’t need transparency and other photos.
RGB – Indexed, 8 bits and 16 bits (per channel) Grayscale – 8 bits and 16 bits (per channel)
Recommended format for graphics, logotypes and product images that need transparency.
RGB – 8 bits and 16 bits (per channel) , supports transparency CMYK – 8 bits (per channel).
The same image will be used between multiple print formats in Shoppa. To ensure that the image works in all formats, we advise you to use an image resolution that works in the largest format you will print from Shoppa.
We recommend using at least 150 PPI for your images to ensure a good quality for printing. The area of the image box in Shoppa will determine what pixel dimensions are needed.
If the received XML-messages are malformed, or something goes wrong during processing of the message, an error message will be returned by our integration service. This document covers the most common error messages. Unexpected faults might produce unknown exceptions which are not covered by this document.
Error messages are reported in one of two ways: as XML or as plain strings. Problems with file contents are generally reported as XML, while other problems, such as authentication and connectivity issues are reported as strings. Error messages are contained in the <UploadProductXmlResult>-tag.
Example of XML-reported error; trying to add a product that does not exist to a campaign:
Example of string-reported error; wrong password was used:
The picture at the specified URL could not be retrieved. The reason is stated in the error text. Here are some example error texts:
The picture at '*' could not be retrieved. Reason: The remote server returned an error: (404) Not Found.
The picture at '*' could not be retrieved. Reason: Invalid URI: The format of the URI could not be determined.
The picture at '*' could not be retrieved. Reason: Byte array for GUID must be exactly 16 bytes long.
The picture at '*' could not be retrieved. Reason: Unable to read data from the transport connection: The connection was closed.
The picture at '*' could not be retrieved. Reason: Exception has been thrown by the target of an invocation.
The picture at '*' could not be retrieved. Reason: Lost connection to MySQL server during query
The picture at '*' could not be retrieved. Reason: Lost connection to backend server.
The picture at '*' could not be retrieved. Reason: Content-Disposition and Content-Type is missing and no file extension found in URI.
Recommended actions:
The remote server returned an error: (404) Not Found.: Verify that the URL is working and is reachable by our service.
Lost connection to MySQL server during query: Our service is not responding properly. Wait a few minutes and try again.
Lost connection to backend server.: Our service is not responding properly. Wait a few minutes and try again.
Content-Disposition and Content-Type is missing and no file extension found in URI.: Add missing meta-data to images, or add extensions to the URL.
Example XML excerpt:
Error text: "The supplied picture hashcode (*) does not match any known Mediablob picture"
The hashcode doesn't match any picture in Mediablob.
Recommended action: Make sure the picture is uploaded before trying to assign it to a product.
Example XML excerpt:
Error text: "Product does not exist in Mediablob"
You're trying to include a non-existing product in a campaign or price list.
Recommended action: Make sure the product is created before adding it to campaigns/price lists.
Example XML excerpt:
Error text: "Product does not exist"
You’re trying to delete a product that does not exist, or add a product that does not exist to a product group.
Recommended actions:
Deleting a product: The product is already deleted, or never existed. If possible, revise your integration system to avoid deleting already deleted products.
Adding to product group: Make sure the product is created before adding it to product groups.
Example XML excerpt (campaign/price list):
Example XML excerpt (product group):
Error text: "Product is a duplicate"
The product appears twice in a campaign or price list.
Recommended action: If possible, revise your integration system to avoid sending the same product twice or more in the same context (same campaign, product import, etc.).
Example XML excerpt:
Error text: "Failed to Save the product"
The product could not be saved, probably because of something that happened serverside.
Recommended action: Wait a while and resend your data.
Example XML excerpt:
Error text: "Found 2 products"
When trying to add a product to a product group, two products with the same code were found.
Recommended action: Resolve the conflict, or use a different code to add the product to the product group.
Example XML excerpt:
Error text: "Product has duplicates in the Xml file. The first copy of the product is saved."
The same product appears multiple times in a product import. Only the first appearance of the product is used, the other ones are discarded.
Recommended action: If possible, revise your integration system to avoid sending the same product twice or more in the same context (same campaign, product import, etc.).
Example XML excerpt:
Error text: "The product already belongs to another supplier."
You are trying to modify, or superimpose a value on, a code on a product that does not belong to the customer node you are integrating to. E.g. a store cannot change a code on a product that is owned by their HQ.
Recommended action: If possible, revise your integration system to not attempt to modify codes on lower levels in the customer hierarchy than the product is created on.
Example XML excerpt:
Error text: Found existing product in database using the same product code: CodeType '*', Value '*'. Product codes must be unique.
You are trying to assign a code to a product, but the code is already used on another product in Mediablob.
Recommended action: If possible, revise your integration system to avoid this behaviour.
Example XML excerpt:
Error text: Found duplicate code: CodeType '*', Value '*'. Product codes must be unique.
You are trying to assign the same code to multiple products within the same file.
Recommended action: If possible, revise your integration system to avoid this behaviour.
Example XML excerpt:
Error text: "User is not authenticated."
The authentication provided in the SOAP-object is not valid.
Recommended action: Verify that you are using the correct login information.
Error text: "Either uri or keyword MUST be set on a product picture."
There is a picture tag that lacks 'uri', 'hashCode' and 'md5' attributes. One of them must be present to successfully reference a picture.
Recommended action: If possible, revise your integration system to avoid this behaviour.
Error text: "Object reference not set to an instance of an object."
The imported XML does not contain any information.
Example of imported XML:
Recommended action: If possible, revise your integration system to avoid sending anything if there is no data to send.
Error text: "Failed to save picture '*'. The picture might be corrupt, try uploading the picture again or use another picture."
Something went wrong when uploading one or more pictures. Several instances can be present in the same response.
Recommended action: Try uploading the picture again.
Example:
Error text: "*. Line *, position *."
There is a syntax error in the imported XML. This is typically caused by unescaped special characters: '&', '<' and '>'. See the encoding section for more details.
Recommended action: Make sure you are encoding special characters correctly: once to get them into the import XML and then once again to get them into the SOAP-object.
Example:
Error text: "Guid *"
You have done too many revisions and the version number has gone out of bounds.
Recommended action: Contact Shoppa.
Example:
Error text: "Line: *, Position: * "*""
The imported XML does not match the XML-schema.
Recommended action: Adjust the generation of the XML content according to the given reason.
Example:
Error text: "Deadlock found when trying to get lock; try restarting transaction"
Something went wrong serverside.
Recommended action: Wait a while and resend your data.
Error text: "Connection must be opened."
Something went wrong serverside.
Recommended action: Wait a while and resend your data.
Error text: "Lost connection to MySQL server during query"
Something went wrong serverside.
Recommended action: Wait a while and resend your data.
Error text: "failed to create new session"
Something went wrong serverside.
Recommended action: Wait a while and resend your data.
Error text: "Exception has been thrown by the target of an invocation."
Something went wrong serverside.
Recommended action: Wait a while and resend your data.
Error text: "Lost connection to backend server."
Something went wrong serverside.
Recommended action: Wait a while and resend your data.
Error text: "An exception occured that could not be fully serialized: Exception has been thrown by the target of an invocation."
Something went wrong serverside.
Recommended action: Wait a while and resend your data.
