11. Web API

This feature is intended for use by developers and experienced programmers who need to integrate third party systems with Kartris (such as EPOS or accounts systems) or add/update/remove/read data within Kartris remotely and programmatically.

The web API ('Application Programming Interface') is a feature introduced in Kartris v2.5005 onwards. It provides a flexible, web-accessible route to access the Kartris BLL functionality. This allows you to write code which can connect to Kartris and add/modify/delete or read data. It is intended for developers and experienced programmers who understand formatting and parsing SOAP requests.

11.1. Activating the web API

To activate the web API you have to set a couple of things in your site's web.config file:

Web API secret key - KartrisWebAPISecretKey App Setting
Service base address - baseAddresses entry

<appSettings>
   <add key="KartrisWebAPISecretKey" value="[YourSecretKeyHere]" />
</appSettings>
...
<baseAddresses>
   <add baseAddress="[YourWebShopURLHere]Protected/KartrisWebAPI.svc" />
</baseAddresses>

Note that [YourWebShopURLHere] should be exactly the same as your general.webshopurl config setting (in the Kartris back end config system).

11.2. Using the web API

Once you have activated and configured the web API, you can access it as follows:

[YourWebShopURLHere]Protected/KartrisWebAPI.svc

The web service contains a single method called 'Execute' with two parameters:

strMethod
strParametersXML

The function itself is below, together with guidance on usage in the XML comments.

'''<summary>
'''Execute Kartris method
'''</summary>
'''<param name="strMethod">Name of the method that you want to execute (fully
'''qualified name, case-sensitive) e.g. CKartrisBLL.WebShopURL </param>
'''<param name="strParametersXML">XML parameter array for the specified method</param>
'''<returns>XML Serialized Object</returns>
'''<remarks></remarks>
Public Function Execute(ByVal strMethod As String, ByVal strParametersXML As String) As String

In order for the API calls to be authenticated, the web API secret key value must be passed as the 'Authorization' HTTP Header in the request. The service can be accessed through a standard SOAP request.

e.g. (VBScript)

set xmlhttp = WScript.CreateObject("MSXML2.ServerXMLHTTP.6.0")
xmlhttp.Open "POST", "[YourWebShopURLHere]Protected/KartrisWebAPI.svc", False
xmlhttp.setRequestHeader "Authorization", [YourSecretKeyHere]
xmlhttp.setRequestHeader "Content-Type", "text/xml"
xmlhttp.setRequestHeader "SOAPAction", "http://tempuri.org/IKartrisWebAPI/Execute"
xmlhttp.send requestDoc.xml

...where requestDoc.xml is the generated SOAP request. An example of which is shown below:

    <s:Envelope xmlns:s='http://schemas.xmlsoap.org/soap/envelope/'>  
     <s:Body>   
      <Execute xmlns='http://tempuri.org/'>   
        <strMethod>TaxBLL.GetTaxRate</strMethod>   
        <strParametersXML>  
        &lt;?xml version="1.0" encoding="utf-8" ?&gt;  
        &lt;KartrisWebAPI&gt;  
        &lt;Parameters&gt;  
        &lt;Parameter Name="numTaxID" Type="Byte"&gt;  
        &lt;Value&gt;2&lt;/Value&gt;  
        &lt;/Parameter&gt;  
        &lt;/Parameters&gt;  
        &lt;/KartrisWebAPI&gt;  
        </strParametersXML>   
      </Execute>   
     </s:Body>   
    </s:Envelope>

The method will serialize the output data and return it as an XML string. The sample request above will return a standard SOAP response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
 <s:Body>
  <ExecuteResponse xmlns="http://tempuri.org/">
   <ExecuteResult>
    &lt;?xml version="1.0" encoding="utf-16"?&gt;
    &lt;double&gt;20&lt;/double&gt;
   </ExecuteResult>
  </ExecuteResponse>
 </s:Body>
</s:Envelope>

Extracted data (HTMLDecoded value):

<?xml version="1.0" encoding="utf-8" ?>
 <double>20</double>

Which can then be XML deserialized in .NET as a "Double" variable with a value of 20.

11.3. Sample code

We have a sample .vbs script which uses the web API within the core Kartris zip, located here:

/Protected/KartrisWebAPISample.vbs

Obviously you don't have to use VBscript. This is a SOAP interface, so you can use .NET, php, Javascript, Java, or whatever.

A Kartris developer POLYCHROME has also kindly donated some sample extension code, 'helper' classes which may be useful to help illustrate how to extend Kartris's BLL for use via the web API for your specific application.

Sample code for extending Kartris with helper classes to use via the web API

Kartris Web API Extensions Sample Code 1541760152_8548.zip 9.5KB