Skip to content Skip to main navigation Skip to footer

Application Program Interface

1. Scope

1.1 Identification

This document identifies the Application Programming Interface (“API”) available to third-party clients for integration with the Prelude Framework (“Framework”) infrastructure.

1.2 System Overview

The API provides a secure HTTPS gateway for communicating with Framework, sending and receiving data in XML format.

Most programming languages can accommodate such HTTPS / XML communication, allowing programmers to develop their applications to communicate directly with Framework by issuing commands as specified in this document.

1.3 Document Overview

This document will explain how to:

  • Authenticate access to Framework
  • Retrieve data from Framework
  • Send data to Framework

2. Connecting to Framework

In order to make a connection to Framework you will need the following:

  • A specific URL (the “Cluster URL”) that identifies the domain and directory that hosts the customer database with which the API is to communicate
  • A Database name that is unique to this Cluster for this customer
  • User credentials that are authorised to access this Database

These details will have been provided to the user or their administrator.

2.1 API URL

The API URL is constructed from the Cluster URL appended with a consistent endpoint/script, which is “api.pl”.

For example, if the Cluster URL is: https://my.prelude.software/clustername

the API URL is: https://my.prelude.software/clustername/api.pl

2.1.1 Validation

Communication with Framework will be accepted only via well-formed XML, which must be in the following basic format:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database></database>
           <username></username>
           <password></password>
</authenticate>
<command></command>
</api>

The format of authenticate and command XML elements are explained in the following sections.

Note the following:

  • XML must be posted to the specified API URL
  • XML is validated by https://www.w3schools.com/xml/xml_validator.asp
  • XML must include the standard DTD ?xml line with no leading spaces or carriage returns at the start of the file
  • XML element names are always lower case
  • There must be no leading/trailing white space in element data
  • Indentation of and line spacing between XML elements is optional
  • The <version> element must include the API version number that is to be used
    • See Release History for details
  • XML must include only one authenticate element
  • XML must include only one command element
  • Command-specific elements must be formatted as explained in the following sections
  • You may include other elements for your own purposes providing that they do not conflict with the names of elements defined in this document, but they will be ignored

Validation checks are carried out in following sequence:

  • Check for well-formed XML
  • Check for valid authentication
  • Check the operation defined in the API version specified in the version element data
  • Check for correct and complete data in the submitted command

If the XML passes validation, a success response in the following format will be returned:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<datetime>2018-11-01 12:00:00</datetime>
<response>
           <success>1</success>
</response>
</api>

If the XML fails validation, an error response in the following format will be returned:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<datetime>2018-11-01 12:00:00</datetime>
<response>
           <success>0</success>
           <errorcode>200</errorcode>
           <errortext>Invalid XML code</errortext>
</response>
</api>

2.1.2 Authentication

In this section we specify the authenticate XML element that must be included in every communication with Framework.  It has the following format:

<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>

Note the following:

  • database    This identifies the name of the target database with which to communicate
  • username  This is the name with which the user logs in to Framework and can be one of:
                              DATABASE.USER   a specific named user of the target database
                              DATABASE              assumes the admin user of the target database
                              OTHERCO.USER   a specific named user of a cluster-admin database*
                              OTHERCO               assumes the admin user of a cluster-admin database*
  • password   This is the password associated with the submitted username

* Framework infrastructure allows for “super users” to log in to other users’ databases in the same cluster.  If OTHERCO does not match DATABASE, it is assumed that OTHERCO.USER is a super user wishing to communicate with DATABASE.  Authentication will fail if OTHERCO.USER is not a super user in the specified cluster.

2.2 Retrieve Data from Framework: Get Commands

This section describes the commands that are available to a third party to return data in XML format from the specified database.

Please contact us if you find that you need commands that are not included in this document.

If the XML passes authentication, the target database will return the requested data in XML format and a success response code in XML format.

Each sub-section includes an example complete XML for the individual command and a table that specifies the format of the data that is returned.

The individual get commands, <get>…</get>, may be included in a larger XML submission of multiple commands.

Each individual get command may be modified with one or many conditions, <condition>…</condition>. The final sub-section describes conditions.

2.2.1 GET_NOMTAIL

To return a listing of all Nominal Ledger account definitions:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<get>
           <command>GET_NOMTAIL</command>
</get>
</api>

NameTypeExampleDescription
nt_idint(10)1Internal record ID
nt_db_idint(10)0Internal database ID
nt_codevarchar(8)CA01Nominal ledger code
nt_hdescvarchar(20)CURRENT ASSETSLedger header description
nt_descvarchar(100)STOCKLedger code description
nt_typeenum(‘B’,’P’,’’)BType of account:Balance Sheet, Profit & Loss
nt_btypeenum(‘D’,’C’,’’)DNormally displayed as positive: Debit, Credit
nt_banktinyint(1)0Designated bank account: Yes (1), No (0)
nt_max_limitdecimal(10,2)0Overdraft/Credit limit for bank account
nt_controltinyint(3)0System control account: Yes (1), No (0)
nt_statustinyint(3)1Enabled (1), Disabled (0)
nt_modifiedtimestamp2015-01-19 12:00:00System datetime this record was last modified

Example response:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<datetime>2015-01-19 12:00:00</datetime>
<success>1</success>
<number_of_rows>2</number_of_rows>
<table>ddwe_nomtail</table>
<row>
            <nt_control>0</nt_control>
            <nt_bank>0</nt_bank>
            <nt_btype>D</nt_btype>
            <nt_status>1</nt_status>
            <nt_modified>0000-00-00 00:00:00</nt_modified>
            <nt_hdesc>CURRENT ASSETS</nt_hdesc>
            <nt_type>B</nt_type>
            <nt_desc>STOCK</nt_desc>
            <nt_db_id>0</nt_db_id>
            <nt_code>CA01</nt_code>
            <nt_id>1</nt_id>
            <nt_max_limit>0.00</nt_max_limit>
</row>
<row>
            <nt_control>1</nt_control>
            <nt_bank>0</nt_bank>
            <nt_btype>D</nt_btype>
            <nt_status>1</nt_status>
            <nt_modified>0000-00-00 00:00:00</nt_modified>
            <nt_hdesc>CURRENT ASSETS</nt_hdesc>
            <nt_type>B</nt_type>
            <nt_desc>DEBTORS CONTROL</nt_desc>
            <nt_db_id>0</nt_db_id>
            <nt_code>CA02</nt_code>
            <nt_id>2</nt_id>
            <nt_max_limit>0.00</nt_max_limit>
</row>
</api>

2.2.2 GET_CUSTOMERS

To return a listing of all Sales Ledger account definitions.

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<get>
           <command>GET_CUSTOMERS</command>
</get>
</api>

