REST API - Writing Data into a Standard ERP database - POST and PATCH Requests
This page describes using a third-party application to write data to your database through the Standard ERP API. Please refer to the following pages for details about other aspects of the API:
---
You can use the following request methods to write data into a Standard ERP database through the API:
- POST
- Use this method to create new records.
- PATCH
- Use this method to update existing records.
If a user would receive messages when entering records from a Standard ERP client, the same messages will be included in the API's responses, in the following format:
- <message description="message_text"></message>
In this context, a message contains information that is passed to the user when entering or updating a record, and does not prevent the saving of that record. An example is the "Open prepayment exists" message that can appear when specifying the Customer in an Invoice. Any messages will be placed at the beginning of the response, before the <data> tag.
Similarly, error messages will be included in the API's responses as follows:
- <error code='error_code' description="error description" row="row_no" field="field_name"></error>
Errors prevent the saving of records. Again, errors will be placed at the beginning of the response, before the <data> tag. If the error is in a header field, the row attribute will be set to -1. If the error is in a row field, note that row numbers begin at 0.
POST
To create new a record, POST to the register.
Records will be created in the same way as when entering them through a Standard ERP client. So, default values in a new record will be the same, and each window action will be enacted (for example, bringing information such as a Customer's Name and Payment Term in to a new Invoice and calculating the Due Date). On saving, the same validation checks will be carried out (as mentioned above). There is no limit to the number of set commands you can issue, they can either be in the url or in the POST data.
Example
- curl -X POST 'http://hostname.domain.top:web port/api/1/IVVc?set_field.CustCode=001&set_row_field.0.ArtCode=10101&set_row_field.0.Quant=3'
where:
- set_field is the parameter used to send a value to a header field. In this example, set_field.CustCode=001 will send the value 001 to the Customer Number field (.CustCode) in the new Invoice (IVVc).
- set_row_field is the parameter used to send a value to a row field. This parameter should include the row number (row numbers begin at 0). In this example, set_row_field.0.ArtCode=10101 will send the value 10101 to the Item Number field (ArtCode) in the first row (row 0), and set_row_field.0.Quant=3 will send the value 3 to the Qty field (Quant) in the same row.
- As shown in the example, enclose the POST data in inverted commas to ensure the ampersands will be interpreted correctly as separators (or use \&).
This will create a new Invoice for Customer 001, with one row for 3 x Item 10101.
The reply will be in this format:
- <data register="IVVc" sequence="16032" url="/api/1/IVVc/10000014" systemversion="8.5.38.66"
- <IVVc>
- <SerNr>10000010</SerNr>
- <InvDate>2018-05-30</InvDate>
- <CustCode>001</CustCode>
- <Math></Math>
- <PayDate>2018-06-29</PayDate>
- <Addr0>Against All Odds Trading Co</Addr0>
- ...
- <rows>
- <row rownumber="0">
- <stp>1</stp>
- <ArtCode>10101</ArtCode>
- <Quant>3</Quant>
- <Price>25.00</Price>
- <Sum>71.25</Sum>
- ...
- </row>
- </rows>
- </IVVc>
- </data>
Note that the <data> tag includes a "url" attribute that uniquely identifies the created record (Invoice Number 10000014 in this example). If there is more than one field in the main key these fields will be separated by '/'. If the main key contains special characters they will be url encoded.
Only fields with non-default (non blank) data will be returned in the response (unlike GET which returns every field unless restricted using the fields parameter).
Depending on the environment from where you are sending POST and PATCH requests, you may need to send special or non-alphanumeric characters using ASCII encoding (e.g. you may need to use %20 instead of a space and %26 instead of an ampersand). Please refer to https://www.w3schools.com/tags/ref_urlencode.asp for a reference list.
Example
- curl -X POST 'http://hostname.domain.top:web port/api/1/CUVc?set_field.Code=301&set_field.Name=Test%20%26%26Co'
This will create a Contact with Code 301 and Name Test & Co.
An alternative syntax is the following:
- curl -X POST --data-urlencode "set_field.Name=Test & Co" 'http://hostname.domain.top:web port/api/1/CUVc?set_field.Code=301'
PATCH
To change an existing record, PATCH the url given in the POST command (i.e. specify the unique code or number of the record to be changed). The 'set' commands have the same syntax and functionality as with POST.
Example
- curl -X PATCH 'http://hostname.domain.top:web port/api/1/IVVc/10000014?set_row_field.0.Quant=100'
This will change the Quantity in the first row in Invoice 10000014 to 100. The reply will be in the same format as POST:
- <data register="IVVc" sequence="16062" url="/api/1/IVVc/10000014" systemversion="8.5.38.66"
- <IVVc>
- <SerNr>10000014</SerNr>
- ...
- <rows>
- <row rownumber="0">
- <stp>1</stp>
- <ArtCode>10101</ArtCode>
- <Quant>100</Quant>
- <Price>25.00</Price>
- <Sum>2375.00</Sum>
If you need to PATCH a record in a register in which the main index has more than one key segment, separate the key segments using /. An example is DelAddrVc (Delivery Addresses), where the main index contains two key segments: Del. Code and Customer.
Example
- curl -X PATCH 'http://hostname.domain.top:web port/api/1/DelAddrVc/1/001?set_field.Comment=TestName'
This will change the Comment in the Delivery Address record in which the Del. Code is 1 and the Customer is 001.
As mentioned above, if the data contains / or other special characters (e.g. if the Del. Code in a Delivery Address is 001/1), use ASCII encoding for those characters:
- curl -X PATCH 'http://hostname.domain.top:web port/api/1/DelAddrVc/001%2F1/001?set_field.Comment=TestName'
---
The Standard ERP REST API:
Go back to:
