SheetMusicDirect.com Digital Retailer API

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

  1. Register as a user on the SMD website.
  2. Send an email to technical.support@sheetmusicdirect.com when you have registered.
  3. 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:

  1. Sell prints and online access to our range of over 20,000 pieces of digital sheet music.
  2. Create, read, update and cancel orders and remaining prints for your customers.
  3. Get details of our new and existing catalogue items, including prices, arrangements and other product details
  4. 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:

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

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.

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:

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

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.

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:

<?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:

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:

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:

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:

<?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:

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:

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

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