Name Type Example Description
c_id int(10) 1 Internal record ID
c_db_id int(10) 1 Internal database ID
c_acc varchar(8) PRE001 Unique customer account code
c_name varchar(255) Prelude Customer name
c_addr_1 varchar(255) Tondu Enterprise Centre First line of address
c_addr_2 varchar(255) Bryn Road Second line of address
c_addr_3 varchar(255)   Third line of address
c_addr_posttown varchar(255) Aberkenfig Post town of address
c_addr_county varchar(255) Bridgend County of address
c_addr_postcode varchar(20) CF32 9BS Postcode of address
c_addr_country varchar(255) United Kingdom Country of address
c_tel varchar(255) 01656 725800 Primary telephone number
c_tel2 varchar(255) Secondary telephone number
c_fax varchar(255) Fax number
c_web varchar(255) prelude.software Web site address
c_cont varchar(255) Ian Vickers Primary contact name
c_email varchar(255) ian@prelude.software Primary contact email address
c_cont2 varchar(255) Secondary contact name
c_email2 varchar(255) Secondary contact email address
c_crlim decimal(20,0) 5000.00 Credit limit
c_special_price char(2) 1 Use selling price of product special price code 1-10
c_price_band char(1) A Use percentage discount of product discount code A-E
c_overall_discount decimal(5,2) 10.00 Default overall discount on all items given to this customer
c_pp_discount decimal(5,2) 10.00 Prompt payment discount percentage
c_pp_days tinyint(3) 30 Prompt payment discount period in days
c_statf tinyint(1) 1 Produce statements for this customer: 0/1
c_warn tinyint(1) 1 Include default warning messages on statements: 0/1
c_stop tinyint(1) 0 Account is no stop: 0/1
c_termd char(1) D Payment term period, D (days), M (months), C (calendar months)
c_termn decimal(5,0) 30 Number of payment term periods
c_comment varchar(255) Must sign for deliveries Optional comment
c_vatreg varchar(15) GB 99 9999 999 VAT registration number, if applicable
c_country char(3) DE Country code for VAT purposes
c_defvat char(1) 1 Default VAT code for transactions
c_defanal varchar(8) SA01 Default Nominal analysis for transactions
c_minord decimal(20,2) 0 Not used
c_vatinc tinyint(1) 0 VAT inclusive/exclusive pricing: 0/1
c_e_ack tinyint(1) 0 Send customer order acknowledgements by email: 0/1
c_e_acka varchar(255) ian@prelude.software Customer order acknowledgements by email: email address
c_e_ackf char(3) pdf Customer order acknowledgements by email: document format
c_e_inv tinyint(1) 0 Send customer invoices by email: 0/1
c_e_inva varchar(255) ian@prelude.software Customer invoices by email: email address
c_e_invf varchar(3) pdf Customer invoices by email: document format
c_remack char(1) Y Produce customer remittance acknowledgements: N/Y/A or blank to use Sales Ledger default
c_remack_email int(1) 0 Send customer remittance acknowledgements by email: 0/1
c_remack_email_addr varchar(255) ian@prelude.software Customer remittance acknowledgements by email: email address
c_remack_format char(3) pdf Customer remittance acknowledgements by email: document format
c_refadv char(1) A Produce customer refund advices: N/Y/A or blank to use Sales Ledger default
c_refadv_email int(1) 1 Send customer refund advices by email: 0/1
c_refadv_email_addr varchar(255) ian@prelude.software Customer refund advices by email: email address
c_refadv_format char(3) pdf Customer refund advices by email: document format
c_e_stat tinyint(1) 0 Send customer statements by email: 0/1
c_e_stata varchar(255) ian@prelude.software Customer statements by email: email address
c_e_statf char(3) pdf Customer statements by email: document format
c_statement_cont varchar(255) Ian Vickers Customer statements: contact name
c_statement_addr_1 varchar(255) Tondu Enterprise Centre Customer statements: first line of address
c_statement_addr_2 varchar(255) Bryn Road Customer statements: second line of address
c_statement_addr_3 varchar(255)   Customer statements: third line of address
c_statement_addr_posttown varchar(255) Aberkenfig Customer statements: post town of address
c_statement_addr_county varchar(255) Bridgend Customer statements: county of address
c_statement_addr_postcode varchar(20) CF32 9BS Customer statements: postcode of address
c_statement_addr_country varchar(255) United Kingdom Customer statements: country of address
c_notes text   Optional detailed notes
c_ddcrm_comp_id int(10) -1 ID of linked company in CRM database
c_ddcrm_cont_id int(10) -1 ID of linked contact in CRM database
c_deleted tinyint(1) 0 This customer account has been deleted
c_modified timestamp 2015-01-19 12:00:00 System datetime this record was last modified

Example response:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<datetime>2015-01-19 12:00:00</datetime>
<success>1</success>
<number_of_rows>1</number_of_rows>
<table>ddwe_customer</table>
<row>
            <c_db_id>0</c_db_id>
            <c_ddcrm_cont_id>-1</c_ddcrm_cont_id>
            <c_e_ack>0</c_e_ack>
            <c_addr_1></c_addr_1>
            <c_e_statf>pdf</c_e_statf>
            <c_pp_discount>0.00</c_pp_discount>
            <c_special_price></c_special_price>
            <c_deleted>0</c_deleted>
            <c_statement_addr_2></c_statement_addr_2>
            <c_statement_cont></c_statement_cont>
            <c_e_acka></c_e_acka>
            <c_statement_addr_1></c_statement_addr_1>
            <c_crlim>0</c_crlim>
            <c_statement_addr_county></c_statement_addr_county>
            <c_refadv_email_addr></c_refadv_email_addr>
            <c_statement_addr_3></c_statement_addr_3>
            <c_remack_format>pdf</c_remack_format>
            <c_remack_email_addr></c_remack_email_addr>
            <c_cont></c_cont>
            <c_warn>1</c_warn>
            <c_email></c_email>
            <c_refadv_format></c_refadv_format>
            <c_ddcrm_comp_id>-1</c_ddcrm_comp_id>
            <c_id>1</c_id>
            <c_statf>1</c_statf>
            <c_notes></c_notes>
            <c_vatinc>0</c_vatinc>
            <c_refadv_email>0</c_refadv_email>
            <c_stop>0</c_stop>
            <c_remack></c_remack>
            <c_e_invf>pdf</c_e_invf>
            <c_statement_addr_postcode></c_statement_addr_postcode>
            <c_acc>CUST0001</c_acc>
            <c_price_band></c_price_band>
            <c_addr_2></c_addr_2>
            <c_overall_discount>0.00</c_overall_discount>
            <c_e_inva></c_e_inva>
            <c_tel2></c_tel2>
            <c_addr_country></c_addr_country>
            <c_termn>0</c_termn>
            <c_country></c_country>
            <c_vatreg></c_vatreg>
            <c_fax></c_fax>
            <c_e_stata></c_e_stata>
            <c_e_stat>0</c_e_stat>
            <c_modified>2015-01-13 13:36:20</c_modified>
            <c_defanal></c_defanal>
            <c_cont2></c_cont2>
            <c_email2></c_email2>
            <c_comment></c_comment>
            <c_name>Customer Number 1</c_name>
            <c_addr_3></c_addr_3>
            <c_statement_addr_country></c_statement_addr_country>
            <c_addr_postcode></c_addr_postcode>
            <c_statement_addr_posttown></c_statement_addr_posttown>
            <c_e_inv>0</c_e_inv>
            <c_addr_county></c_addr_county>
            <c_remack_email>0</c_remack_email>
            <c_defvat></c_defvat>
            <c_refadv></c_refadv>
            <c_addr_posttown></c_addr_posttown>
            <c_pp_days>0</c_pp_days>
            <c_minord>0.00</c_minord>
            <c_termd>D</c_termd>
            <c_e_ackf>pdf</c_e_ackf>
            <c_web></c_web>
            <c_tel></c_tel>
</row>
</api>

2.2.3 GET_SUPPLIERS

To return a listing of all Purchase Ledger account definitions.

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<get>
           <command>GET_SUPPLIERS</command>
</get>
</api>

