Affiliate service APIV3

From Wiki

Jump to: navigation, search

Contents

Introduction

The AffiliateService provides the necessary functionality to retrieve all the information about an Affiliate’s transactions and Affiliate Window merchants.

The API is built on the core open source standards of SOAP and WSDL.

To use the API to programmatically access an affiliate account you will need to build a web service client in your chosen language.

How can I access it?

Affiliates can access this service in their Darwin account. Please click on the link labelled AffiliateService API from the Links & Tools menu.

The current version of the AffiliateService is version 3. Please refer to the AffiliateService API v3 document for a technical specification on the service.

File:Affserv_usefuldocs.PNG




With the v3 of the Affiliate Window API we have changed the password you need to authenticate with. You will now need to enter a 48 character long API password hash - this can be found by clicking on Settings and then Manage API Credentionals.

Note: If there is no Affiliate API Password visible, please create a ticket from within your account and a member of the Technical Services team will generate a password for you.

By clicking on PHP API client you can download the zip file api.client.zip which contains the php scripts in order to build the webservice.

Intended Audience

This document is intended for developers who want to programmatically access Affiliate Window affiliate accounts. It assumes the reader is familiar with web services and with the programming language they will be using. It also assumes they are familiar with the affiliate aspect of the Affiliate Window system.

Updates and Version Revisions

The current version of the AffiliateService is version 3. As the service is updated, new versions will be deployed and old versions will stop being supported. They will however be left on our servers for a limited time to allow developers a smooth transition from one version to another.

Other services

ProductServeService – provides access to Affiliate Window product data to allow development of products such as the ShopWindow Toolkit.

API Overview

WSDL

The current version of the AffiliateService WSDL can be found at http://api.affiliatewindow.com/v3/AffiliateService?wsdl

User authentication

User authentication is performed by SOAP-Headers, which must be passed with every single request.

Quota

Every user has an allocated operations quota. The remaining quota is returned as a SOAP-Header, in the response of every request. The quota is specific to this service and has no relation to any quota you may have for any other Affiliate Window service.

SOAP Request Format

SOAP requests are "envelopes" of specially formatted XML data posted to a URL. You can find out more about SOAP at www.w3.org/TR/soap/. Each request must contain the following 2 parts.

Header

UserAuthentication The header must contain element required to authenticate the user.
getQuota The header can optionally contain a call to the method getQuota

Body

getClickStats Gets click stats that fall under the specified criteria
getCommissionGroup Gets the commission values for a given commission group
getImpressionStats Gets impression stats that fall under the specified criteria
getMerchant Gets the requested merchants.
getMerchantList Gets the merchants that fall under the specified criteria
getTransaction Gets the requested transactions
getTransactionList Gets the transactions that fall under the specified criteria
getTransactionProduct Gets the products associated with an affiliate transaction
getTransactionQuerys Gets the transaction query’s that fall under the specified criteria
setTransactionQuery Save a transaction query 




<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope 
           xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
           xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
           xmlns:ns1="http://api.affiliatewindow.com/">
 
<SOAP-ENV:Header>
<ns1:UserAuthentication 
           SOAP-ENV:mustUnderstand="1" 
           SOAP-ENV:actor="http://api.affiliatewindow.com">
           <ns1:iId>*****</ns1:iId>
           <ns1:sPassword>*****</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>2006-08-04T00:00:00</ns1:dStartDate>
           <ns1:dEndDate>2006-08-14T23:59:59</ns1:dEndDate>
           <ns1:sDateType>transaction</ns1:sDateType>
       </ns1:getTransactionList>
</SOAP-ENV:Body>
 
</SOAP-ENV:Envelope>

Sample SOAP request

SOAP Response Format

In response to each request the AffiliateService API will send back a SOAP response.
If getQuota was called in the request header, the remaining quota will be returned in the header of the request. 

<?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:getQuotaResponse>14951</ns1:getQuotaResponse>
</SOAP-ENV:Header>
 
