Developer API – How to use
When connecting using this API, you don’t necessarily need an online store hosted on a web server. You can use any or all of the following supported functionality:
Communication into the ChannelUnity account:
- Validate a merchant account
- Get subscriptions and user names currently present on a merchant account
- Upload product data including prices and quantities
- Upload details of stores and product categories
Callbacks to the API:
- Orders from customers placed on the connected marketplaces
- Request from ChannelUnity for a list of all SKUs
- Request from ChannelUnity to provide product data
The API works via an endpoint through which XML messages are posted. The XML messages are uploaded via HTTPS.
Object Model
At the top level of the API is a “merchant”. Each merchant has a unique API key which is required when accessing the API.
Each merchant has one or more user accounts. A “main user” is created when a merchant account is created, and further users can be added with full access or restricted roles. Users are identified by the merchant name and user name in combination (i.e. a merchant could have user names also in use by other merchants).
Merchants have a list of zero or more subscriptions associated with them. Each subscription is a link to a shopping channel such as Amazon.com. Each subscription has an ID and an SKU (to uniquely indicate the exact channel in use).
Each merchant also has a set of “sources”. Each source is a shopping cart which can be the main retail website running Magento for example. A source provides product data and category data to ChannelUnity which is used to synchronize with the shopping channels. Each source has a Base URL, and in the case of Magento sources, a store view ID to link to a specific store. The diagram below illustrates this model.
Notes:
- Access to the API itself is inclusive within the main feature set of ChannelUnity.
- It is possible to link to multiple instances of the same channel, for example, multiple Amazon.com accounts.
Sample Code
CUSDK – C# Visual Studio Sample
This is a Visual Studio solution written in C# which demonstrates how to call the key ChannelUnity APIs, as well as a listener to accept notifications. There are three projects within the solution. The code which calls into the ChannelUnity API, a test console app which makes calls to a ChannelUnity account, and a listener project to accept order notifications and so on.
Visit the project page on Github
If you use PHP, check out our Magento 2 integration module. This is a good way to get an overview of a PHP implementation of this API.
If you use any other programming language and require some assistance, feel free to get in touch with us at support@channelunity.com.
API Usage
A typical request sent to the ChannelUnity Connector Kit API works as follows.
1. Create an XML message according to the specific API being called. All requests require the XML elements MerchantName, Authorization, and RequestType.
<ChannelUnity> <MerchantName>mytoolsltd</MerchantName> <Authorization>12341234</Authorization> <ApiKey>ac69d65ca5d466</ApiKey> <RequestType>ProductData</RequestType> <Payload></Payload> </ChannelUnity>
2. Create a URL encoded version of this XML message and prepend “message=”. The complete text string will constitute the data for a form upload.
3. Create a POST request to the URL “https://api.channelunity.com/event.php”. Set the Content-Type as application/x-www-form-urlencoded. Upload the data generated in step 2.
4. The response is an XML document, the contents of which will depend on the API which was called. However most calls have a message status, for example:
<ChannelUnity> <Status>OK</Status> </ChannelUnity>
The <Status> element in the returned XML message indicates whether the operation was a success or an error. To detect error conditions, the status will begin with the string “Error”. Specific error messages you may encounter are shown for each API call.
Request Elements
In the XML request, the MerchantName element contains the merchant name which is associated with the ChannelUnity account. The ApiKey element is available from the ValidateUser API, and once obtained it can be stored as it will never change. The RequestType element identifies which API is being called. The Payload element contains data specific to the API call in use.
Authorization
The Authorization element allows ChannelUnity to validate your username and password and grant API access.
To generate the value to be used in the Authorization element, follow these steps:
1. Treating all strings as UTF-8 strings, create a SHA-256 hash of the password.
2. Convert this hash into a string by encoding the bytes as a hexadecimal string. For example, the byte value 255 would be encoded as the string “ff” (please use lower case hexadecimal).
3. Now concatenate the user name, the colon symbol “:” and the string from step 2.
4. Create a Base64 encoded string of the result of step 3.
PHP Sample Code
function getValidUserAuth($username, $password) {
$auth = $username . ":" . hash("sha256", $password);
$auth = base64_encode($auth);
return $auth;
}
C# Sample Code
private string getValidUserAuth(string username, string password) {
SHA256 mySHA256 = SHA256Managed.Create();
byte[] passbytes = Encoding.UTF8.GetBytes(password);
string auth = username + ":" + HexCharsEncode(mySHA256.ComputeHash(passbytes));
auth = Convert.ToBase64String(Encoding.UTF8.GetBytes(auth));
return auth;
}
private string HexCharsEncode(byte[] inputBytes) {
string strTemp = "";
for (int x = 0; x <= inputBytes.GetUpperBound(0); x++) {
int number = int.Parse(inputBytes[x].ToString());
strTemp += number.ToString("x").PadLeft(2, '0');
}
return strTemp;
}
URL / SourceURL
The URL identifies the location of the store as provided to the StoreData API call. ChannelUnity uses this URL to pull products from the store, as well as push order data. The URL also is used to distinguish between multiple stores if multiple stores are connected to the same ChannelUnity account.