Name Type Example Description
s_id int(10) 1 Internal record ID
s_db_id int(10) 1 Internal database ID
s_acc varchar(8) PRE001 Unique supplier account code
s_name varchar(255) Prelude Supplier name
s_addr_1 varchar(255) Tondu Enterprise Centre First line of address
s_addr_2 varchar(255) Bryn Road Second line of address
s_addr_3 varchar(255)   Third line of address
s_addr_posttown varchar(255) Aberkenfig Post town of address
s_addr_county varchar(255) Bridgend County of address
s_addr_postcode varchar(20) CF32 9BS Postcode of address
s_addr_country varchar(255) United Kingdom Country of address
s_tel varchar(255) 01656 725800 Primary telephone number
s_tel2 varchar(255) Secondary telephone number
s_fax varchar(255) Fax number
s_web varchar(255) prelude.software Web site address
s_cont varchar(255) Ian Vickers Primary contact name
s_email varchar(255) ian@prelude.software Primary contact email address
s_cont2 varchar(255) Secondary contact name
s_email2 varchar(255) Secondary contact email address
s_crlim decimal(20,0) 5000.00 Credit limit
s_special_price char(2)   Not used
s_price_band char(1)   Not used
s_overall_discount decimal(5,2) 10.00 Default overall discount on all items received from this supplier
s_pp_discount decimal(5,2) 10.00 Prompt payment discount percentage
s_pp_days tinyint(3) 30 Prompt payment discount period in days
s_statf tinyint(1) 0 Not used
s_warn tinyint(1) 0 Not used
s_stop tinyint(1) 0 Not used
s_termd char(1) D Payment term period, D (days), M (months), C (calendar months)
s_termn decimal(5,0) 30 Number of payment term periods
s_comment varchar(255) Must sign for deliveries Optional comment
s_vatreg varchar(15) GB 11 1111 111 VAT registration number, if applicable
s_country char(3) DE Country code for VAT purposes
s_defvat char(1) 1 Default VAT code for transactions
s_defanal varchar(8) PU01 Default Nominal analysis for transactions
s_minord decimal(20,2) 0 Not used
s_vatinc tinyint(1) 0 VAT inclusive/exclusive pricing: 0/1
s_e_ack tinyint(1) 0 Send supplier purchase orders by email: 0/1
s_e_acka varchar(255) ian@prelude.software Supplier purchase orders by email: email address
s_e_ackf char(3) pdf Supplier purchase orders by email: document format
s_e_inv tinyint(1) 0 Not used
s_e_inva varchar(255) ian@prelude.software Not used
s_e_invf varchar(3) pdf Not used
s_remadv char(1) Y Produce supplier remittance advices: N/Y/A or blank to use Purchase Ledger default
s_remadv_email tinyint(1) 0 Send supplier remittance advices by email: 0/1
s_remadv_email_addr varchar(255) ian@prelude.software Supplier remittance advices by email: email address
s_remadv_format char(3) pdf Supplier remittance advices by email: document format
s_refack char(1) Y Produce supplier refund acknowledgements: N/Y/A or blank to use Purchase Ledger default
s_refack_email tinyint(1) 0 Send supplier refund acknowledgements by email: 0/1
s_refack_email_addr varchar(255) ian@prelude.software Supplier refund acknowledgements by email: email address
s_refack_format char(3) pdf Supplier refund acknowledgements by email: document format
s_e_stat tinyint(1) 0 Not used
s_e_stata varchar(255) ian@prelude.software Not used
s_e_statf char(3) pdf Not used
s_statement_cont varchar(255)   Not used
s_statement_addr_1 varchar(255)   Not used
s_statement_addr_2 varchar(255)   Not used
s_statement_addr_3 varchar(255)   Not used
s_statement_addr_posttown varchar(255)   Not used
s_statement_addr_county varchar(255)   Not used
s_statement_addr_postcode varchar(20)   Not used
s_statement_addr_country varchar(255)   Not used
s_notes text   Optional detailed notes
s_ddcrm_comp_id int(10) -1 ID of linked company in CRM database
s_ddcrm_cont_id int(10) -1 ID of linked contact in CRM database
s_deleted tinyint(1) 0 This supplier account has been deleted
s_modified timestamp 2015-01-19 12:00:00 System datetime this record was last modified

Example response:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<datetime>2015-01-19 12:00:00</datetime>
<success>1</success>
<number_of_rows>1</number_of_rows>
<table>ddwe_supplier</table>
<row>
            <s_addr_2></s_addr_2>
            <s_e_stata></s_e_stata>
            <s_statement_addr_county></s_statement_addr_county>
            <s_statement_addr_posttown></s_statement_addr_posttown>
            <s_defvat></s_defvat>
            <s_tel></s_tel>
            <s_remadv></s_remadv>
            <s_addr_posttown></s_addr_posttown>
            <s_remadv_format>pdf</s_remadv_format>
            <s_db_id>0</s_db_id>
            <s_refack></s_refack>
            <s_vatreg></s_vatreg>
            <s_acc>SUPP001</s_acc>
            <s_statement_addr_1></s_statement_addr_1>
            <s_e_ackf>pdf</s_e_ackf>
            <s_name>Supplier Number One</s_name>
            <s_web></s_web>
            <s_refack_format></s_refack_format>
            <s_addr_country></s_addr_country>
            <s_deleted>0</s_deleted>
            <s_addr_county></s_addr_county>
            <s_e_acka></s_e_acka>
            <s_notes></s_notes>
            <s_e_statf></s_e_statf>
            <s_comment></s_comment>
            <s_stop>0</s_stop>
            <s_statf>0</s_statf>
            <s_country></s_country>
            <s_refack_email>0</s_refack_email>
            <s_price_band></s_price_band>
            <s_warn>0</s_warn>
            <s_modified>2015-01-13 13:36:53</s_modified>
            <s_statement_addr_2></s_statement_addr_2>
            <s_tel2></s_tel2>
            <s_addr_1></s_addr_1>
            <s_statement_addr_postcode></s_statement_addr_postcode>
            <s_statement_addr_country></s_statement_addr_country>
            <s_termn>0</s_termn>
            <s_crlim>0</s_crlim>
            <s_minord>0.00</s_minord>
            <s_e_inva></s_e_inva>
            <s_termd>D</s_termd>
            <s_special_price></s_special_price>
            <s_e_invf>pdf</s_e_invf>
            <s_statement_addr_3></s_statement_addr_3>
            <s_e_inv>0</s_e_inv>
            <s_statement_cont></s_statement_cont>
            <s_email></s_email>
            <s_email2></s_email2>
            <s_defanal></s_defanal>
            <s_overall_discount>0.00</s_overall_discount>
            <s_ddcrm_cont_id>-1</s_ddcrm_cont_id>
            <s_ddcrm_comp_id>-1</s_ddcrm_comp_id>
            <s_pp_discount>0.00</s_pp_discount>
            <s_remadv_email_addr></s_remadv_email_addr>
            <s_cont2></s_cont2>
            <s_id>1</s_id>
            <s_remadv_email>0</s_remadv_email>
            <s_cont></s_cont>
            <s_refack_email_addr></s_refack_email_addr>
            <s_e_stat>0</s_e_stat>
            <s_vatinc>0</s_vatinc>
            <s_e_ack>0</s_e_ack>
            <s_addr_postcode></s_addr_postcode>
            <s_addr_3></s_addr_3>
            <s_pp_days>0</s_pp_days>
            <s_fax></s_fax>
</row>
</api>

2.2.4 GET_PRODUCTS

To return a listing of all Products, Services and Descriptions definitions.

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<get>
           <command>GET_PRODUCTS</command>
</get>
</api>

