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.

HTTPS endpoints

There are two available endpoints; one for development and testing, and the other for production use.

1. Development: https://api.test2.mediablob.com/api/xml

2. Production: https://api.mediablob.com/api/xml

REST/HTTP Developer tools

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.

1. Install the addon.

2. Open the new app from the upper right corner of Chrome.

3. Select the Method, i.e. POST and fill in the url to the endpoint

   https://api.test2.mediablob.com/api/xml.

4. Add an Authentication request header that conforms to the credentials provided by Shoppa, i.e Authentication: Basic dXNlcm5hbWU6cGFzc3dvcmQ=.

5. 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.

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

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

Legacy SOAP endpoints

There are two available endpoints; one for development and testing, and the other for production use.

1. Development: http://ws.test2.mediablob.com/services/products.asmx

2. Production: http://ws.mediablob.com/services/products.asmx

You can open the endpoint urls in a standard browser and read about the provided functions.

SOAP Developer tools

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.

1. Install the addon.

2. Browse to the wsdl-definition of the webserver at http://ws.test2.mediablob.com/services/products.asmx?WSDL.

3. Click on the Wizdler icon in the addons toolbar and select the function you want to call.

4. Rewrite the example content in the browser window.

5. Click GO to post the xml file to the service.

6. Await the service response.

Shoppa also provides C# source code for a sample application that uploads xml files to the api.

How to use the endpoints properly

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.

Requesting user access

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.

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.

UploadImage

Legacy

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

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.

The AuthHeader

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:

<AuthHeader xmlns="http://www.mediablob.com/">
  <username>demouser1</username>
  <password>Not_a_real_password</password>
  <customerId>14</customerId>
  <customerIdType>ShoppaID</customerIdType>
</AuthHeader>

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.

Encoding

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 & vinn!.

Mediablob also requires an xml declaration line at the top.

Example SOAP Request

Lets say we want to upload the following product definition:

<mediablob customerID="1143" customerIDType="ShoppaID" createDate="2018-05-12T00:00:00" schemaVersion="1.7">
  <products>
    <product id="65467-14" idType="Code1">
      <codes>
        <code name="EAN13" value="123456789012" />
      </codes>
      <texts>
        <text productName="Champagneglas" brand="Orrefors" languageCode="sv-SE" />
      </texts>
    </product>
  </products>
</mediablob>

Using the following user details:

• username: demouser1

• password: Not_a_real_password

• ShoppaID: 1143

Encoded and wrapped in a valid soap request this becomes:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <AuthHeader xmlns="http://www.mediablob.com/">
      <username>demouser1</username>
      <password>Not_a_real_password</password>
      <customerId>1132</customerId>
      <customerIdType>ShoppaID</customerIdType>
    </AuthHeader>
    <CultureHeader xmlns="http://www.mediablob.com/">
      <currentCulture>sv-SE</currentCulture>
    </CultureHeader>
  </soap:Header>
  <soap:Body>
    <UploadProductXml xmlns="http://www.mediablob.com/">
      <productXml>&lt;mediablob customerID=&quot;1143&quot; customerIDType=&quot;ShoppaID&quot; createDate=&quot;2018-05-12T00:00:00&quot; schemaVersion=&quot;1.7&quot;&gt;
  &lt;products&gt;
    &lt;product id=&quot;65467-14&quot; idType=&quot;Code1&quot;&gt;
      &lt;codes&gt;
        &lt;code name=&quot;EAN13&quot; value=&quot;123456789012&quot; /&gt;
      &lt;/codes&gt;
      &lt;texts&gt;
        &lt;text productName=&quot;Champagneglas&quot; brand=&quot;Orrefors&quot; languageCode=&quot;sv-SE&quot; /&gt;
      &lt;/texts&gt;
    &lt;/product&gt;
  &lt;/products&gt;
&lt;/mediablob&gt;</productXml>
    </UploadProductXml>
  </soap:Body>
</soap:Envelope>

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:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <UploadProductXmlResponse xmlns="http://www.mediablob.com/">
            <UploadProductXmlResult />
        </UploadProductXmlResponse>
    </soap:Body>
</soap:Envelope>

Integration user

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

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.

/api/xml

Used for uploading Shoppa XML's to the integration service bus queue

PUT https://api.mediablob.com/api/xml

Available Shoppa XML's can be found at XML structure

Headers

Request Body

23829771-e1d5-4dc3-8311-6503a38f2614

{
message: "The request is invalid."
}

{
message: "Authorization has been denied for this request."
}

Used for uploading a custom XML to the integration service

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.

Headers

Request Body

23829771-e1d5-4dc3-8311-6503a38f2614

{
message: "Authorization has been denied for this request."
}

Operation to list all uploaded XML's for the defined date

GET https://api.mediablob.com/api/xml/{date}

Headers

{
id: "80004390-0000-a900-b63f-84710c7967bb",
receivedAt: "2022-12-28T13:01:51+00:00",
fileLenght: 164,
sentBy:{
    name: "sebbewstest",
    shoppaId: 17786,
    externalId: null
},
file: "https://mbintegrationdatainttest.blob.core.windows.net/xml/2022-12-28/17786/17786/a5ff59a67806e7af3d49fb184a671c68.xml",
result: "https://api.test2.mediablob.com/api/status/80004390-0000-a900-b63f-84710c7967bb/result",
errors:[]
}

{
message: "The request is invalid."
}

{
message: "Authorization has been denied for this request."
}

/api/status

Operation to check if the XML processing is done

GET https://api.mediablob.com/api/status/{sessionId}/done

{sessionId} corresponds to the hashcode returned by a 202 Accepted response in #api-xml

true

false

Operation to get a detailed information about the XML process

GET https://api.mediablob.com/api/status/{sessionId}/result

{sessionId} corresponds to the hashcode returned by a 202 Accepted response in #api-xml

The request is still being proccessed.

/api/images

Upload images

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.

Query Parameters

Headers

Request Body

{
    // Response
}

Check if an image exists

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.

Headers

{
    // Response
}

{
    // Response
}

Find the Mediablob hashcode for an uploaded image

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.

Query Parameters

Headers

{
    // Response
}

{
    // Response
}