Transactional Web Service

Top  Previous  Next

In addition to using the Simple Reporting Service to retrieve data from Navigator, it is possible to complete a number of transactions on Navigator using web service calls.


In order to do this, you will need to contact your Navigator Account Manager to be allocated an API key - which is targeted specifically to allow the calls you wish to make.


Each Navigator transaction contains the following information :-


 API Key:        The API Key supplied by Navigator

 Session Key:        An optional Session Key used for security - this is retrieved using a login call if needed for the call in question

 Method Name:        The name of the transaction to call


In addition each call may have a specific set of parameters sent and returned.


The URL for the web service is :


The web service uses HTTP POST to accept a text/text data structure that may be XML or JSON in the following format :-





<apikey>i[api key]</apikey>

<method>[method name]</method>


<[parameter 1 name]>[parameter 1 data]</[parameter 1 name]>

<[parameter 2 name]>[parameter 2 data]</[parameter 2 name]>

<[parameter 3 name]>[parameter 3 data]</[parameter 3 name]>


<[parameter n name]>[parameter n data]</[parameter n name]>







 "request": {

  "apikey": "[api key]",

  "method": "[method name]",

  "parameters": {

    "[parameter name 1]": "[parameter 1 data]",

    "[parameter name 1]": "[parameter 2 data]",

    "[parameter name 2]": "[parameter 3 data]",


    "[parameter name n]": "[parameter n data]"







The web service call returns a result containing the following information :-


 Method : The transaction method name called

 resultcode: 1/0 to indicate success or failure 

 message: a general message indicating reason for failure or generic success message

 result: a list of returned parameters







<resultcode>[1/0 - success or failure</resultcode>

<message>[Error Message or information]</message>


<[result 1 name]>[result 1 data]</[result 1 name]>

<[result 2 name]>[result 2 data]</[result 2 name]>

<[result 3 name]>[result 3 data]</[result 3 name]>


<[result n name]>[result n data]</[result n name]>








"method": "[method name]",

"resultcode": "[1/0]",

"message": "[message returned]",

"result": {

"result 1 name": "[result 1 data returned",

"result 2 name": "[result 2 data returned",

"result 3 name": "[result 3 data returned",


"result n name": "[result n data returned"





Many transactional calls are available, in theory duplicating almost anything that Navigator itself can do - for example posting a nominal journal, or adding a stock record. 


A typical use of this will be in Excel.    Excel supports macros written in VBA.   For those that are familiar, sample VBA call made to make a call and parse the result is as follows -


Excel VBA Sample


Public Sub CallProg()


' call prog

Dim wsControl As Worksheet

Dim apiKey As String

Dim MethodName As String

Set wsControl = Sheets("Control")

apiKey = wsControl.Cells(3, 2) ' assumes the API key is stored in cell B3 in Control Sheet

MethodName = wsControl.Cells(4, 2) ' assumes the method name is stored in cell B4 in Control Sheet


' Set up XML for call

Dim xml As String

xml = "<request>"

xml = xml & "<apikey>" & apiKey & "</apikey>"

xml = xml & "<method>" & MethodName & "</method>"

xml = xml & "<parameters>"


' Assumes that the control sheet has a list of parameter names in columm A and the data in column B starting at column 7 onwards


Dim rowno As Integer

rowno = 7


   xml = xml & "<" & wsControl.Cells(rowno, 1) & ">" & wsControl.Cells(rowno, 2) & "</" & wsControl.Cells(rowno, 1) & ">"

   rowno = rowno + 1

Loop Until wsControl.Cells(rowno, 1) = ""

xml = xml & "</parameters>"

xml = xml & "</request>"



' Make the call

Destws = wsControl.Cells(5, 2) ' Assumes the destination sheet for the call result is stored in cell B5 in Control Sheet



With ActiveSheet.QueryTables.Add(Connection:="URL;", Destination:=Range("A2"))

   .PostText = xml

   .RefreshStyle = xlOverwriteCells

   .SaveData = True

   .BackgroundQuery = False


End With


' Now parse the result

   xml = Range("A2").Text


   ActiveSheet.Cells(4, 1) = "Batch No"

   ActiveSheet.Cells(4, 2) = getXML(xml, "BatchNo") ' This example extracts a result of "BatchNo" and displays in cell B4 in the reault sheet


End Sub


Public Function getXML(xml As String, NodeName As String) As String

' Function to extract XML result information

Dim oXml As MSXML2.DOMDocument60

   Set oXml = New MSXML2.DOMDocument60

   oXml.LoadXML xml

   Dim oSeqNodes, oSeqNode As IXMLDOMNode


   Set oSeqNodes = oXml.SelectNodes("//response/result")


   getXML = oSeqNodes(0).SelectSingleNode(NodeName).Text

End Function