Name Type Example Description
pf_id int(10) 1 Internal record ID
pf_db_id int(10) 1 Internal database ID
pf_code varchar(16) PROD001 Unique product code
pf_type char(1) P Product type, P (Product), S (Service), D (Description)
pf_desc varchar(255) My Product Name Product name or description
pf_ldesc varchar(255) This is the name of my product Product long description
pf_line_notes text Enter notes that can be used to populate transaction line-item notes Product line notes
pf_anal varchar(8) SA01 Default Nominal Code for Sales Invoices/Credit Notes
pf_banal varchar(8) PU01 Default Nominal Code for Purchase Invoices/Credit Notes
pf_cost decimal(20,2) 100.00 Not used
pf_xcost decimal(20,2) 100.00 Standard buying price
pf_acost decimal(20,2) Not used
pf_sell decimal(20,2) 200.00 Standard selling price
pf_sell_01 decimal(20,2) 195.00 Special selling price 1
pf_sell_02 decimal(20,2) 190.00 Special selling price 2
pf_sell_03 decimal(20,2) 185.00 Special selling price 3
pf_sell_04 decimal(20,2) 180.00 Special selling price 4
pf_sell_05 decimal(20,2) 175.00 Special selling price 5
pf_sell_06 decimal(20,2) 170.00 Special selling price 6
pf_sell_07 decimal(20,2) 165.00 Special selling price 7
pf_sell_08 decimal(20,2) 160.00 Special selling price 8
pf_sell_09 decimal(20,2) 155.00 Special selling price 9
pf_sell_10 decimal(20,2) 150.00 Special selling price 10
pf_factor decimal(4,0) 1 Selling factor, for products sold in lots and bought individually
pf_bfactor decimal(4,0) 12 Buying factor, for products bought in lots and sold individually
pf_unit varchar(10) BOTTLE Selling unit
pf_bunit varchar(10) CASE Buying unit
pf_disc_a decimal(20,2) 5% Discount band A
pf_disc_b decimal(20,2) 10% Discount band B
pf_disc_c decimal(20,2) 15% Discount band C
pf_disc_d decimal(20,2) 20% Discount band D
pf_disc_e decimal(20,2) 25% Discount band E
pf_vatcode char(1) 1 Default VAT code
pf_cat char(2) C1 Product Category
pf_commod varchar(8) 0406 Intrastat commodity code
pf_onhold tinyint(1) 0 Product is on hold and not for sale (0/1)
pf_promo_price decimal(20,2) 140.00 Promotion period selling price
pf_promo_sdate date 01/12/2019 Promotion period start date
pf_promo_edate date 31/12/2019 Promotion period end date
pf_notes text These are detailed notes, e.g. product specifications Detailed product notes
pf_deleted tinyint(3) 0 This product has been deleted (0/1)
pf_modified timestamp CURRENT_TIMESTAMP System datetime this record was last modified

Example response:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<datetime>2015-01-19 12:00:00</datetime>
<success>1</success>
<number_of_rows>1</number_of_rows>
<table>ddwe_product</table>
<row>
           <pf_id>1</pf_id>
           <pf_db_id>1</pf_db_id>
           <pf_code>PROD001</pf_code>
           <pf_type>P</pf_type>
           <pf_desc>My Product Name</pf_desc>
           <pf_ldesc>This is the name of my product</pf_ldesc>
           <pf_line_notes>Enter text to populate transaction line-item notes</pf_line_notes>
           <pf_anal>SA01</pf_anal>
           <pf_banal>PU01</pf_banal>
           <pf_cost></pf_cost>
           <pf_xcost>100.00</pf_xcost>
           <pf_acost></pf_acost>
           <pf_sell>200.00</pf_sell>
           <pf_sell_01>195.00</pf_sell_01>
           <pf_sell_02>190.00</pf_sell_02>
           <pf_sell_03>185.00</pf_sell_03>
           <pf_sell_04>180.00</pf_sell_04>
           <pf_sell_05>175.00</pf_sell_05>
           <pf_sell_06>170.00</pf_sell_06>
           <pf_sell_07>165.00</pf_sell_07>
           <pf_sell_08>160.00</pf_sell_08>
           <pf_sell_09>155.00</pf_sell_09>
           <pf_sell_10>150.00</pf_sell_10>
           <pf_factor>1</pf_factor>
           <pf_bfactor>12</pf_bfactor>
           <pf_unit>Bottle</pf_unit>
           <pf_bunit>Case</pf_bunit>
           <pf_disc_a>5%</pf_disc_a>
           <pf_disc_b>10%</pf_disc_b>
           <pf_disc_c>15%</pf_disc_c>
           <pf_disc_d>20%</pf_disc_d>
           <pf_disc_e>25%</pf_disc_e>
           <pf_vatcode>1</pf_vatcode>
           <pf_cat>C1</pf_cat>
           <pf_commod>0406</pf_commod>
           <pf_onhold>0</pf_onhold>
           <pf_promo_price>140.00</pf_promo_price>
           <pf_promo_sdate>01/12/2016</pf_promo_sdate>
           <pf_promo_edate>31/12/2016</pf_promo_edate>
           <pf_notes>These are detailed notes, e.g. product specifications</pf_notes>
           <pf_deleted>0</pf_deleted>
           <pf_modified>2016-01-01 12:00:00</pf_modified>
</row>
</api>

2.2.5 GET_CUSTOMERPODSETTINGS

To return the settings required to operate a remote application (“app”) to process on-site Proof of Delivery (POD) documents.

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<get>
           <command>GET_CUSTOMERPODSETTINGS</command>
</get>
</api>

2.2.5.1 Reasons Table

The Reasons table can be used as the source of a picklist to be displayed in the app’s User Interface (“UI”), from which the user selects a reason why a delivery was not made or was made without a signature being provided by the customer.  With each call of this command, the app should create/repopulate/refresh a table named Reasons on the app device, overwriting existing content if it exists, with the data in the pod_reasons table from the response that is returned (see Example response below).

Name Type Example Description
reason_id int(10) 101 Database ID of the Reason table item
reason_text varchar(255) “Agreed by customer” Database content of the Reason table item

Example response:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<datetime>2018-10-31 12:00:00</datetime>
<success>1</success>
<number_of_rows>3</number_of_rows>
<table>pod_reasons</table>
<row>
           <reason_id>520</reason_id>
           <reason_text>Agreed by customer</reason_text>
</row>
<row>
           <reason_id>521</reason_id>
           <reason_text>No-one on site</reason_text>
</row>
<row>
           <reason_id>522</reason_id>
           <reason_text>Other</reason_text>
</row>
</api>

2.2.6 GET Conditions

Every GET command may be modified by setting a number of conditions, which will have the effect of filtering the data that is returned by the command. This is probably best illustrated by an example. Say you want to retrieve a list of customers whose details have been modified after a certain date. The following XML will achieve this response:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<get>
           <command>GET_CUSTOMERS</command>
           <condition>
                       <field>c_modified</field>
                       <operator>gt</operator>
                       <value>2015-01-19 12:00:00</value>
         </condition>
</get>
</api>

See that the condition element is applied after the command element within the get block. The condition has three components, which should be quite clear to understand:

  • <field>, which is the field name as specified in the relevant section above
  • <operator>, which is a logical operator as specified in the table immediately below
  • <value>, which must be in the same format as the specified field

Note that the condition element can also be written in a single line:

<condition field=”c_modified” operator=”gt” value=”2015-01-19 12:00:00″ />

OperatorDescriptionApplied to
gtIs greater thanInteger, number, date, time, datetime fields
ltIs less thanInteger, number, date, time, datetime fields
equalIs equal toInteger, number, date, time, datetime, text fields
notequalIs not equal toInteger, number, date, time, datetime, text fields
likeIncludesText fields
notlikeDoes not includeText fields

Text operators are not case sensitive, i.e. <value>text</value> and <value>TEXT</value> would return the same result.

Multiple conditions are applied with the AND logical operator, i.e. a record will be returned only if all conditions are met.

2.3 Send data to Framework: Post Commands

This section describes the commands that are available to a third party to send data in XML format to the specified database.

Please contact us if you find that you need commands that are not included in this document.

If the XML passes authentication, the target database will be updated with the data being sent and a success response code in XML format will be returned.

Each sub-section includes an example complete XML for the individual command and a table that specifies the format of the data that is submitted.

The individual post commands, <post>…</post>, may be included in a larger XML submission of multiple commands.

2.3.1 CUSTOMER_NEW