<SOAP-ENV:Body>
           <ns1:getTransactionListResponse>
           <ns1:getTransactionListReturn>
           <ns1:Transaction>
           <ns1:iId>7302200</ns1:iId>
           <ns1:sStatus>declined</ns1:sStatus>
           <ns1:sDeclinedReason>Duplicate</ns1:sDeclinedReason>
           <ns1:iMerchantId>1286</ns1:iMerchantId>
           <ns1:fSaleAmount>22.6</ns1:fSaleAmount>
           <ns1:fCommissionAmount>4.52</ns1:fCommissionAmount>
           <ns1:dClickDate>2006-08-06 16:36:21</ns1:dClickDate>
           <ns1:dTransactionDate>2006-08-07 22:31:48</ns1:dTransactionDate>
           <ns1:dValidationDate>2006-08-08 17:21:13</ns1:dValidationDate>
           <ns1:aTransactionParts>
           <ns1:TransactionPart>
           <ns1:sCommissionGroupName>Default Commission</ns1:sCommissionGroupName>
           <ns1:fSaleAmount>22.6</ns1:fSaleAmount>
           <ns1:fCommissionAmount>4.52</ns1:fCommissionAmount>
           <ns1:iCommission>10</ns1:iCommission>
           <ns1:sCommissionType>percentage</ns1:sCommissionType>
           </ns1:TransactionPart>
           </ns1:aTransactionParts>
           </ns1:Transaction>
           </ns1:getTransactionListReturn>
           </ns1:getTransactionListResponse>
</SOAP-ENV:Body>
 
</SOAP-ENV:Envelope>

Sample SOAP response

API Methods

Headers

UserAuthentication
(SOAP-Header) The authentication element, has to be sent with every single request

Parameters

Element Type Required Description
ild int YES The user id
sPassword string YES The user password
sType string YES The user type


Response

none


getQuota
(SOAP-Header) Gets the remaining quota back in the response headers, with every single request

Parameters

Type Required Description
boolean YES Indicate if the quote should be returned or not

Response

Type Description
int The number of remaining operations

Requests

getCommissionGroup

Gets the commission values for a given commission group

Parameters

Element Type Required Description
iMerchantID int YES id of a merchant
sCommisionGroupCode string YES Commission Group Code

Response

Element Type Description
getCommissionGroupReturn CommissionGroup Commission Group Object

Commision Group Data Type

Element Type Description
sCommissionGroupCode string Commission Group Code
fAmount float Set amount given
fPercentage float Percentage of sale amount

getCommissionGroupList

Gets an array of commission groups for a merchant

Parameters

Element Type Required Description
iMerchantID int YES id of a merchant

Response

Element Type Description
getCommissionGroupListReturn ArrayOfCommissionGroup Array of Commission group objects

getTransactionProduct

Gets the requested merchants

Parameters

Element Type Required Description
aTransactionIds Array of Integers YES Array of transaction Ids

Response

Element Type Description
getTransactionProductReturn ArrayOfTransactionProduct Transaction and an array of their associated products

Transaction Product Data Type

Element Type Description
iTransaactionId int Transaction id
aProducts ArrayOfProducts Array of products

Product Data Type

Element Type Description
iId int Product id
sName string Unit price of product

getTransactionList

Gets the transactions that fall under the specified criteria


Parameters

Element Type Required Description
aMerchantIds Array of Integers NO Array of Merchant Ids
dStartDate dateTime YES Start date of transaction search
dEndDate dateTime YES End date of transaction search
sDateType dateType YES Which date the date range will apply to
sTransactionStatus TransactionStatus NO The transaaction status e.g. pending, confirmed
iLimit int NO Limit result set - max 1000 - default 1000
iOffset int NO Offset the results - default 0

DateType Data Type

Type Values
string transaction
validation

TransactionStatus Data Type

Type Values
transaction validation
confirmed
declined

Response

Element Type Description
getTransactionListReturn ArrayOfTransaction Array of Transaction objects
getTransactionListCountReturn RowCounts Number of rows returned/available


TransactionData Type

Element Type
iId int
sStatus TransaactionStatus
sType TransactionType
sIp string
bPaid boolean
iPaymentId int
sDeclinedReason string
iMerchantId int
fSaleAmount float
fCommissionAmount float
dClickDate dateTime
dTransaactionDate dateTime
dValidationDate dateTime
sClickRef string
sSearchSiteName string
sSearchSiteKeyword string
aTransactionParts ArrayOfTransactionPart
sExtra string


RowCounts Data Type

Element Type
iRowsReturned int
iRowsAvailable int


TransactionType Data Type

Type Values
string
normal
bonus
second tier
untracked


TransactionType Data Type

Element Type
aCommissionGroupName string
fSaleAmount float
fCommissionAmount float
iCommissionAmount float
iCommission int
sCommissionType commissionType


CommissionType Data Type

Type Values
string percentage
amount

getTransaction

Gets the requested transactions

Parameters

Element Type Required Description
aTransactionIds Array of Integers Yes The Id's of the transactions to get

Response

Element Type Description
getTransactionReturn ArrayOfTransaction Array of Transaction objects


getMerchant

