Application Program Interface

[hide]

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:

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:

Name	Type	Example	Description
nt_id	int(10)	1	Internal record ID
nt_db_id	int(10)	0	Internal database ID
nt_code	varchar(8)	CA01	Nominal ledger code
nt_hdesc	varchar(20)	CURRENT ASSETS	Ledger header description
nt_desc	varchar(100)	STOCK	Ledger code description
nt_type	enum(‘B’,’P’,’’)	B	Type of account:Balance Sheet, Profit & Loss
nt_btype	enum(‘D’,’C’,’’)	D	Normally displayed as positive: Debit, Credit
nt_bank	tinyint(1)	0	Designated bank account: Yes (1), No (0)
nt_max_limit	decimal(10,2)	0	Overdraft/Credit limit for bank account
nt_control	tinyint(3)	0	System control account: Yes (1), No (0)
nt_status	tinyint(3)	1	Enabled (1), Disabled (0)
nt_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>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.

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)	[email protected]	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)	[email protected]	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)	[email protected]	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)	[email protected]	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)	[email protected]	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)	[email protected]	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.

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)	[email protected]	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)	[email protected]	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)	[email protected]	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)	[email protected]	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)	[email protected]	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)	[email protected]	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.

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.

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:

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:

Operator	Description	Applied to
gt	Is greater than	Integer, number, date, time, datetime fields
lt	Is less than	Integer, number, date, time, datetime fields
equal	Is equal to	Integer, number, date, time, datetime, text fields
notequal	Is not equal to	Integer, number, date, time, datetime, text fields
like	Includes	Text fields
notlike	Does not include	Text 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:

<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)	[email protected]	Email address for all customer communications

2.3.2 CUSTOMER_EDIT

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

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)	[email protected]	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:

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] *

2.3.6 CUSTOMER_POD

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

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:

<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)	[email protected]	Email address for all supplier communications

2.3.8 SUPPLIER_EDIT

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

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)	[email protected]	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:

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]*

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] *

2.3.12 PRODUCT_NEW

Create a new product, service or description:

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:

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:

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.

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.

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.

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.

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.

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.

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.

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.

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):

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

Release	Date	Description	Author	Review
1.00	18/01/2015	First release	IV	RM, JS
1.01	11/01/2016	Customer, Supplier, Product, Bank Deposits added	RM	IV
1.03	01/11/2018	Customer Proof of Delivery (POD)	IV	RJ, RM
1.03	27/11/2019	Customer, Supplier enhanced with [auto], <condition>	IV	RM

1. Scope

1.1 Identification

1.2 System Overview

1.3 Document Overview

2. Connecting to Framework

2.1 API URL

2.1.1 Validation

2.1.2 Authentication

2.2 Retrieve Data from Framework: Get Commands

2.2.1 GET_NOMTAIL

2.2.2 GET_CUSTOMERS

2.2.3 GET_SUPPLIERS

2.2.4 GET_PRODUCTS

2.2.5 GET_CUSTOMERPODSETTINGS

2.2.5.1 Reasons Table

2.2.6 GET Conditions

2.3 Send data to Framework: Post Commands

2.3.1 CUSTOMER_NEW

2.3.2 CUSTOMER_EDIT

2.3.3 CUSTOMER_DELETE

2.3.4 CUSTOMER_INVOICE

2.3.5 CUSTOMER_CREDIT_NOTE

2.3.6 CUSTOMER_POD

2.3.7 SUPPLIER_NEW

2.3.8 SUPPLIER_EDIT

2.3.9 SUPPLIER_DELETE

2.3.10 SUPPLIER_INVOICE

2.3.11 SUPPLIER_CREDIT_NOTE

2.3.12 PRODUCT_NEW

2.3.13 PRODUCT_EDIT

2.3.14 PRODUCT_DELETE

2.3.15 RECEIPT_CUSTOMER

2.3.16 RECEIPT_NOMINAL

2.3.17 RECEIPT_SUPPLIER

2.3.18 RECEIPT_VATREFUND

2.3.19 PAYMENT_CUSTOMER

2.3.20 PAYMENT_NOMINAL

2.3.21 PAYMENT_SUPPLIER

2.3.22 PAYMENT_VATPAYMENT

2.3.23 BANK_DEPOSIT

2.3.24 BANK_TRANSFER

3. Release History

Previous

Next

NAVIGATION

TWITTER FEED