A Linux/Mac OS X Command Line Interface to AffiliateWindow David Walker, Data Management & Warehousing, January 2010 Introduction Affiliate Window offer a tracking and management solutions for maintaining an affiliate program. This works by directing sales to a merchant from an affiliates’ website. In exchange for displaying the merchants’ advertising the affiliate receives commission for sales that originate from the affiliate site. Affiliate Window (http://www.affiliatewindow.com) are one of the market leaders in providing a tracking and management solution. In order to exchange information between merchant and the affiliate there is an API for exchange of data via XML and SOAP over HTTP(S). AffiliateWindow provide a comprehensive description of the API1 to their clients and a PHP example2,3 on how to access this information. This example is very powerful for those organisations that have PHP development resources and is very easy to integrate with PHP based websites however there are limited resources for those who may wish to use other development tools,4 test file structures from the command line, store requests and responses for audit purposes, etc. This document describes a way to use the interface from a Linux or Mac OS X command line. Pre-‐Requisites In order to use this script the Linux server must have curl installed (available on Debian based systems with “apt-‐get install curl” and on RedHat based systems with “rpm –Uvh curl” or “yum install curl”. Mac OS X 10.6 (Snow Leopard) and potentially earlier versions have curl pre-‐installed so no further installation is required. In addition to the software a username and password are required. These are available from AffiliateWindow. It is also useful to have a copy of the API to hand. 1 http://www.affiliatewindow.com/documents/affiliates/documentation/webservices/affiliateservice/Affiliateservice_API_v3.pdf (requires login) 2 http://www.affiliatewindow.com/downloads/api.client.zip (requires login) 3 For those looking for further information of the PHP packages required for Linux will need php and php-‐soap. If these are installed with apt-‐get, yum or rpm then the remaining dependencies will automatically be installed 4 Whilst researching this note a version of the API written in C# was found at http://awin.codeplex.com/
The Scripts There are two files. The first, request.xml, contains the request in XML format as per the API. The second, request.sh, reads request.xml and writes response.xml in the current working directory. Debugging can be assisted by changing the line “curl ” to be “curl –-‐verbose ”. In this example we are fetching affiliate transaction data using the example from the API5. <?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.affiliatewindow.com/"> <SOAP-ENV:Header> <ns1:UserAuthentication> SOAP-ENV:mustUnderstand="1" SOAP-ENV:actor=http://api.affiliatewindow.com/ <ns1:iId>YOUR_USERNAME_HERE</ns1:iId> <ns1:sPassword>YOUR_PASSWORD_HERE</ns1:sPassword> <ns1:sType>affiliate</ns1:sType> </ns1:UserAuthentication> <ns1:getQuota> SOAP-ENV:mustUnderstand="1" SOAP-ENV:actor=http://api.affiliatewindow.com/ True </ns1:getQuota> </SOAP-ENV:Header> <SOAP-ENV:Body> <ns1:getTransactionList> <ns1:dStartDate>2009-12-01T00:00:00</ns1:dStartDate> <ns1:dEndDate>2009-12-31T23:59:59</ns1:dEndDate> <ns1:sDateType>transaction</ns1:sDateType> </ns1:getTransactionList> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Figure 1 - request.xml Since we are fetching affiliate data from the version 3 API the correct URL is to call is http://api.affiliatewindow.com/v3/AffiliateService. To fetch merchant data the URL is http://api.affiliatewindow.com/v3/MerchantService. Note that the path (v3/AffiliateService and v3/MerchantService) is case sensitive. 5 The namespace setting “xmlns:xsd=http://www.w3.org/2001/XMLSchema” also appears in the example but it is not used by PHP example code and was not seen in the wireshark trace file.
#!/bin/bash curl --user YOUR_USERNAME_HERE:YOUR_PASSWORD_HERE --data @request.xml -H "Content-Type: application/soap+xml" --output response.xml http://api.affiliatewindow.com/v3/AffiliateService Figure 2 - request.sh (curl version) The curl command line can have many options. In this example the important things to note are: • The @ before the data file that instructs curl not to escape the payload data. • -‐H “ContentType:” adds a header that is essential for the input to be treated as a SOAP request by the server. It is also possible to use the wget command6 on Linux systems: #!/bin/bash wget --http-user=“YOUR_USERNAME_HERE” --http-passwd=“YOUR_PASSWORD_HERE” --header=“Content-Type: application/soap+xml” --post-file=“request.xml” --output-document=“response.xml” http://api.affiliatewindow.com/v3/AffiliateServiceFigure 3 - request.sh (wget version) Debugging can be added by changing “wget ” to “wget -‐-‐debug ”. Note that these scripts have only been tested with version 3 of the API and this may change in the future with new releases. Background Research It took some time to make this work. In the end WireShark7 was run to packet sniff a working PHP version of the code. The important aspect of making this work appears to be the content type of application/soap+xml in the header. 6 Available on Debian based systems with “apt-‐get install wget” and on RedHat based systems with “rpm –Uvh wget” or “yum install wget” 7 http://www.wireshark.org/