HansaWorld - Integrated ERP and CRM

HansaManuals Home >> Standard ERP >> System Administrator and Technical Pages >> System Administrator and Technical Pages

Previous Next Entire Chapter in Printable Form Search

This text refers to program version 8.5

REST API - Retrieving Data from a Standard ERP Database - GET Requests

This page describes using a third-party application to retrieve data from your database through the Standard ERP API. Please refer to the following pages for details about other aspects of the API:

Introduction
Configuration and Access
Retrieving Data from a Standard ERP Database - GET Requests
Writing Data into a Standard ERP database - POST and PATCH Requests
Requests and Responses in JSON format

---

In its most basic format, a GET request should specify the Company and the resource to be read:

http://hostname.domain.top:web port/api/1/IVVc

where:

"hostname.domain.top" should be the web or IP address of the sever.

"web port" is the HTTPS Port or Web Port (if you are using Basic HTTP Authentication) in the Program Mode register.

"api" is a mandatory hardcoded string.

"1" is the company code from the Company register (1st column).

"IVVc" is the name of the register (in this example, the Invoice register).

You will be asked to log in and the request will then fetch and list all Invoices in company 1. The response to the request is described immediately below, under the 'Response' heading.

If you are using Basic HTTP Authentication for testing, you can include log-in details (i.e. a Signature and a password) in the request:

http://Signature:password@hostname.domain.top:web port/api/1/IVVc

To retrieve information from a block (for example, the Base Currency setting), you would similarly use:

http://hostname.domain.top:web port/api/1/BaseCurBlock

Register names end in "Vc" and block names in "Block" as in the examples above. For a list of Vc and Block names, use the Export/Import Format report in the Technics module.

If the request fails, the probable reasons are:

If the response is "Response File not found! api/1/ivvc", this will probably be because you are making the request from an IP Address that is not listed in the Access to Functions from Web setting or because you have entered "yes" in the SSL field in the relevant row in the Access to Functions from Web setting and you are making the request using http.
If you are asked to log in more than once, the Signature and/or password are not correct or your Access Group does not allow you access to the register in the request.

Response
By default, all responses will be in XML (please refer here for details about JSON responses).. In the <data> tag at the beginning of each response, the register that was requested, a sequence number and the version of Standard ERP that you are using will be included as attributes. For example:

<?xml version='1.0' encoding-'utf-8' standalone='yes'?>

The sequence number will be incremented for each action carried out by the database. Responding to API calls will increment the sequence number.

Following the <data> tag, the response will list the records in the requested register:

<IVVc>

... (other header fields listed)

<rows>

... (other row fields listed)

</row>

... (other rows listed)

</rows>

</IVVc>

.. (other records listed)

</data>

Data Format
The data format for requests and for returned data is the same and hardcoded:

The decimal point is "." (period).
There is no thousand separator.
Dates are in ISO format YYYY-MM-DD.

Parameters
You can refine GET requests using parameters. You can include several parameters in a request, separated using the & character (depending on the environment you are using, you may need to precede & with \).
sort
The sort parameter will sort the retrieved records on the specified field. Only one field can be sorted on, and only if there is a suitable index. If there is no suitable index the request will fail. The field name is case sensitive. For example:

http://hostname.domain.top:web port/api/1/IVVc?sort=CustCode

This request will fetch all Invoices in company 1, sorted by Customer Number.

The sort parameter and its value will be included in the response as an attribute of the <data> tag.

range
Using the range parameter requires the use of the sort parameter as well.

The range parameter will only retrieve records where the value of the sorted-on field is inside the specified range. The range is inclusive (values matching the start and end values are inside the range). Use a colon (:) to separate the first and last values of the range. Open ranges where only the first or last value is specified are allowed, and will return all records before or after the specified value. If you specify a singular value without a colon, only records matching that value will be retrieved.

Example 1

http://hostname.domain.top:web port/api/1/IVVc?sort=CustCode&range=001:004

Will return Invoices with Customer Numbers between 001 and 004.

Example 2