Gets the requested merchants

Parameters

Element Type Required Description
aMerchantIds Array of Integers Yes The Id's of the Merchants to get

Response

Element Type Description
getMerchantReturn ArrayOfMerchant Array of Merchant objects


MerchantData Type

Element Type
iId int
sName string
sDisplayUrl string
sClickThroughUrl string
sLogoUrl string
iDetailsVersion int
sDetailsModified dateTime
iFeedVersion int
dFeedModified dateTime
sStrapline string
sDescription string
fApprovalPercentage float
fEpc float
fConversionRate float
iValidationDays float
sfAwinGrade float
aCommissionGroups ArrayOfCommissionRanges
aSectors ArrayOfMercahntSectors


CommissionRange Data Type

Element Type
sType CommissionType
fMin float
fMax float



MerchantSector Data Type

Element Type
iSectorId int
sSectorName string


getMerchantList

Gets the merchants that fall under the specified criteria

Parameters

Element Type Required Description
sRelationship relationship NO The affiliate's relationship to the merchant


Relationship Data Type

Type Value
string joined


Response

Element Type Description
getMerchantListReturn ArrayOfMerchant Array of Merchant objects


getTransactionQuerys

Gets the requested transaction queries

Note: To use any of the Transaction Query functionality it must be enabled within your account.

Parameters

Element Type Required Description
aMerchantIds ArrayOfInt NO Array of Merchant ids
aStatus ArrayOfTransactionPreStatus NO Array of status
aclickRefs Array NO Array of click refs
iOffset int NO Offset the results - default 0
iLimit int NO Limit result set - max 100 - default 100

TransactionPreStatus Data Type

Type Value
string pending
confirmed
declined


Response

Element Value Description
gettransaactionQuery ArrayOfTransactionQuerys Array of Transaction Query objects
getTransactionQueryCountReturn Rowcounts Array of integer values


TransactionQuery Data Type

Element Type
iEnquiryId int
iMerchantId int
sClickRef string
sStatus string
fAmount float
fCommission dateTime
sCustomerReference string
sReference string
sProgramName string
sDeclineReason string
sType string
sDescription string


getTransactionQuery

Sets a single transaction query

Parameters

Element Value Required Description
iEnquiryId int YES The enquiry id
iMerchatId int YES The merchant id
sClickRef String YES A customer reference
fAmount float NO The transaction amount
fCommission float NO The comission due
dDate dateTime YES The date of the transaction
sCustomerReference String NO Rereence to identify the customer
sReference string YES Reference to identify the order
sType string YES Type of transaction query
sDescription string NO Description of transaction query

Response

Element Type Description
gettransaactionQueryReturn Store Result of the set


Store Data Type

Element Type
iRowsSaved int

getClickStats

Gets the requested link click stats

Parameters

Element Type Required Description
dStartDate dateTime YES Start date of date range
dEndDate dateTime YES End date of date range
aMerchantIds ArrayOfInt NO Array of merchant ids to limit the results to
sDateType DateType YES Which date the range will apply to. Default is transaction
iOffset int NO Offset the results - default 100
iLimit int NO limit result set - max 100 - default 100

Response

Element Type Description
gettransaactionQueryReturn Store Result of the set


Click Stats Data Type

Value Type
sLinkName string
sLinkType string
sMerchantName string
iPendingCount int
fPendingValue float
fPendingCommission float
iConfirmedCount int
fConfirmedValue float
fConfirmedCommission float
iDeclinedCount int
fDeclinedValue float
fDeclinedCommission float
iClick int

getImpressionStats

Gets the requested link impression stats

Parameters

Element Type Required Description
dStartDate dateTime YES Start date of date range
dEndDate dateTime YES End date of date range
aMerchantIds ArrayOfInt NO Array of merchant ids to limit the results to
sDateType DateType YES Which date the range will apply to. Default is transaction
iOffset int NO Offset the results - default 100
iLimit int NO limit result set - max 100 - default 100

Response

Element Value Description
getImpressionStatsReturn ArrayOfImpressionStats Result set
getImpressionStatsCountReturn RowCounts Nuber of rows returned/available


TransactionQuery Data Type

Value Type
sLinkName String
sLinkType string
sMerchantName string
iPendingCount int
fPendingvalue float
fPendingCommission float
iConfirmedCount int
iConfirmedValue float
fConfirmedCommission float
iDeclinedCount int
fDeclinedValue float
fDeclinedCommission float
iImpressions int
Retrieved from "http://wiki.affiliatewindow.com/index.php/Affiliate_service_APIV3"