Create a new customer with basic records:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>CUSTOMER_NEW</command>
           <customer_account>DIA001</customer_account>
           <customer_name></customer_name>
           <customer_addr_1></customer_addr_1>
           <customer_addr_2></customer_addr_2>
           <customer_addr_3></customer_addr_3>
          <customer_posttown></customer_posttown>
          <customer_county></customer_county>
          <customer_postcode></customer_postcode>
          <customer_country></customer_country>
          <customer_tel></customer_tel>
          <customer_contact></customer_contact>
          <customer_email></customer_email>
</post>
</api>

<customer_account /> and <customer_name /> are required but all others are optional. <customer_account /> must contain only alphanumeric characters unless it contains specifically [auto*], where * can be any number of other characters, in which case an account code will be created automatically in the form XYZnnn where XYZ is the first three alphanumeric characters of <customer_name /> (so this must contain at least three alphanumeric characters) and nnn is an incrementing integer to ensure uniqueness of the created account code.

Example response:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<datetime>2018-11-01 12:00:00</datetime>
<response>
           <success>1</success>
          <c_id>n</c_id>
          <c_db_id>n</c_db_id>
          <c_acc>XYZnnn</c_acc>
           <c_acc_auto>auto*</c_acc_auto>
          <c_modified>timestamp</c_modified>
</response>
</api>

From this response the database record number, <c_id>, databse number, <c_db_id>, autogenerated account code, <c_acc>, the [auto*] string that triggered it, <c_acc_auto>, and the record’s timestamp, <c_modified>, are identified to enable you to update your local database accordingly.

Name Type Example Description
customer_account varchar(8) PRE001 The customer account code, unique
customer_name varchar(100) Prelude The customer name
customer_addr_1 varchar(100) Tondu Enterprise Centre Address line 1
customer_addr_2 varchar(100) Bryn Road Optional line 2
customer_addr_3 varchar(100) Aberkenfig Optional line 3
customer_posttown varchar(100) Bridgend Postal town
customer_county varchar(100) Glamorgan Postal county
customer_postcode varchar(20) CF32 9BS Postcode
customer_country varchar(100) Wales Postal country
customer_tel varchar(100) 01656 725800 Primary telephone number
customer_contact varchar(100) Dr Vickers Named contact
customer_email varchar(100) accounts@prelude.software Email address for all customer communications

2.3.2 CUSTOMER_EDIT

Edit an existing customer, updating all fields and removing content if blank:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>CUSTOMER_EDIT</command>
           <customer_account>DIA001</customer_account>
           <customer_name></customer_name>
           <customer_addr_1></customer_addr_1>
           <customer_addr_2></customer_addr_2>
           <customer_addr_3></customer_addr_3>
          <customer_posttown></customer_posttown>
           <customer_county></customer_county>
          <customer_postcode></customer_postcode>
          <customer_country></customer_country>
          <customer_tel></customer_tel>
           <customer_contact></customer_contact>
           <customer_email></customer_email>
</post>
</api>

Name Type Example Description
customer_account varchar(8) PRE001 The customer account code, unique
customer_name varchar(100) Prelude The customer name
customer_addr_1 varchar(100) Tondu Enterprise Centre Address line 1
customer_addr_2 varchar(100) Bryn Road Optional line 2
customer_addr_3 varchar(100) Aberkenfig Optional line 3
customer_posttown varchar(100) Bridgend Postal town
customer_county varchar(100) Glamorgan Postal county
customer_postcode varchar(20) CF32 9BS Postcode
customer_country varchar(100) Wales Postal country
customer_tel varchar(100) 01656 725800 Primary telephone number
customer_contact varchar(100) Dr Vickers Named contact
customer_email varchar(100) accounts@prelude.software Email address for all customer communications

2.3.3 CUSTOMER_DELETE

Delete an existing customer, which has no transactions. A customer account with existing transactions cannot be deleted:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>CUSTOMER_DELETE</command>
           <customer_account>PRE001</customer_account>
</post>
</api>

Name Type Example Description
customer_account varchar(8) PRE001 Customer to be deleted

2.3.4 CUSTOMER_INVOICE

Produce a customer invoice with multiple lines, optionally using products/services:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>CUSTOMER_INVOICE</command>
           <post_account>PRE001</post_account>
           <post_date>19/01/2019</post_date>
           <post_invno>100025</post_invno>
           <post_ref_1>Order 159</post_ref_1>
           <post_ref_2>Ebay Sale</post_ref_2>
           <post_notes>Notes shown on invoice footer</post_notes>
           <line_item>
                      <line_number>1</line_number>
                      <line_code>PROD001</line_code>
                      <line_description>Description of item</line_description>
                      <line_quantity>3</line_quantity>
                      <line_unit_price>12.50</line_unit_price>
                      <line_analysis>SA01</line_analysis>
                      <line_vatcode>1</line_vatcode>
           </line_item>
           <line_item>
                      <line_number>2</line_number>
                      <line_code>PROD002</line_code>
                      <line_description>Description of item</line_description>
                      <line_quantity>1</line_quantity>
                      <line_unit_price>50.00</line_unit_price>
                      <line_analysis>SA02</line_analysis>
                       <line_vatcode>1</line_vatcode>
           </line_item>
</post>
</api>

Name Type Example Description
post_account varchar(8) PRE001 The customer account code
post_date Date 19/01/2019 The transaction date
post_invno varchar(16) 100025 The invoice number or [auto]
post_ref_1 varchar(20) Order 159 A reference of your choice, optional
post_ref_2 varchar(20) Ebay Sale A reference of your choice, optional
post_notes varchar(250) Thank you for your custom Notes appear on the invoice footer

Lines can be repeated for multi-line invoices, a minimum of one is always required:

Name Type Example Description
line_number int(13) 1 Optional number to uniquely identify this line item
line_code varchar(18) PROD001 The code of the product or service
line_description varchar(250) Item, short description Description of item *
line_quantity decimal(12,3) 3 Number of items, multiplier
line_unit_price decimal(20,2) 12.50 Cost of individual item *
line_analysis varchar(8) SA01 Nominal ledger code to which invoice line is analysed or [auto] *
line_vatcode varchar(1) 1 The VAT code: 0-9, A-Z (N is outside scope) or [auto] *

* <line_code> may be omitted with considerations.  If <line_code> is included with a valid Product code, these fields can be omitted and their values will be obtained from the Product file details in our database.  If <line_code> is omitted, these fields cannot be omitted.  If these fields are included, their values will be used, whether <line_code> is omitted or included.

2.3.5 CUSTOMER_CREDIT_NOTE

Produce a customer credit note with multiple lines, optionally using products/services:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>CUSTOMER_CREDIT_NOTE</command>
           <post_account>PRE001</post_account>
           <post_date>19/01/2019</post_date>
           <post_invno>100026</post_invno>
           <post_ref_1>Order 159</post_ref_1>
           <post_ref_2>Ebay Refund</post_ref_2>
           <post_notes>Notes shown on invoice footer</post_notes>
           <line_item>
                      <line_number>1</line_number>
                      <line_code>PROD001</line_code>
                      <line_description>Description of item</line_description>
                      <line_quantity>3</line_quantity>
                      <line_unit_price>12.50</line_unit_price>
                      <line_analysis>SA01</line_analysis>
                      <line_vatcode>1</line_vatcode>
           </line_item>
</post>
</api>

Name Type Example Description
post_account varchar(8) PRE001 The customer account code
post_date Date 19/01/2019 The transaction date
post_invno varchar(16) 100026 The invoice number or [auto]
post_ref_1 varchar(20) Order 159 A reference of your choice, optional
post_ref_2 varchar(20) Ebay Refund A reference of your choice, optional
post_notes varchar(250) Thank you for your custom Notes appear on the invoice footer

Lines can be repeated for multi-line invoices, a minimum of one is always required:

