SheetMusicDirect.com Digital Retailer API

Viewer: Sibelius Cloud Publishing (SCP)


System Requirements | Front end implementation | Preview | View full score | Register print | Completion Checklist | Legacy API documentation | Register purchase (DEPRECATED)

Introduction

These endpoints enable you to display interactive previews, display post-purchase full scores and register prints via Sibelius Cloud Publishing.

Disclaimer: This API is subject to revision in accordance with changes to the Avid SCP API.

Known issues

The last release of SCP introduced a bug for Internet Explorer which is preventing users from printing full scores. Avid are aware of the issue and are investigating.

Maximising (full screen) does not work in Internet Explorer. This issue is in Avid's backlog.

For Firefox only, SCP will not render in a Twitter bootstrap modal or in a jQuery tab when it is not in the primary tab.

To workaround the above Firefox modal / jQuery issue, setting iframe src on the client side with Javascript is recommended.

Overview

There are three principal endpoints:

  1. /preview
  2. /view (requires score to have been purchased - see orders/create)
  3. /registerprint

The /registerpurchase endpoint is now deprecated. Please use the orders/create endpoint.

Rendering Scores

To render scores in your website:

  1. embed an iframe in your product and post-purchase pages
  2. make a request to this API for a URI
  3. set the source of that iframe to the URI received

When printing, you will need to make a JS client-side call to the RegisterPrint endpoint.

Please do not store any URLs returned by this API. When you need a URL, please hit the relevant endpoint.

End user system requirements

It should be noted that only the following browsers are supported:

PC

Macintosh

iOS and Android users

These platforms are not currently supported. At the time of writing, though a score may be rendered on these platforms via SCP (best with iOS8+), bugs with printing prevent us advocating SCP implementation. Music Sales is in ongoing dialogue and collaboration with Avid and will advise as and when this situation changes.

Front-end implementation

Suggested iframe dimensions: 800px high (see below)

Sample <iframe> html

<style>
	.container {
	height: auto;
	margin: 0 auto;
	}

	.iframe {
	border: solid #C9C9C9 1px; 
	width: 567px;
	overflow: hidden;
	height: 800px; /* height to width ratio is approximately 1.41 */
	}

<style>

<iframe id="ifScore" name="ifScore" src="[UrlReplacedAtRuntime]" class="iframe" clientidmode="Static" allowfullscreen seamless="seamless" scrolling="no"><iframe>

Preview (HTTP GET request)

https://api.sheetmusicdirect.com/viewer/scp/preview

Endpoint security signature: "preview[your key][product ID]"

Returns an SCP preview URL for a given score. This endpoint takes key and product ID as parameters. It returns a JSON object containing HTTP status code and, where successful, a URL to set as src for the <iframe> in your product page.

Please note that printing in preview mode is no longer permitted.

Example query:

	https://api.sheetmusicdirect.com/viewer/scp/preview?key=[YourKeyHere]&productId=[ProductIdHere]

Example OK response:

	{
		"status":"200",
		"message":"Success",
		"viewerUrl":"https://publishing.sibelius.com:80/viewer/randomstring"
	}

Example credentials error response:

	{
		"status":"401",
		"message":"Authorization failed.",
		"viewerUrl":null
	}

Example product not found error response:

	{
		"status":"404",
		"message":"Product not found.",
		"viewerUrl":null
	}

View (HTTP GET Request)

https://api.sheetmusicdirect.com/viewer/scp/view

Endpoint security signature: "view[your key][your order ID][product ID]"

This endpoint returns an SCP view full score URL for a given score. It takes key, retailer order ID and Sheetmusicdirect product ID as parameters. It will return a JSON object containing HTTP status code and URL to set as iframe source in post-purchase “print score” page.

Example query:

	https://api.sheetmusicdirect.com/viewer/scp/view?key=[YourKeyHere]&retailerOrderId=[YourOrderIdHere]&productId=[ProductIdHere]

