Webservices

From Wiki
Jump to: navigation, search

See the NOVUS Walkthrough Guide for general information about the system.


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.

Plpost-example.png

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