Name Type Example Description
line_number int(13) 1 Optional number to uniquely identify this line item
line_code varchar(18) PROD001 The code of the product or service
line_description varchar(250) Item, short description Description of item *
line_quantity decimal(12,3) 3 Number of items, multiplier
line_unit_price decimal(20,2) 12.50 Cost of individual item *
line_analysis varchar(8) SA01 Nominal ledger code to which invoice line is analysed or [auto] *
line_vatcode varchar(1) 1 The VAT code: 0-9, A-Z (N is outside scope) or [auto] *

* <line_code> may be omitted with considerations.  If <line_code> is included with a valid Product code, these fields can be omitted and their values will be obtained from the Product file details in our database.  If <line_code> is omitted, these fields cannot be omitted.  If these fields are included, their values will be used, whether <line_code> is omitted or included.

2.3.6 CUSTOMER_POD

Create a new customer Proof of Delivery (POD) document:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>CUSTOMER_POD</command>
           <barcodes></barcodes>
           <signed></signed>
           <paid></paid>
           <method></method>
           <scan></scan>
           <amount></amount>
           <reason></reason>
           <notes></notes>
           <photo></photo>
           <name></name>
           <signature></signature>
           <created></created>
           <submitted></submitted>
</post>
</api>

Name Type Example Description
barcodes varchar(255) 123456,abcdef,789xyz Scanned barcodes stored as comma-delimited text string
signed char(1) Y or N To identify whether the customer has signed for the Job
paid char(1) Y or N To identify whether the customer has paid for the Job
method varchar(100) “Cash” or “Cheque” To identify how the customer has paid for the Job
scan varchar(100) 123456 Single scanned barcode
amount Currency £9,999.99 £2,972.78 The amount the customer has paid for this Job
reason Integer(10) 501 Code of the selected reason for delivery without signature
notes varchar(255) “Building is closed” Notes entered by the user to provide more information
photo JPG   Picture taken of goods delivered without signature
name varchar(100) “Bob James” Name of customer staff member signing for delivery
signature JPG   Image of signature entered on device screen
created date/time 2018-10-27 11:46:05 System date/time when the record is added to Joblog table
submitted date/time 2018-10-27 11:56:05 System date/time when the record is synced with API

2.3.7 SUPPLIER_NEW

Create a new supplier with basic records:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>SUPPLIER_NEW</command>
           <supplier_account>DIA001</supplier_account>
           <supplier_name></supplier_name>
           <supplier_addr_1></supplier_addr_1>
           <supplier_addr_2></supplier_addr_2>
           <supplier_addr_3></supplier_addr_3>
           <supplier_posttown></supplier_posttown>
          <supplier_county></supplier_county>
          <supplier_postcode></supplier_postcode>
          <supplier_country></supplier_country>
           <supplier_tel></supplier_tel>
           <supplier_contact></supplier_contact>
           <supplier_email></supplier_email>
</post>
</api>

<supplier_account /> and <supplier_name /> are required but all others are optional. <supplier_account /> must contain only alphanumeric characters unless it contains specifically [auto*], where * can be any number of other characters, in which case an account code will be created automatically in the form XYZnnn where XYZ is the first three alphanumeric characters of <supplier_name /> (so this must contain at least three alphanumeric characters) and nnn is an incrementing integer to ensure uniqueness of the created account code.

Example response:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<datetime>2018-11-01 12:00:00</datetime>
<response>
           <success>1</success>
          <s_id>n</s_id>
          <s_db_id>n</s_db_id>
          <s_acc>XYZnnn</s_acc>
           <s_acc_auto>auto*</s_acc_auto>
          <s_modified>timestamp</s_modified>
</response>
</api>

From this response the database record number, <s_id>, database number, <s_db_id>, autogenerated account code, <s_acc>, the [auto*] string that triggered it, <s_acc_auto>, and the record’s timestamp, <s_modified>, are identified to enable you to update your local database accordingly.

Name Type Example Description
supplier_account varchar(8) PRE001 The supplier account code, unique
supplier_name varchar(100) Prelude The supplier name
supplier_addr_1 varchar(100) Tondu Enterprise Centre Address line 1
supplier_addr_2 varchar(100) Bryn Road Optional line 2
supplier_addr_3 varchar(100) Aberkenfig Optional line 3
supplier_posttown varchar(100) Bridgend Postal town
supplier_county varchar(100) Glamorgan Postal county
supplier_postcode varchar(20) CF32 9BS Postcode
supplier_country varchar(100) Wales Postal country
supplier_tel varchar(100) 01656 725800 Primary telephone number
supplier_contact varchar(100) Dr Vickers Named contact
supplier_email varchar(100) accounts@prelude.software Email address for all supplier communications

2.3.8 SUPPLIER_EDIT

Edit an existing supplier, updating all fields and removing content if blank:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>SUPPLIER_EDIT</command>
           <supplier_account>PRE001</supplier_account>
           <supplier_name></supplier_name>
           <supplier_addr_1></supplier_addr_1>
           <supplier_addr_2></supplier_addr_2>
           <supplier_addr_3></supplier_addr_3>
           <supplier_posttown></supplier_posttown>
          <supplier_county></supplier_county>
          <supplier_postcode></supplier_postcode>
          <supplier_country></supplier_country>
           <supplier_tel></supplier_tel>
           <supplier_contact></supplier_contact>
           <supplier_email></supplier_email>
</post>
</api>

Name Type Example Description
supplier_account varchar(8) PRE001 The supplier account code, unique
supplier_name varchar(100) Prelude The supplier name
supplier_addr_1 varchar(100) Tondu Enterprise Centre Address line 1
supplier_addr_2 varchar(100) Bryn Road Optional line 2
supplier_addr_3 varchar(100) Aberkenfig Optional line 3
supplier_posttown varchar(100) Bridgend Postal town
supplier_county varchar(100) Glamorgan Postal county
supplier_postcode varchar(20) CF32 9BS Postcode
supplier_country vrachar(100) Wales Postal country
supplier_tel varchar(100) 01656 725800 Primary telephone number
supplier_contact varchar(100) Dr Vickers Named contact
supplier_email varchar(100) accounts@prelude.software Email address for all supplier communications

2.3.9 SUPPLIER_DELETE

Delete an existing supplier, which has no transactions. A supplier account with existing transactions cannot be deleted:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>SUPPLIER_DELETE</command>
           <supplier_account>PRE001</supplier_account>
</post>
</api>

Name Type Example Description
supplier_account varchar(8) PRE001 Supplier to be deleted

2.3.10 SUPPLIER_INVOICE

Produce a supplier invoice with multiple lines, optionally using products/services:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>SUPPLIER_INVOICE</command>
           <post_account>PRE001</post_account>
           <post_date>19/01/2019</post_date>
           <post_invno>100025</post_invno>
           <post_ref_1>Order 159</post_ref_1>
           <post_ref_2>Ebay Sale</post_ref_2>
           <post_notes>Notes shown on invoice footer</post_notes>
           <line_item>
                      <line_number>1</line_number>
                      <line_code>PROD001</line_code>
                      <line_description>Description of item</line_description>
                      <line_quantity>3</line_quantity>
                      <line_unit_price>12.50</line_unit_price>
                      <line_analysis>PU01</line_analysis>
                      <line_vatcode>1</line_vatcode>
           </line_item>
</post>
</api>

Name Type Example Description
post_account varchar(8) PRE001 The customer account code
post_date date 19/01/2019 The transaction date
post_invno varchar(16) 100025 The invoice number or [auto]
post_ref_1 varchar(20) Order 159 A reference of your choice, optional
post_ref_2 varchar(20) Ebay Sale A reference of your choice, optional
post_notes varchar(250) Thank you for your custom Notes appear on the invoice footer

