Legacy API documentation
IMPORTANT
The legacy API will be decommissioned in Q4 2016. All endpoints below should now be considered deprecated and have been transferred to the new White Label API. All new users should use the new API endpoints only. The information
below is provided for the use of existing legacy API users only.
Last updated: October 30th, 2015
Update summary: this is version 1.6.1 of this (Legacy API) documentation. Documentation will no longer be distributed via email. Removed references to Sibelius Scorch and deprecated appropriate endpoints.
Intended Audience
This document is intended for web developers. Experience with consuming web
services on your development platform will be useful. Intermediate level knowledge
of HTML and programming experience is also assumed.
Method call examples are given in SOAP.
Getting Started
- Register as a user on the SMD website.
- Send an email to technical.support@sheetmusicdirect.com when you have registered.
- We will then amend your user status so you can start making calls to the API.
NB your user name and password will be used to confirm Sheetmusicdirect.com (hereafter SMD) API transactions, so please ensure that these details are kept safe.
Legal considerations
The nature of sheet music copyright is such that a vendor’s right to sell a piece of sheet music is restricted dependent on where in the world the potential customer lives.
It is therefore the responsibility of all API consumers to place appropriate checks within their website to ensure that these restrictions are observed.
Failure to comply with this requirement may result in the immediate and permanent withdrawal of access to the SMD API.
Sheetmusicdirect will not be liable for any loss of earnings resulting from any such withdrawal.
Please note that the API catalogue update does not consider product withdrawal from
the SMD catalogue. In order to comply with the requirements of maintaining a current
catalogue, API customer will therefore occasionally be required to manually remove
products displayed on their site. In such events, API customers will be notified via
email.
What can I use the SMD API for?
You can use the SMD API to:
- Sell prints and online access to our range of over 20,000 pieces of digital sheet music.
- Create, read, update and cancel orders and remaining prints for your customers.
- Get details of our new and existing catalogue items, including prices, arrangements and other product details
- Enable paging and full midi playback for your customers purchased scores - DEPRECATED - Use SCP API
Please note that scores embedded in your web pages are rendered from the SMD server.
You cannot use the SMD API to:
- Sell a piece of sheet music without providing the purchaser's ISO country code(see Appendix 3)
Programming examples – getting connected
The API is located at http://dw.sheetmusicdirect.com/SmdWebSvc.asmx.
Establish a connection to the API as is appropriate for your platform. We have tried to provide guidance for as many platforms as possible.
ASP.Net / Visual Studio
Add a web reference to the project and connect to the above URL. We suggest renaming the reference to be “SheetmusicdirectAPI”.
We further suggest creating a wrapper class to access the API methods. Once you have created the reference, add a using directive to the class which will make the API calls.
PHP
If using PHP 5.0 use the php_soap extension. If using an earlier version, NuSOAP or
similar will be required. (See Appendix 1 for a code example.)
JSP/Java
See http://www.netbeans.org/kb/55/websvc-jax-ws.html.
Perl
See http://aspn.activestate.com/ASPN/WebServices/SWSAPI/perltut
RubyOnRails
See http://wiki.rubyonrails.org/rails/pages/How+To+Consume+.NET+WebServices.
For other languages, please consult your user documentation or search the web for API consumption tutorials.
Methods available via the SMD API
- CancelOrder - DEPRECATED - Use White Label API
- CancelOrderItem - DEPRECATED - Use White Label API
- CheckProductHasBeenPurchased - DISCONTINUED - Data available through other endpoints
- CreateOrder - DEPRECATED - Use White Label API
- GetCatalogueItemAvailableCountries_Dataset - DISCONTINUED - Data available through other endpoints
- GetCatalogueItemContributors_Dataset
- GetCatalogueItemGenres_Dataset
- GetOrders_Dataset - - DEPRECATED - Use White Label API
- GetOrderDetails_Dataset - DEPRECATED - Use White Label API
- GetAllProductsOrderedByUser_Dataset
- GetOrderItemDetails_Dataset - DISCONTINUED - Data available through other endpoints
- ListCatalogueItemDetails_Dataset
- ListCatalogueItems_Dataset
- UpdateOrderStatus - DEPRECATED - Use White Label API
- AuthoriseScorePaging - DEPRECATED - Use White Label API
- UpdateOrderItemPrintsRemaining - DEPRECATED - Use White Label API
Getting new product information from the catalogue
We strongly suggest you automate this procedure to ensure that your database is kept up to date with our latest sheet music releases.
Use the ListCatalogueItems method to get the latest product data as shown below.
<![CDATA[
Soap request:<br />
POST /SmdWebSvc.asmx HTTP/1.1<br />
Host: localhost<br />
Content-Type: text/xml; charset=utf-8<br />
Content-Length: length<br />
SOAPAction: "http://dw.sheetmusicdirect.com/ListCatalogueItems_Dataset"<br />
<?xml version="1.0" encoding="utf-8"?><br />
<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:Body>
<ListCatalogueItems_Dataset xmlns="http://dw.sheetmusicdirect.com">
<username>string</username>
<password>string</password>
<startDate>dateTime</startDate>
<endDate>dateTime</endDate>
</ListCatalogueItems_Dataset>
</soap:Body>
</soap:Envelope>
]]>
NB if you are using ASP.Net, you can cast the XML returned by this method to a
DataSet, as with any method offered by this service which has a call suffix of
_DataSet. Users of other platforms should parse the XML using other suitable
techniques.
Sample response:
<![CDATA[
<?xml version="1.0" encoding="utf-8" ?>
- <DataSet xmlns="http://dw.sheetmusicdirect.com">
- <xs:schema id="smdCatalogue" xmlns="" xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
- <xs:element name="smdCatalogue" msdata:IsDataSet="true"
msdata:UseCurrentLocale="true">
- <xs:complexType>
- <xs:choice minOccurs="0" maxOccurs="unbounded">
- <xs:element name="smdProduct">
- <xs:complexType>
- <xs:sequence>
<xs:element name="smd_product_id" type="xs:int" minOccurs="0" />
<xs:element name="smd_song_id" type="xs:int" minOccurs="0" />
<xs:element name="smd_title" type="xs:string" minOccurs="0" />
<xs:element name="smd_catalogue_reference" type="xs:string" minOccurs="0" />
<xs:element name="smd_number_of_pages" type="xs:int" minOccurs="0" />
<xs:element name="smd_price" type="xs:decimal" minOccurs="0" />
<xs:element name="smd_arrangement" type="xs:string" minOccurs="0" />
<xs:element name="Genres" type="xs:string" minOccurs="0" />
<xs:element name="Artist" type="xs:string" minOccurs="0" />
<xs:element name="smd_available_countries" type="xs:string" minOccurs="0" />
<xs:element name="smd_release_date" type="xs:dateTime" minOccurs="0" />
<xs:element name="smd_difficulty" type="xs:string" minOccurs="0" />
<xs:element name="smd_keystage" type="xs:string" minOccurs="0" />
<xs:element name="smd_language" type="xs:string" minOccurs="0" />
<xs:element name="product_preview_image" type="xs:string" minOccurs="0" />
<xs:element name="product_cover_art_small" type="xs:string" minOccurs="0" />
<xs:element name="product_cover_art_large" type="xs:string" minOccurs="0" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:choice>
</xs:complexType>
</xs:element>
</xs:schema>
- <diffgr:diffgram xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"
xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1">
- <smdCatalogue xmlns="">
<smdProduct diffgr:id="smdProduct12" msdata:rowOrder="11">
<smd_product_id>38598</smd_product_id>
<smd_song_id>40516</smd_song_id>
<smd_title>David Bowie: Quicksand</smd_title>
<smd_catalogue_reference>smd_113877</smd_catalogue_reference>
<smd_filename>smd_113877.sco</smd_filename>
<smd_number_of_pages>13</smd_number_of_pages>
<smd_price>2.2500</smd_price>
<smd_arrangement>PVG::Piano, Vocal & Guitar</smd_arrangement>
<Genres>Rock, Pop</Genres>
<Artist>Bowie, David</Artist>
<smd_available_countries>AD, AE, AF, AG, AI, AL, AM, AN, AO, AQ, AR, AS, AT, AU, AW,
AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BM, BN, BO, BR, BS, BT, BV, BW, BY, BZ, CC,
CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CS, CU, CV, CX, CY, CZ, DE, DJ, DK, DM,
DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GH,
GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL,
IN, IO, IQ, IR, IS, IT, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA,
LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, MG, MH, MK, ML, MM, MN, MO, MP,
MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU,
NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PT, PW, PY, QA, RE, RO, RU, RW, SA,
SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, ST, SV, SY, SZ, TC, TD, TF,
TG, TH, TJ, TK, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UY, UZ, VA, VC, VE, VG, VI,
VN, VU, WF, WS, YE, YT, ZA, ZM, ZW</smd_available_countries>
<smd_release_date>2007-09-03T00:00:00+01:00</smd_release_date>
<smd_difficulty />
<smd_keystage />
<smd_language>English</smd_language>
</smdProduct>
</smdCatalogue>
</diffgr:diffgram>
</DataSet>
]]>
Creating an order
The CreateOrder request is used to place an order with the SMD API.
Requires username, password, your customer’s user ID and order ID as stored in your database, SMD product ID, number of copied purchased, order status (see Appendix) and ISO country code (see appendix 3)
The retailerClientId needs to be a GUID. Order status should be set to 4.
<![CDATA[
Sample call:
SOAP:
POST /SmdWebSvc.asmx HTTP/1.1
Host: localhost
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://dw.sheetmusicdirect.com/CreateOrder"
<?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:Body>
<CreateOrder xmlns="http://dw.sheetmusicdirect.com">
<username>string</username>
<password>string</password>
<retailerClientId>string</retailerClientId>
<retailerOrderNumber>string</retailerOrderNumber>
<productId>string</productId>
<copiesPurchased>int</copiesPurchased>
<orderStatus>int</orderStatus>
<orderCountryCode>string</orderCountryCode>
</CreateOrder>
</soap:Body>
</soap:Envelope>
Sample response:
<?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:Body>
<CreateOrderResponse xmlns="http://dw.sheetmusicdirect.com">
<CreateOrderResult> OK: order was placed with SMD web
service.</CreateOrderResult>
</CreateOrderResponse>
</soap:Body>
</soap:Envelope>
Alternative possible responses:
(some XML omitted for brevity)
<CreateOrderResult> Error - the following required fields were not supplied or
contained invalid data[...]</CreateOrderResult>
]]>
Retrieving order data
The GetAllProductsOrderedByUser_Dataset method provides details of
all products ordered by your customer. Requires username, password and your
customer’s user ID.
<![CDATA[
Sample request:
POST /SmdWebSvc.asmx HTTP/1.1
Host: localhost
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://dw.sheetmusicdirect.com/GetAllProductsOrderedByUser_Dataset"
<?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:Body>
<GetAllProductsOrderedByUser_Dataset xmlns="http://dw.sheetmusicdirect.com">
<username>string</username>
<password>string</password>
<retailerClientId>string</retailerClientId>
</GetAllProductsOrderedByUser_Dataset>
</soap:Body>
</soap:Envelope>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
]]>
Sample response:
<![CDATA[
<?xml version="1.0" encoding="utf-8" ?>
- <DataSet xmlns="http://dw.sheetmusicdirect.com">
- <xs:schema id="Orders" xmlns="" xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
- <xs:element name="Orders" msdata:IsDataSet="true" msdata:UseCurrentLocale="true">
- <xs:complexType>
- <xs:choice minOccurs="0" maxOccurs="unbounded">
- <xs:element name="OrderItems">
- <xs:complexType>
- <xs:sequence>
<xs:element name="g_order_id" msdata:DataType="System.Guid, mscorlib,
Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" type="xs:string"
minOccurs="0" />
<xs:element name="date_order_created" type="xs:dateTime" minOccurs="0" />
<xs:element name="item_ordered" type="xs:string" minOccurs="0" />
<xs:element name="retailer_order_id" type="xs:string" minOccurs="0" />
<xs:element name="order_status" type="xs:short" minOccurs="0" />
<xs:element name="copies_purchased" type="xs:int" minOccurs="0" />
<xs:element name="line_item_qty_printed" type="xs:int" minOccurs="0" />
<xs:element name="prints_remaining" type="xs:int" minOccurs="0" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:choice>
</xs:complexType>
</xs:element>
</xs:schema>
- <diffgr:diffgram xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"
xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1">
- <Orders xmlns="">
- <OrderItems diffgr:id="OrderItems1" msdata:rowOrder="0">
<g_order_id>f1904b41-2a67-4aa3-a884-88093d01249e</g_order_id>
<date_order_created>2007-08-23T14:48:31.59+01:00</date_order_created>
<item_ordered>34672</item_ordered>
<retailer_order_id>6750d455-bb82-4257-992d-1d0649dd5409</retailer_order_id>
<order_status>4</order_status>
<copies_purchased>1</copies_purchased>
<line_item_qty_printed>2</line_item_qty_printed>
<prints_remaining>-1</prints_remaining>
</OrderItems>
- <OrderItems diffgr:id="OrderItems2" msdata:rowOrder="1">
<g_order_id>f1904b41-2a67-4aa3-a884-88093d01249e</g_order_id>
<date_order_created>2007-08-23T14:48:31.59+01:00</date_order_created>
<item_ordered>35623</item_ordered>
<retailer_order_id>6750d455-bb82-4257-992d-1d0649dd5409</retailer_order_id>
<order_status>4</order_status>
<copies_purchased>1</copies_purchased>
<line_item_qty_printed>1</line_item_qty_printed>
<prints_remaining>0</prints_remaining>
</OrderItems>
- <OrderItems diffgr:id="OrderItems3" msdata:rowOrder="2">
<g_order_id>269f082f-b6e3-464a-a33a-dcb97d266708</g_order_id>
<date_order_created>2007-08-23T14:30:52.903+01:00</date_order_created>
<item_ordered>35694</item_ordered>
<retailer_order_id>8e9957e1-c995-43d4-99c8-a2aabe681d6e</retailer_order_id>
<order_status>64</order_status>
<copies_purchased>1</copies_purchased>
<line_item_qty_printed>2</line_item_qty_printed>
<prints_remaining>-1</prints_remaining>
</OrderItems>
</Orders>
</diffgr:diffgram>
</DataSet>
]]>
Cancelling an order
The CancelOrder method is, logically enough, used to cancel orders. It requires
username, password and orderId.
No cancelled orders will be billed. If the order is cancelled in the month after it was placed
(i.e. after you've already been invoiced for it), you will receive a credit note in the following month.
Sample request:
<![CDATA[
POST /SmdWebSvc.asmx HTTP/1.1
Host: localhost
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://dw.sheetmusicdirect.com/CancelOrder"
<?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:Body>
<CancelOrder xmlns="http://dw.sheetmusicdirect.com">
<username>string</username>
<password>string</password>
<vendorOrderId>string</vendorOrderId>
</CancelOrder>
</soap:Body>
</soap:Envelope>
]]>
Sample response:
<![CDATA[
HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
<soap12:Body>
<CancelOrderResponse xmlns="http://dw.sheetmusicdirect.com">
<CancelOrderResult> OK: order was cancelled.</CancelOrderResult>
</CancelOrderResponse>
</soap12:Body>
</soap12:Envelope>
]]>
Cancelling an order item
The CancelOrderItem method can be used to cancel a single item within an
order. Requires username, password, your orderId and the SMD product ID.
Sample request:
<![CDATA[
POST /SmdWebSvc.asmx HTTP/1.1
Host: localhost
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://dw.sheetmusicdirect.com/CancelOrderItem"
<?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:Body>
<CancelOrderItem xmlns="http://dw.sheetmusicdirect.com">
<username>string</username>
<password>string</password>
<vendorOrderId>string</vendorOrderId>
<productId>string</productId>
</CancelOrderItem>
</soap:Body>
</soap:Envelope>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
]]>
Sample response:
<![CDATA[
<?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:Body>
<CancelOrderItemResponse xmlns="http://dw.sheetmusicdirect.com">
<CancelOrderItemResult>OK: order item was cancelled.</CancelOrderItemResult>
</CancelOrderItemResponse>
</soap:Body>
</soap:Envelope>
]]>
Updating the status of an order
The UpdateOrderStatus can be used to update the status of an order. You may use this
method if, for example, you wish to allow customers to pay offline by cheque. Once
you have created the order, use this method to set the order status to pending. When
payment has been received, use this call to amend the status again. See Appendix 2
for a list of status codes.
Sample request:
<![CDATA[
POST /SmdWebSvc.asmx HTTP/1.1
Host: localhost
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://dw.sheetmusicdirect.com/UpdateOrderStatus"
<?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:Body>
<UpdateOrderStatus xmlns="http://dw.sheetmusicdirect.com">
<username>string</username>
<password>string</password>
<retailerClientId>string</retailerClientId>
<retailerOrderNumber>string</retailerOrderNumber>
<orderStatus>int</orderStatus>
</UpdateOrderStatus>
</soap:Body>
</soap:Envelope>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
]]>
Sample response:
<![CDATA[
<?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:Body>
<UpdateOrderStatusResponse xmlns="http://dw.sheetmusicdirect.com">
<UpdateOrderStatusResult> OK: order status was updated in SMD web
service.</UpdateOrderStatusResult>
</UpdateOrderStatusResponse>
</soap:Body>
</soap:Envelope>
]]>
Allowing paging and full MIDI playback in a purchased score
Deprecated - Use SCP API
Displaying scores in a web page
Deprecated - use SCP API
Printing Scores
Deprecated - use SCP API
Appendix 1: PHP 5.0 Code Example
An example of using PHP 5.0 to consume the API and call ListCatalogueItems_Dataset.
<![CDATA[
<?php
$userName = "username";
$password = "password";
$client = new
SoapClient("http://dw.sheetmusicdirect.com/smdwebsvc.asmx?wsdl");
//Format date
$startDate = date('Y-m-d', strtotime('2008-01-01'));
$endDate = date('Y-m-d', strtotime('2008-05-01'));
$guid = “guid”
if($err)
{
die('An error occured whiles the WSDL was being accessed: '.$err);
}
//Create array of parameters
$params = array(
'username' => $userName,
'password' => $password,
'retailerClientId' => $guid );
//Call method and print result
$res = $client->GetAllProductsOrderedByUser_Dataset($params);
print_r($res);
$params2 = array(
'username' => $smdUserName,
'password' => $smdPassword,
'startDate' => $startDate,
'endDate' => $endDate);
foreach($params as $value)
{
echo $value ."<br/>";
}
echo "<br/>";
$cat = $client->ListCatalogueItems_Dataset($params2);
print_r($cat);
?>
]]>
Appendix 2: Sheetmusicdirect.com Order Status Codes
| Basket | 1 |
| SavedOrder | 2 |
| Accepted | 4 |
| Processing | 8 |
| Completed | 16 |
| Declined | 32 |
| Cancelled | 64 |
| PaymentPending | 128 |
| PartiallyReturned | 256 |
| FullyReturned | 512 |
| ChargeBackPending | 1024 |
| ChargeBackConfirmed | 2048 |
| DuplicateToVerify | 4096 |
| OrderIncomplete | 8192 |
Appendix 3: Two-letter ISO country codes
Please see Wikipedia for a list of two-letter ISO country codes
