Intro
Our webservices are the easiest way to the get the information you need from the system, each webservice will provide access to a layer of information and functionality to enrich your app or solution.
All requests are POST requests. Before using the web services check info about required headers below.
Headers
To perform requests you need to add headers listed below.
| Header |
Description |
| "Content-Type" : "application/json" |
This header is mandatory for all requests. You'd send it in any situation. |
| "applicationToken" : YOUR_APP_TOKEN |
This header defines which application makes the call and is also mandatory. YOUR_APP_TOKEN is the token for exact application, which can be created in your admin panel. |
| Credentials token header |
This header helps the server to identify which user the method is called for. This header is required for methods, which provide access to exact user's data (GetCustomer, GetActiveCarts, UpdatePin, etc).
In case you'll send this header for methods, which don't require it, nothing bad will happen. In case you'll forget to add it for those methods which do require it, you'll get error 403.
Generally this header should be added in two situations:
a) The user is logged in using Login method.
Among other parameters Login method returns CredentialsHeaderName string and CredentialsToken string ("CredentialsHeaderName" : "YOUR_CredentialsHeaderName", "CredentialsToken" : "YOUR_CredentialsToken").
Values for these parameters are unique for each session. You'd use them correspondingly to create a credentials token header. In this case the header should look like this:
"YOUR_CredentialsHeaderName" : "YOUR_CredentialsToken"
b) In case you want to provide ability to use your system without registration (e.g. easy ordering in the market), the Login method will not be called and you'll not be able to use auto-generated credentials values.
For such situations allows you to generate credentials token yourself and to add it to headers with the "Cookie" parameter. So the header will look like this:
"Cookie" : CREDENTIALS_TOKEN_YOU_GENERATED
This will allow you to keep user's data between user's session. For example, GetActiveCarts will return you same active carts as long as you use same token. |
| Signature header |
This is a mandatory header. It brings more security to your services and may look different:
"Signature", "bytes-SHA256, YOUR_BASE64HASH"
"Signature", "values-SHA384, YOUR_BASE64HASH", etc.
For more details check Signature topic. |
Signature
The signature adds a layer of security by ensuring the integrity of the server request and response.
It is sent and received in the http header with the Signature key:
Signature: [ Mode ]-[ Hash algorithm ], [ base64(hash(Data + Salt)) ]
| Mode |
use bytes in case the entire post body is hashed |
use values in case only parameters' values are hashed |
| Hash algorithm |
Can be either SHA256, SHA384 or SHA512. MD5 is supported but not recommended |
| Data |
should be the entire post body string if mode is set to bytes.For example, in case your request body string looks like
{"name":"John","surname":"Gray","age":45} your Data will look the same.In case body for the
current request is empty, use an empty string as Data |
should contain only parameters' values if mode is set to values. Parameter values should be concatenated in the order they
appear in the service function.For example, in case your request looks like {"name":"John","surname":"Gray","age":45} and real order
of parameters in the service function is name/surname/age, your Data will look like JohnGray45. But in
case real order of parameters in the service function is age/name/surname, your Data will look like 45JohnGray.
In case body for the current request is empty (doesn't have any values), use an empty string as Data |
| Salt |
This value is unique for each application token and can be taken from your admin panel |
Examples
Please note that this base64 string is for demonstration only.
A signature header that calculates the entire post and uses SHA256 would look like this:
Signature: bytes-SHA256, anVzdCBhIHNhbXBsZSBzaWduYXR1cmU=
A signature header that calculates the parameters' values and uses SHA384 would look like this:
Signature: values-SHA384, c29tZSB2YWx1ZXMgc2lnbmF0dXJl=
The service reply will contain a response header signature with the same structure as described above. You should check this signature for integrity.
Code examples for hashing and converting to base64
ASP.Net (VB)
Public Class Signature
Public Shared Function GenerateSHA256(ByVal value As String) As String
Dim sh As System.Security.Cryptography.SHA256 = System.Security.Cryptography.SHA256.Create()
Dim hashValue As Byte() = sh.ComputeHash(System.Text.Encoding.UTF8.GetBytes(value))
Return System.Convert.ToBase64String(hashValue)
End Function
End Class
'Usage Example
Dim sSignature As String = Signature.GenerateSHA256("1234567ABCDEFGHIJ")
ASP.Net (C#)
public class Signature
{
public static string GenerateSHA256(string value)
{
System.Security.Cryptography.SHA256 sh = System.Security.Cryptography.SHA256.Create();
byte[] hashValue = sh.ComputeHash(System.Text.Encoding.UTF8.GetBytes(value));
return System.Convert.ToBase64String(hashValue);
}
}
//Usage Example
string sSignature = Signature.GenerateSHA256("1234567ABCDEFGHIJ");
PHP 5
$val=base64_encode(hash("sha256", "1234567ABCDEFGHIJ", true));