Lines can be repeated for multi-line invoices, a minimum of one is always required:

Name Type Example Description
line_number int(13) 1 Optional number to uniquely identify this line item
line_code varchar(18) PROD001 The code of the product or service
line_description varchar(250) Item, short description Description of item *
line_quantity decimal(12,3) 3 Number of items, multiplier
line_unit_price decimal(20,2) 12.50 Cost of individual item *
line_analysis varchar(8) PU01 Nominal ledger code to which invoice line is analysed or [auto] *
line_vatcode varchar(1) 1 The VAT code: 0-9, A-Z (N is outside scope) or [auto]*

* <line_code> may be omitted with considerations.  If <line_code> is included with a valid Product code, these fields can be omitted and their values will be obtained from the Product file details in our database.  If <line_code> is omitted, these fields cannot be omitted.  If these fields are included, their values will be used, whether <line_code> is omitted or included.

2.3.11 SUPPLIER_CREDIT_NOTE

Produce a supplier credit note with multiple lines, optionally using products/services:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>SUPPLIER_CREDIT_NOTE</command>
           <post_account>PRE001</post_account>
           <post_date>19/01/2019</post_date>
           <post_invno>100026</post_invno>
           <post_ref_1>Order 159</post_ref_1>
           <post_ref_2>Ebay Refund</post_ref_2>
           <post_notes>Notes shown on invoice footer</post_notes>
           <line_item>
                      <line_number>1</line_number>
                      <line_code>PROD001</line_code>
                      <line_description>Description of item</line_description>
                      <line_quantity>3</line_quantity>
                      <line_unit_price>12.50</line_unit_price>
                      <line_analysis>PU01</line_analysis>
                      <line_vatcode>1</line_vatcode>
           </line_item>
</post>
</api>

Name Type Example Description
post_account varchar(8) PRE001 The supplier account code
post_date date 19/01/2019 The transaction date
post_invno varchar(16) 100026 The invoice number or [auto]
post_ref_1 varchar(20) Order 159 A reference of your choice, optional
post_ref_2 varchar(20) Ebay Refund A reference of your choice, optional
post_notes varchar(250) Thank you for your custom Notes appear on the invoice footer

Lines can be repeated for multi-line invoices, a minimum of one is always required:

Name Type Example Description
line_number int(13) 1 Optional number to uniquely identify this line item
line_code varchar(18) PROD001 The code of the product or service
line_description varchar(250) Item, short description Description of item *
line_quantity decimal(12,3) 3 Number of items, multiplier
line_unit_price decimal(20,2) 12.50 Cost of individual item *
line_analysis varchar(8) PU01 Nominal ledger code to which invoice line is analysed or [auto] *
line_vatcode varchar(1) 1 The VAT code: 0-9, A-Z (N is outside scope) or [auto] *

* <line_code> may be omitted with considerations.  If <line_code> is included with a valid Product code, these fields can be omitted and their values will be obtained from the Product file details in our database.  If <line_code> is omitted, these fields cannot be omitted.  If these fields are included, their values will be used, whether <line_code> is omitted or included.

2.3.12 PRODUCT_NEW

Create a new product, service or description:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>PRODUCT_NEW</command>
           <product_code>PROD001</product_code>
           <product_description> Description of item</product_description>
           <product_description_extra>Further information</product_description_extra>
           <product_vatcode>1</product_vatcode>
           <product_buying_price>7.25</product_buying_price>
           <product_selling_price>12.50</product_selling_price>
           <product_buying_analysis>PU01</product_buying_analysis>
           <product_selling_analysis>SA01</product_selling_analysis>
</post>
</api>

Name Type Example Description
product_code varchar(16) PROD001 The code of the product or service, unique
product_type varchar(1) [ P | S | D ] Item is a product, a service or a description *
product_description varchar(250) Item, short description Description of item
product_description_extra varchar(250) Further information Additional information
product_vatcode varchar(1) 1 The VAT code: 0-9, A-Z (N is outside scope)
product_buying_price decimal(20,2) 7.25 Default price of item when purchased
product_selling_price decimal(20,2) 12.50 Default price of item when sold
product_buying_analysis varchar(8) PU01 Nominal ledger code to which purchases of item are analysed
product_selling_analysis varchar(8) SA01 Nominal ledger code to which sales of item are analysed

* When a product_type of  D is used for description, the vatcode, price and analysis fields are not required and will be ignored.

2.3.13 PRODUCT_EDIT

Edit an existing product, service or description:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>PRODUCT_EDIT</command>
           <product_code>PROD001</product_code>
           <product_description> Description of item</product_description>
           <product_description_extra>Further information</product_description_extra>
           <product_vatcode>1</product_vatcode>
           <product_buying_price>7.25</product_buying_price>
           <product_selling_price>12.50</product_selling_price>
           <product_buying_analysis>PU01</product_buying_analysis>
           <product_selling_analysis>SA01</product_selling_analysis>
</post>
</api>

Name Type Example Description
product_code varchar(16) PROD001 The code of the product or service, unique
product_type varchar(1) [ P | S | D ] Item is a product, a service or a description *
product_description varchar(250) Item, short description Description of item
product_description_extra varchar(250) Further information Additional information
product_vatcode varchar(1) 1 The VAT code: 0-9, A-Z (N is outside scope)
product_buying_price decimal(20,2) 7.25 Default price of item when purchased
product_selling_price decimal(20,2) 12.50 Default price of item when sold
product_buying_analysis varchar(8) PU01 Nominal ledger code to which purchases of item are analysed
product_selling_analysis varchar(8) SA01 Nominal ledger code to which sales of item are analysed

* When a product_type of  D is used for description, the vatcode, price and analysis fields are not required and will be ignored.

2.3.14 PRODUCT_DELETE

Delete an existing product, service or description:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>PRODUCT_DELETE</command>
           <product_code>PROD001</product_code>
</post>
</api>

Name Type Example Description
product_code varchar(16) PROD001 Code of product to be deleted

2.3.15 RECEIPT_CUSTOMER

To post money received from a Sales Ledger account to a designated bank account.

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>RECEIPT_CUSTOMER</command>
           <post_date>19/01/2019</post_date>
           <post_account>PRE001</post_account>
           <post_ref>100159</post_ref>
           <post_amount>1000.00</post_amount>
           <post_bank>CA04</post_bank>
</post>
</api>

Name Type Example Description
post_date date 19/01/2019 The transaction date
post_account varchar(8) PRE001 The customer account code
post_ref varchar(16) 100159 A reference of your choice
post_amount decimal(20,2) 1000.00 The receipt amount
post_bank varchar(8) CA04 Nominal ledger code, must be designated bank

2.3.16 RECEIPT_NOMINAL

To post money received to a designated bank account analysed to a specified Nominal Ledger account.

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>RECEIPT_NOMINAL</command>
           <post_date>19/01/2019</post_date>
           <post_ref>January 2019</post_ref>
           <post_detail>Expenses refund</post_detail>
           <post_vatcode>1</post_vatcode>
           <post_vat>200.00</post_vat>
           <post_analysis>EA08</post_analysis>
           <post_bank>CA04</post_bank>
</post>
</api>

Name Type Example Description
post_date date 19/01/2019 The transaction date
post_ref varchar(16) January 2019 A reference of your choice
post_detail varchar(255) Expenses refund Optional detailed description
post_gross decimal(20,2) 1200.00 The receipt amount, including VAT if appropriate
post_vatcode varchar(1) 1 The VAT code: 0-9, A-Z (N is outside scope)
post_vat decimal(20,2) 200.00 The VAT amount
post_analysis varchar(8) EA08 Nominal ledger code to which receipt is analysed
post_bank varchar(8) CA04 Nominal ledger code, must be designated bank

2.3.17 RECEIPT_SUPPLIER

