Webservices
See the NOVUS Walkthrough Guide for general information about the system.
Table of Contents
Webservice - PLPOST
The PLPOST program allows the entry of invoices and expenses into the NOVUS accounting system.
This webservice accepts specifically formatted XML that represents a single or group of invoices and inserts them into the Novus database over a secured internet connection.
Validation checks are made before the data is entered into the NOVUS database that makes sure all requires fields have been provided, values are formatted correctly and that code values exist in the database. In the event that incorrect data is sent to the webservice an error code with a descriptive error message is sent back to describe what went wrong.
XML Schema Definition
The XML must conform to the following XML Schema Definition (XSD):
<?xml version="1.0" encoding="UTF-8" ?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="PLPOST_Request"> <xs:complexType> <xs:sequence> <xs:element name="invoice_ref"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:maxLength value="16"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="header"> <xs:complexType> <xs:sequence> <xs:element name="account_code"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:pattern value="[A-Z0-9]{1,8}"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="invoice_type" default="INV"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="INV"/> <xs:enumeration value="CRE"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="invoice_date" type="xs:date" minOccurs="0"/> <xs:element name="gross_amount"> <xs:simpleType> <xs:restriction base="xs:decimal"> <xs:fractionDigits value ="2"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="currency_code"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:pattern value="[a-zA-Z0-9]{3}"/> </xs:restriction> </xs:simpleType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="line_item" minOccurs="1" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:element name="division_code"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:pattern value="[A-Z0-9]{1,4}"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="country_code" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:pattern value="[a-zA-Z0-9]{1,4}"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="nl_account_code" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:pattern value="[0-9]{1,5}"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="department_code"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:pattern value="[a-zA-Z0-9]{1,4}"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="reference" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:maxLength value="50"/> <xs:minLength value="1"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="due_date" type="xs:date"/> <xs:element name="net_amount"> <xs:simpleType> <xs:restriction base="xs:decimal"> <xs:fractionDigits value="2"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="vat_code" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:pattern value="[a-zA-Z0-9]{1,4}"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="vat_amount"> <xs:simpleType> <xs:restriction base="xs:decimal"> <xs:fractionDigits value="2"/> </xs:restriction> </xs:simpleType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="PLPOST_Response"> <xs:complexType> <xs:sequence> <xs:element name="invoice_ref"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:maxLength value="16"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="result" > <xs:simpleType> <xs:restriction base="xs:integer"> <xs:enumeration value="0"/> <xs:enumeration value="1"/> <xs:enumeration value="2"/> <xs:enumeration value="100"/> <xs:enumeration value="101"/> <xs:enumeration value="102"/> <xs:enumeration value="103"/> <xs:enumeration value="104"/> <xs:enumeration value="105"/> <xs:enumeration value="106"/> <xs:enumeration value="107"/> <xs:enumeration value="108"/> <xs:enumeration value="200"/> <xs:enumeration value="201"/> <xs:enumeration value="202"/> <xs:enumeration value="203"/> <xs:enumeration value="204"/> <xs:enumeration value="205"/> <xs:enumeration value="300"/> <xs:enumeration value="9999"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="message" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:maxLength value="4000"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="transaction_ref" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:length value="6"/> </xs:restriction> </xs:simpleType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
Example
In this PLPOST example, two items totalling 100.00 with an invoice reference (invoice no) of INV-12345678.
Below is the XML equivalent of the data being inserted in the example above.
<PLPOST_Request>
<invoice_ref>INV-12345678</invoice_ref>
<header>
<account_code>TEST001</account_code>
<invoice_type>INV</invoice_type>
<invoice_date>2016-12-31</invoice_date>
<gross_amount>100.00</gross_amount>
<currency_code>GBP</currency_code>
</header>
<line_item>
<division_code>A</division_code>
<country_code>GB</country_code>
<nl_account_code>12000</nl_account_code>
<department_code>XX</department_code>
<reference>sugar, spice and all things nice</reference>
<due_date>2017-01-31</due_date>
<net_amount>62.50</net_amount>
<vat_code>1</vat_code>
<vat_amount>12.50</vat_amount>
</line_item>
<line_item>
<division_code>A</division_code>
<country_code>GB</country_code>
<nl_account_code>23000</nl_account_code>
<department_code>XX</department_code>
<reference>basil, thyme and plenty of wine</reference>
<due_date>2017-02-28</due_date>
<net_amount>20.83</net_amount>
<vat_code>1</vat_code>
<vat_amount>4.17</vat_amount>
</line_item>
</PLPOST_Request>
Validation
There are various checks performed on incoming XML by the webservice in addition to the XML definition schema above. The following bulleted list details these checks.
- invoice_ref must not already exist
- invoice_type only supports INV type currently (v1.0.2)
- accound_code must exist in the dataset
- currency_code must exist in the dataset
- gross_amount must equal the sum of all (line_item.net_amount + line_item.vat_amount)
- division_code must exist in the dataset
- country_code (if provided), must exist in the dataset
- nl_account_code (if provided), must exist in the dataset
- department_code must exist in the dataset
- vat_code (if provided), must exist in the dataset
- net_amount must be a positive value if invoice_type set to INV
- vat_amount must be a positive value if invoice_type set to INV
Error Codes
If XML provided is invalid for any reason the webservice will not insert data into the dataset, will not return a transaction reference and will provide an informative error message to help highlight the cause of the issue.
- 0 = Pass
- 1 = XML Validation error
- 2 = database error
- 100 = account_code invalid
- 101 = currency_code invalid
- 102 = division_code invalid
- 103 = country_code invalid
- 104 = nl_account_code invalid
- 105 = department_code invalid
- 106 = vat_code invalid
- 107 = invoice_ref invalid
- 108 = invoice_type invalid
- 200 = invoice_date invalid
- 201 = gross_amount invalid
- 202 = reference invalid
- 203 = due_date invalid
- 204 = net_amount invalid
- 205 = vat_amount invalid
- 300 = gross does not equal sum of line items
- 9999 = unknown error
Response
When a HTTP request is made to the webservice a response will be given that describes what was done by the webservice is response to the XML provided. Below shows an example of a successful webservice call:
<PLPOST_Response> <invoice_ref>INV-1234567</invoice_ref> <result>0</result> <message>Passed</message> <transaction_ref>B00123</transaction_ref> </PLPOST_Response>
The invoice_ref value is that provided in the original request, result is always zero if the call was successful, message describes the result code in this case passed, finally only successful calls return a transaction_ref. If a transaction reference is returned the data has been entered into the dataset.
Alternatively a unsuccessful webservice call might look like this:
<PLPOST_Response> <invoice_ref>INV-1234567</invoice_ref> <result>100</result> <message>Invalid Account Code</message> <transaction_ref></transaction_ref> </PLPOST_Response>
The error code returned explains that the account_code value provided was invalid when checked against the dataset.
Finally below shows an example of a response given when the XML provided did not conform to the XML definition schema:
<PLPOST_Response> <invoice_ref>INV-12345678</invoice_ref> <result>1</result> <message>The element 'header' has invalid child element 'invoice_type'. List of possible elements expected: 'account_code'.The element 'line_item' has invalid child element 'reference'. List of possible elements expected: 'department_code'.</message> <transaction_ref></transaction_ref> </PLPOST_Response>
Version History
v 5.0.0 – Updated to latest version