Example OK response:

	{
		"status":"200",
		"message":"Success",
		"viewerUrl":"https://publishing.sibelius.com:80/viewer/randomstring"
	}

Example credentials error response:

	{
		"status":"401",
		"message":"Authorization failed.",
		"viewerUrl":null
	}

Example order not found error response:

	{
		"status":"404",
		"message":"order not found.",
		"viewerUrl":null
	}

Registering prints (HTTP PUT request)

Endpoint security signature: "registerprint[your key][your order ID][product ID]"

Please note that implementing this endpoint is a requirement for your account to be in good standing.

1. Embed the following Javascript in your post-purchase print / view full score page:

	var printCount = [printsRemaining];

	window.addEventListener('message', function (event) {
		switch (event.data) {
		case 'scpDialogPrintApprove':
			var xhr = new XMLHttpRequest();
			xhr.onreadystatechange = function () {
				if (xhr.readyState == 4 && xhr.status == 200) {
					printCount -= 1;
	
					// following requires remaining print count page element with ID of 'printsRemaining'
					document.getElementById('printsRemaining').innerHTML = printCount.toString();

					var result = JSON.parse(xhr.response);
					document.getElementById('[YourIframeIdHere]').src = result.viewerUrl;
				}
			}

			xhr.open("PUT",
				"https://api.sheetmusicdirect.com/viewer/scp/registerPrint?key=[yourKeyHere]&retailerOrderId=[yourOrderId]&productId=[productId]", true);

			xhr.setRequestHeader("Authorization", "[authorisation]");
			xhr.send();

			break;
		default:
			break;
		}
	}, false);

2. replace parameters in square brackets above at run time.

The put command above will return a new URL. This should be used to replace the src of your iframe. If a customer has now printed all copies of the score they purchased, the returned viewer instance will have the print icon disabled.

Completion checklist

  1. Service credentials obtained
  2. Able to preview a score
  3. Able to register a purchase using the orders/create endpoint
  4. Able to view a full score
  5. Able to register a print
  6. When viewing a purchased score that has been printed, further printing is disallowed.

Register purchase (HTTP PUT request) - DEPRECATED

https://api.sheetmusicdirect.com/viewer/scp/registerpurchase

IMPORTANT: Please note that as of October 2015, this endpoint is deprecated. It should only be used in conjunction with the legacy API. We encourage all users to use the new orders/create endpoint.

This endpoint will be decommissioned in Q4 2016.

Endpoint security signature: registerpurchase[your key][your order ID][product ID]

Please note that this endpoint does not replace the CreateOrder endpoint in the legacy API. This endpoint is supplemental to the legacy API CreateOrder endpoint. You will need to call CreateOrder to ensure user purchases are correctly logged in our system. A call to /registerpurchase is required to enable full score paging and printing via SCP.

This endpoint should be called when completing your user purchase process, for each score they have purchased. It takes key, retailer order ID, Sheetmusicdirect product ID and, optionally, a license string as parameters. It returns a JSON object containing a HTTP status code and URL to set as iframe source in post-purchase “print score” page. There is no need to store this URL - simply call the /view endpoint described below.

A license string is a short piece of text describing the purchase. It is embedded in the footer of every page of the purchased score. For example:

Supplied by [Your company name here] for [your customer name here]. Order number [your order number]. Copies purchased: [number of copies purchased].

- where the square brackets and their contents above are replaced with your data at runtime.

Please note: this parameter must be URL encoded. Spaces should be encoded as "%20", not "+".

If you do not provide a license string, one will be created for you. It is not currently possible to update a license string once it has been created.

License strings will be generated automatically on first access for all your customer's purchases which pre-date the release of this API.

Example request:

	https://api.sheetmusicdirect.com/viewer/scp/registerpurchase?key=[YourKeyHere]&retailerOrderId=[YourOrderIdHere]&productId=[ProductIdHere]&licenseString=[UrlEncodedLicenseStringHere]