This document outlines the concepts, methods and objects used in the various APIs.
The concepts, objects and methods described in this document are generic in nature, and are used by the various APIs as required.
These concepts, objects and methods are designed to function within the context of a specific, specialised API, and have little use outside of APIs. Refer to specific API documentation for detailed information on the various APIs.
All APIs via SOAP use the Permissions System to allow and deny access to users. Use of these APIs require a user to be granted the various actions (all under iSAMS / API) to be able to authenticate and perform the various actions available under the various APIs. See individual API documentation for details.
The methods outlined in this document require the iSAMS / API permission for use.
Error handling is primarily left to the caller. Any methods that return an ApiResponse object will provide additional details that can be used to assist when debugging problems.
Where a "Call Identifier" is returned in the Message field of the ApiResponse, then a full exception trace will be available from http://[siteurl]/logs/api/{Call Identifier}.txt
Generic concepts relating to the APIs are listed below.
Generic API methods are listed below.
API objects are listed below.
Each website in the system has a unique numeric website ID associated with it. These website IDs may be required as a parameter to an API method if the action performed by the method requires a specific website as a target of an operation.
Desktop and mobile sites are considered separate websites for this purpose.
A list of website URLs and their corresponding website IDs can be obtained by calling the ListAvailableWebsites method.
Website IDs are static and do not change once assigned, and as such this method will need to be called rarely. However, if a new website is created in the system, this method should be called to retrieve the website ID of the new website. Note that adding a new website to an existing system will not change the website IDs of existing websites.
As an example, consider an (imaginary) system with four websites, consisting of separate desktop and mobile sites for New Zealand and Australia (i.e. four websites in total). The following table shows an example of one possible set of website IDs for these websites:
| Site | URL | Website ID |
|---|---|---|
| Desktop site (New Zealand) | http://www.site.co.nz | 1 |
| Desktop site (Australia) | http://www.site.com.au | 2 |
| Mobile site (New Zealand) | http://m.site.co.nz | 3 |
| Mobile site (Australia) | http://m.site.com.au | 4 |
The exact website IDs assigned to each site are arbitrary and are not guaranteed to be ordered or sequential. The important thing to note is that each website ID is unique to a website, and conversely that a website ID uniquely identifies a website.
Authenticates against the credentials provided, and returns a token to be used for all subsequent method calls in the current API session.
| Name | Type | Description |
|---|---|---|
| username | String | username to authenticate with. |
| password | String | Corresponding password to authenticate with. |
Returns an ApiReponse object.
Typically any API session will begin with a call to this method to obtain an authentication token for subsequent API calls.
The authentication token will be returned in the Message field of the ApiReponse object.
Lists the available websites and their corresponding website IDs for this system.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
Returns an NVPApiReponse indicating the outcome of the call and containing website ID data if successful.
The Data field of the response contains a set of NameValuePairs, where the Name of a pair is a website URL and the Value is the website ID for that particular website.
See Website ID for information on website IDs.
Contains basic information about the result of a method call.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Success | Boolean | Indicates the success or failure of an API method call. | A failure (false) response should contain a failure Code and Message in the respective fields. |
| Code | Integer | A response code for the method call. | |
| Message | String | Message or output from the method call. |
Contains basic information about the result of a method call, along with an array of string values.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Success | Boolean | Indicates the success or failure of an API method call. | A failure (false) response should contain a failure Code and Message in the respective fields. |
| Code | Integer | A response code for the method call. | |
| Message | String | Message or output from the method call. | |
| Data | String[] | Supplementary data returned from the method call. |
Contains basic information about the result of a method call, along with an array of integer values.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Success | Boolean | Indicates the success or failure of an API method call. | A failure (false) response should contain a failure Code and Message in the respective fields. |
| Code | Integer | A response code for the method call. | |
| Message | String | Message or output from the method call. | |
| Data | Integer[] | Supplementary data returned from the method call. |
Contains basic information about the result of a method call, along with an array of NameValuePair objects.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Success | Boolean | Indicates the success or failure of an API method call. | A failure (false) response should contain a failure Code and Message in the respective fields. |
| Code | Integer | A response code for the method call. | |
| Message | String | Message or output from the method call. | |
| Data | NameValuePair[] | Supplementary data returned from the method call. |
An NVPApiResponse is a collection of key-value pairs, where the Name of each NameValuePair is the key for the pair.
The Names in an NVPApiResponse may not be unique, and the NameValuePairs in any response are not ordered in any way.
Represents a basic name-value pair.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Name | String | Name of the pair. | |
| Value | String | Value of the pair. |
Contains basic information about the result of a method call, along with an array of IdentifierValuePair objects.
This is a generic response type. Different methods may return IdentifierValuePairs with different types for their Key and Value properties.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Success | Boolean | Indicates the success or failure of an API method call. | A failure (false) response should contain a failure Code and Message in the respective fields. |
| Code | Integer | A response code for the method call. | |
| Message | String | Message or output from the method call. | |
| Data | IdentifierValuePair[] | Supplementary data returned from the method call. |
An IdentifierValuePairApiResponse is a collection of key-value pairs, where the Key of each IdentifierValuePair is the key for the pair.
The Keys in an IdentifierValuePairApiResponse may not be unique, and the IdentifierValuePairs in any response are not ordered in any way.
Represents a key-value pair.
This is a generic response type. Different methods may return IdentifierValuePairs with different types for their Key and Value properties.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Key | (Generic) | Key of the pair. | |
| Value | (Generic) | Value of the pair. |
The types of the Key and Value pairs will depend on the method being called.
Object used to transmit payment details between services.
| Name | Type | Description | Notes |
|---|---|---|---|
| Type | String | The card type. | |
| Number | String | The card number. | |
| Name | String | The name of the card holder. | |
| CSC | String | The card security code. | |
| Month | Int32 | The expiry month of the card. | |
| Year | Int32 | The expiry year of the card. |
Represents a product promotion redeemed using a coupon code.
| Name | Type | Description | Notes |
|---|---|---|---|
| Code | String | The coupon code required to redeem this promotion. | |
| RedemptionMessage | String | A UI message related to this promotion. | |
| ValidFrom | DateTime | The time the promotion can be redeemed from. | |
| ValidTo | DateTime | The time the promotion can be redeemed to. |
An ApiResponse object for a collection of CustomerAddresses.
| Name | Type | Description | Notes |
|---|---|---|---|
| Data | CustomerAddress[] | The CustomerAddresses included in this response. | |
| Success | Boolean | Indicates if the call was successful. | |
| Code | Int32 | Contains a numeric code providing additional information on the result of the call. | |
| Message | String | Non-structured message containing further information or data. |
Wrapper for returning an Initiated Order.
| Name | Type | Description | Notes |
|---|---|---|---|
| Data | Order | An Initiated Order. | |
| Success | Boolean | Indicates if the call was successful. | |
| Code | Int32 | Contains a numeric code providing additional information on the result of the call. | |
| Message | String | Non-structured message containing further information or data. |
Used to indicate the result of an API method call.
| Code | Description | Notes |
|---|---|---|
| 0 | Success. | |
| 1000 | Authentication of provided credentials failed. | |
| 1001 | Caller does not have permission to call this method. | |
| 2000 | Invalid data was passed in the request. | |
| 2001 | The allowed call rate of this API method was exceeded. | |
| 2002 | The requested operation is not valid with the system in the current state. | |
| 3000 | An internal error occurred. |