To post money received from a Purchase Ledger account to a designated bank account.

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>RECEIPT_SUPPLIER</command>
           <post_date>19/01/2019</post_date>
           <post_account>PRE001</post_account>
           <post_ref>100159</post_ref>
           <post_amount>1000.00</post_amount>
           <post_bank>CA04</post_bank>
</post>
</api>

Name Type Example Description
post_date Date 19/01/2019 The transaction date
post_account varchar(8) PRE001 The supplier account code
post_ref varchar(16) 100159 A reference of your choice
post_amount decimal(20,2) 1000.00 The receipt amount
post_bank varchar(8) CA04 Nominal ledger code, must be designated bank

2.3.18 RECEIPT_VATREFUND

To post receipt of a VAT refund to a designated bank account.

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>RECEIPT_VATREFUND</command>
           <post_date>19/01/2019</post_date>
           <post_ref>Q4 2018</post_ref>
           <post_amount>1000.00</post_amount>
           <post_bank>CA04</post_bank>
</post>
</api>

Name Type Example Description
post_date Date 19/01/2019 The transaction date
post_ref varchar(16) Q4 2018 A reference of your choice
post_amount decimal(20,2) 1000.00 The receipt amount
post_bank varchar(8) CA04 Nominal ledger code, must be designated bank

2.3.19 PAYMENT_CUSTOMER

To post money paid to a Sales Ledger account from a designated bank account.

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>PAYMENT_CUSTOMER</command>
           <post_date>19/01/2019</post_date>
           <post_account>PRE001</post_account>
           <post_ref>100159</post_ref>
           <post_amount>1000.00</post_amount>
           <post_bank>CA04</post_bank>
</post>
</api>

Name Type Example Description
post_date Date 19/01/2019 The transaction date
post_account varchar(8) PRE001 The customer account code
post_ref varchar(16) 100159 A reference of your choice
post_amount decimal(20,2) 1000.00 The payment amount
post_bank varchar(8) CA04 Nominal ledger code, must be designated bank

2.3.20 PAYMENT_NOMINAL

To post money paid from a designated bank account analysed to a specified Nominal Ledger account.

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>PAYMENT_NOMINAL</command>
           <post_date>19/01/2019</post_date>
           <post_ref>January 2019</post_ref>
           <post_detail>Expenses paid</post_detail>
           <post_gross>1200.00</post_gross>
           <post_vatcode>1</post_vatcode>
           <post_vat>200.00</post_vat>
           <post_analysis>EA08</post_analysis>
           <post_bank>CA04</post_bank>
</post>
</api>

Name Type Example Description
post_date date 19/01/2019 The transaction date
post_ref varchar(16) January 2019 A reference of your choice
post_detail varchar(255) Expenses paid Optional detailed description
post_gross decimal(20,2) 1200.00 The payment amount, including VAT if appropriate
post_vatcode varchar(1) 1 The VAT code: 0-9, A-Z (N is outside scope)
post_vat decimal(20,2) 200.00 The VAT amount
post_analysis varchar(8) EA08 Nominal ledger code to which payment is analysed
post_bank varchar(8) CA04 Nominal ledger code, must be designated bank

2.3.21 PAYMENT_SUPPLIER

To post money paid to a Purchase Ledger account from a designated bank account.

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>PAYMENT_SUPPLIER</command>
           <post_date>19/01/2019</post_date>
           <post_account>PRE001</post_account>
           <post_ref>100159</post_ref>
           <post_amount>1000.00</post_amount>
           <post_bank>CA04</post_bank>
</post>
</api>

Name Type Example Description
post_date date 19/01/2019 The transaction date
post_account varchar(8) PRE001 The supplier account code
post_ref varchar(16) 100159 A reference of your choice
post_amount decimal(20,2) 1000.00 The payment amount
post_bank varchar(8) CA04 Nominal ledger code, must be designated bank

2.3.22 PAYMENT_VATPAYMENT

To post payment of a VAT liability from a designated bank account.

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>PAYMENT_VATPAYMENT</command>
           <post_date>19/01/2019</post_date>
           <post_ref>Q4 2018</post_ref>
           <post_amount>1000.00</post_amount>
           <post_bank>CA04</post_bank>
</post>
</api>

Name Type Example Description
post_date date 19/01/2019 The transaction date
post_ref varchar(16) Q4 2018 A reference of your choice
post_amount decimal(20,2) 1000.00 The payment amount
post_bank varchar(8) CA04 Nominal ledger code, must be designated bank

2.3.23 BANK_DEPOSIT

Make a single bank deposit analysed to multiple receipts to individual customer, supplier and nominal accounts:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>BANK_DEPOSIT</command>
           <post_date>19/01/2019</post_date>
           <post_ref>PAIDIN123</post_ref>
           <post_amount>1000.00</post_amount>
           <post_bank>CA04</post_bank>
           <line_item>
                      <customer_account>PRE100</customer_account>
                      <customer_ref>000001</customer_ref>
                      <customer_amount>200.00</customer_amount>
           </line_item>
           <line_item>
                      <supplier_account>FR100</supplier_account>
                      <supplier_ref>000001</supplier_ref>
                      <supplier_amount>200.00</supplier_amount>
           </line_item>
           <line_item>
                      <nominal_account>EA01</nominal_account>
                      <nominal_ref>BT100</nominal_ref>
                      <nominal_gross>600.00</nominal_gross>
                      <nominal_vat>100.00</nominal_vat>
                      <nominal_vatcode>1</nominal_vatcode>
           </line_item>
</post>
</api>

Name Type Example Description
post_date date 19/01/2019 The transaction date
post_ref varchar(16) PAIDIN123 A reference of your choice
post_amount decimal(20,2) 1000.00 The deposit amount (sum of line items)
post_bank varchar(8) CA04 Receiving bank

Repeatable line items (only one type of customer/supplier/nominal per line_item record:

Name Type Example Description
customer_account varchar(8) PRE100 Sales ledger customer account code
customer_ref varchar(16) 000001 A reference for this line
customer_amount decimal(20,2) 200.00 The line amount
supplier_account varchar(8) FR100 Purchase ledger customer account code
supplier_ref varchar(16) 000001 A reference for this line
supplier_amount decimal(20,2) 200.00 The line amount
nominal_account varchar(8) EA01 Nominal ledger account code
nominal_ref varchar(16) BT100 A reference for this line
nominal_gross decimal(20,2) 600.00 The line amount
nominal_vat decimal(20,2) 100.00 The line VAT amount
nominal_vatcode varchar(1) 1 The VAT code: 0-9, A-Z (N is outside scope)

2.3.24 BANK_TRANSFER

To transfer money from one designated bank account (credit) to another designated bank account (debit):

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<post>
           <command>BANK_TRANSFER</command>
           <post_date>19/01/2019</post_date>
           <post_bank_from>CA04</post_bank_from>
           <post_bank_to>CA05</post_bank_to>
           <post_detail>Cash flow</post_detail>
           <post_amount>1000.00</post_amount>
</post>
</api>

Name Type Example Description
post_date date 19/01/2019 The transaction date
post_bank_from varchar(16) CA04 Nominal ledger code, must be designated bank: the paying bank account
Post_bank_to varchar(16) CA05 Nominal ledger code, must be designated bank: the receiving bank account
post_detail varchar(255) Cash flow Optional detailed description
post_amount decimal(20,2) 1000.00 The transfer amount

3. Release History

ReleaseDateDescriptionAuthorReview
1.0018/01/2015First releaseIVRM, JS
1.0111/01/2016Customer, Supplier, Product, Bank Deposits addedRMIV
1.0301/11/2018Customer Proof of Delivery (POD)IVRJ, RM
1.0327/11/2019Customer, Supplier enhanced with [auto], <condition>IVRM