http://hostname.domain.top:web port/api/1/IVVc?sort=CustCode&range=004:

Will return Invoices with Customer Numbers from 004 onwards.

Example 3

http://hostname.domain.top:web port/api/1/IVVc?sort=CustCode&range=004

Will return Invoices with Customer Number 004 only.

The range parameter and its value will be included in the response as an attribute of the <data> tag.

The range parameter is fast because it uses an index.
fields
Use the fields parameter if you need to specify which fields will be included in the response. You can specify several fields, separated by commas. If the parameter is not present all fields are retrieved. If fields in the header and matrix have the same name, both will be retrieved. If no field in the matrix is retrieved then the matrix itself will not be present in the result. The field names are case sensitive.

Example

http://hostname.domain.top:web port/api/1/IVVc?fields=SerNr,OKFlag,Addr0,ArtCode,CustCode,InvDate,TransDate,Objects

Will return the following information from all Invoices: Invoice Number, OK, Customer Name, Item Number(s), Customer Number, Invoice Date, Transaction Date, Tag/Object (from both header and row(s)).
filter
The filter parameter will only retrieve records where the content of a specified field matches a specified value. filter is significantly slower than range, as it will not use an index and will scan all records individually. If you use range the filter will only scan the records in the range, so try to reduce the number of records as much as possible using range and include other conditions as filters.

You can obtain field names from the Export/Import Format report in the Technics module.

There can only be one filter per field in a request.
There can be multiple filters on different fields.
Filters can handle ranges of values, including open ranges. Use the same syntax as for range.
Filters work only on header fields.
In list fields (fields such as Objects and Persons that can contain several values separated by commas), the filter will be applied to the entire string in the field. For example, filter.Objects=AB will not match "AB,D10101".

Example 1

http://hostname.domain.top:web port/api/1/IVVc?filter.CustCode=004

Will return Invoices with Customer Number 004 only (but note that a faster method will be to use sort and range).

Example 2

http://hostname.domain.top:web port/api/1/IVVc?sort=CustCode&range=001:004&filter.Sum4=100:1000

Will retrieve Invoices with Customer Numbers between 001 and 004 and with TOTALs between 100 and 1000.

Example 3

http://hostname.domain.top:web port/api/1/IVVc?sort=CustCode&range=001:004&filter.Sum4=100:1000&filter.Location=WHS

Will retrieve Invoices with Customer Numbers between 001 and 004, with TOTALs between 100 and 1000 and with Location WHS.
offset and limit
If the response will be larger than the API user can handle in one request, you can use offset and limit to make several requests that will generate smaller responses.

offset will skip the specified number of records before producing output and limit will restrict the number of records retrieved.

offset and limit work together with all other parameters.

Example

http://hostname.domain.top:web port/api/1/IVVc?offset=0&limit=5

http://hostname.domain.top:web port/api/1/IVVc?offset=5&limit=5

http://hostname.domain.top:web port/api/1/IVVc?offset=10&limit=5

Will retrieve the first 15 Invoices in three separate requests.
updates_after
Returns all records that were saved or updated after a given sequence number.

The sequence number is returned in the <data> tag in each response and can be saved for later use with updates_after.

Example

http://hostname.domain.top:web port/api/1/IVVc?updates_after=5000

Returns all Invoices with sequence numbers greater than 5000, listed in sequence number order (i.e. in the order in which they were last saved).
deletes_after
Returns all records that were deleted after a given sequence number.

The sequence number is returned in the <data> tag in each response and can be saved for later use with deletes_after.

Example

http://hostname.domain.top:web port/api/1/IVVc?deletes_after=5000

Returns all deleted Invoices with sequence numbers greater than 5000.

---

The Standard ERP REST API:

Introduction
Configuration and Access
Retrieving Data from a Standard ERP Database - GET Requests
Writing Data into a Standard ERP database - POST and PATCH Requests
Requests and Responses in JSON format

Go back to:

Home page for Standard ERP manual

Previous Next Top Entire Chapter in Printable Form