Você está na página 1de 17

Web Services: AffiliateService API Technical Specification

Version 4

Introduction ..........................................................................3
Intended Audience ................................................................................................................ 3
The AffiliateService ............................................................................................................... 3
Updates and versioning ........................................................................................................ 3
Other services ....................................................................................................................... 3

API Overview .........................................................................3


WSDL ..................................................................................................................................... 3
User authentication .............................................................................................................. 3
Quota .................................................................................................................................... 3
Dates and Time Zones ........................................................................................................... 4
SOAP Request Format ........................................................................................................... 4
Header .............................................................................................................................. 4
Body .................................................................................................................................. 4
SOAP Response Format ......................................................................................................... 6

API Methods ..........................................................................7


Headers ................................................................................................................................. 7
UserAuthentication .......................................................................................................... 7
getQuota ........................................................................................................................... 7
Requests ................................................................................................................................ 8
getCommissionGroup ....................................................................................................... 8
getTransactionProduct ..................................................................................................... 8
getTransactionList............................................................................................................. 9
getTransaction ................................................................................................................ 11
getMerchant ................................................................................................................... 12
getMerchantList.............................................................................................................. 13
getTransactionQuerys..................................................................................................... 14
getImpressionStats ......................................................................................................... 16

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

The AffiliateService
The AffiliateService provides the necessary functionality to retrieve all the information about
an Affiliates 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.

Updates and versioning


The current version of the AffiliateService is version 4.
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/v4/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 SOAPHeader, 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.

Dates and Time Zones


All dates are returned in UTC, and any date passed as a parameter will be used as UTC unless
a time zone offset is specified. This is different to previous versions of the API, where dates
were accepted and returned in Europe/London and any time zone offsets were ignored.
To pass a time zone offset in a parameter, add it at the end of a date, so for a date in British
Summer Time (BST) which is 1 hour ahead of UTC, you would pass in a value like
2012-05-13T12:35:00+01:00, where the +01:00 specifies the offset.
For more information see http://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC

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
getQuota

The header must contain element required to authenticate


the user.
The header can optionally contain a call to the method
getQuota

Body
getCommissionGroup

Gets the commission values for a given commission group.

getTransactionProduct

Gets the products associated with an affiliate transaction.

getTransactionList

Gets the transactions that fall under the specified criteria.

getTransaction

Gets the requested transactions.

getMerchant

Gets the requested merchants.

getMerchantList

Gets the merchants that fall under the specified criteria.

getTransactionQuerys

Gets the transaction queries that fall under the specified


criteria.

getClickStats

Gets click stats that fall under the specified criteria.

getImpressionStats

Gets impression stats that fall under the specified criteria.

<?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" SOAPENV: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:mSaleAmount>
<ns1:dAmount>22.6</ns1:dAmount>
<ns1:sCurrency>GBP</ns1:sCurrency>
</ns1mfSaleAmount>
<ns1:mCommissionAmount>
<ns1:dAmount>4.52</ns1:dAmount>
<ns1:sCurrency>GBP</ns1:sCurrency>
</ns1:mCommissionAmount>
<ns1:dClickDate>2006-08-06T16:36:21</ns1:dClickDate>
<ns1:dTransactionDate>2006-08-07T22:31:48+00:00</ns1:dTransactionDate>
<ns1:dValidationDate>2006-08-08T17:21:13+00:00</ns1:dValidationDate>
<ns1:aTransactionParts>
<ns1:TransactionPart>
<ns1:sCommissionGroupName>Default Commission</ns1:sCommissionGroupName>
<ns1:mSaleAmount>
<ns1:dAmount>22.6</ns1:dAmount>
<ns1:sCurrency>GBP</ns1:sCurrency>
</ns1:mSaleAmount>
<ns1:mCommissionAmount>
<ns1:dAmount>4.52</ns1:dAmount>
<ns1:sCurrency>GBP</ns1:sCurrency>
</ns1:mCommissionAmount>
<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

iId

int

Yes

The user id.

sPassword

string

Yes

The user password.

sType

UserType

Yes

The user type.

Response
none

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

Type
boolean

Response
Elements

Yes

Type
int

Required

Description
Indicate if the quota should be returned or not.

Description
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

sCommissionGroupCode

string

Yes

Commission group code

Response
Element

Type

getCommissionGroupReturn

CommissionGroup

Commission Group Data Type


Element

Type

Description
Commission Group object

Description

sCommissionGroupCode

string

Commission group code

mAmount

Money

Set amount given.

fPercentage

float

Percentage of sale amount.

Money Data Type


Element

Type

Description

fAmount

float

The Amount

sCurrency

string

The currency code eg. GBP,


USD

getTransactionProduct
Gets the products that are associated with this transaction.
Parameters
Element
aTransactionIds

Type

Required

Array of Integers

Yes

Description
Array of transaction Ids

Response
Element
getTransactionProductReturn

Type

Description

ArrayOfTransactionProduct

Transactions and an array of


their associated products

TransactionProduct Data Type


Element

Type

Description

iTransactionId

int

Transaction id

aProducts

ArrayOfProducts

Array of Product

Product Data Type


Details per product.
Element

Type

Description

iId

int

Product id

sName

string

Product name

mUnitPrice

Money

Unit price of product

getTransactionList
Gets the transactions that fall under the specified criteria
Parameters
Element

Type

Required

aMerchantIds

ArrayOfInt

Yes

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 transaction status e.g.


pending, confirmed.

iOffset

int

No

Offset the results


default 0.

iLimit

int

No

Limit result set max 100


default 100

DateType Data Type


Type
string

Values
transaction
validation

Description

TransactionStatus Data Type


Type
string

Values
pending
confirmed
declined

Response
Element

Type

getTransactionListReturn

ArrayOfTransaction

Array of Transaction
objects.

getTransactionListCountReturn

RowCounts

Number of rows
returned/available.

Transaction Data Type


Element

Type

iId

int

sStatus

TransactionStatus

sType

TransactionType

sIp

string

bPaid

boolean

iPaymentId

int

sDeclinedReason

string

iMerchantId

int

mSaleAmount

Money

mCommissionAmount

Money

dClickDate

dateTime

dTransactionDate

dateTime

dValidationDate

dateTime

sClickRef

string

sSearchSiteName

string

sSearchSiteKeyword

string

aTransactionParts

ArrayOfTransactionPart

RowCounts Data Type


Element

10

Description

Type

iRowsReturned

int

iRowsAvailable

int

TransactionStatus Data Type


Type
string

Values
pending
confirmed
declined

TransactionType Data Type


Type
string

Values
normal
bonus
second tier
untracked

TransactionPart Data Type


Element

Type

aCommissionGroupName

string

mSaleAmount

Money

mCommissionAmount

Money

iCommission

int

sCommissionType

commissionType

CommissionType Data Type


Type
string

Values
percentage
amount

getTransaction
Gets the requested transactions.
Parameters
Element
aTransactionIds

Type
ArrayOfInt

Required
Yes

Description
The id's of the transactions
to get.

Response
Element
getTransactionReturn

11

Type
ArrayOfTransaction

Description
Array of Transaction objects.

getMerchant
Gets the requested merchants.
Parameters
Element
aMerchantIds

Type

Required

ArrayOfInt

Description

Yes

The ids of the merchants to


get.

Response
Element
getMerchantReturn

Type
ArrayOfMerchant

Merchant Data Type


Elements

12

Description
Array of Merchant objects.

Type

iId

int

sName

string

sDisplayUrl

string

sClickThroughUrl

string

sLogoUrl

string

iDetailsVersion

int

dDetailsModified

dateTime

iFeedVersion

int

dFeedModified

dateTime

sStrapline

string

sDescription

String

fApprovalPercentage

float

fEpc

float

fConversionRate

float

iValidationDays

float

fAwinGrade

float

aCommissionGroups

ArrayOfCommissionRanges

aSectors

ArrayOfMerchantSectors

oPrimaryRegion

Region

CommissionRange Data Type


Element

Type

sType

CommissionType

fMin

float

fMax

float

MerchantSector Data Type


Element

Type

iSectorId

int

sSectorName

string

CommissionType Data Type


Type
string

Values
percentage
amount

Region Data Type


Element

Type

sName

string

sCountryCode

string

sCurrencyCode

String

getMerchantList
Gets the merchants that fall under the specified criteria.
Parameters
Element
sRelationship

Type
Relationship

Required
No

Relationship Data Type


Type
string

Description
The affiliate's relationship to
the merchant.

Value
joined

Response
Element
getMerchantListReturn

13

Type
ArrayOfMerchant

Description
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

Value

Required

Description

aMerchantIds

ArrayOfInt

Yes

Array of merchant ids.

aStatus

ArrayOfTransaction
PreStatus

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
string

Value
pending
confirmed
declined

Response
Element

14

Value

Description

getTransactionQuery

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

mAmount

Money

mCommission

Money

dDate

dateTime

sCustomerReference

string

sReference

string

sProgramName

string

sDeclineReason

string

sType

string

sDescription

string

getClickStats
Gets the requested link click stats.
Parameters
Element

15

Type

Required

Description

dStartDate

dateTime

Yes

Start date of date range.

dEndDate

dateTime

Yes

End date of date range.

aMerchantIds

ArrayOfInt

Yes

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

Required

Description

getClicksStatsReturn

ArrayOfClick
Stats

Yes

Result set

getClickStatsCountReturn

RowCounts

Yes

Number of rows
returned/available.

ClickStats Data Type


Value

Type

sLinkName

string

sLinkType

string

sMerchantName

string

iPendingCount

int

mPendingValue

M oney

mPendingCommission

Money

iConfirmedCount

int

mConfirmedValue

Money

mConfirmedCommission

Money

iDeclinedCount

Int

mDeclinedValue

Money

mDeclinedCommission

Money

iClick

int

getImpressionStats
Gets the requested link impression stats.
Parameters
Element

16

Value

Required

Description

dStartDate

dateTime

Yes

Start date of date range.

dEndDate

dateTime

Yes

End date of date range.

aMerchantIds

ArrayOfInt

Yes

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

iLimit

int

No

Limit result set max 100


default 100.

Response
Element

Value

getImpressionStatsReturn

ArrayOfImpressionStats

Result set

getImpressionStatsCountReturn

RowCounts

Number of rows
returned/available.

ImpressionStats Data Type


Value

17

Description

Type

sLlinkName

string

sLinkType

string

sMerchantName

string

iPendingCount

Int

mPendingValue

Money

mPendingCommission

Money

iConfirmedcount

Int

mConfirmedValue

Money

mConfimedCommission

Money

iDeclinedCount

int

mDeclinedValue

Money

mDeclinedCommission

Money

iImpressions

int

Você também pode gostar