The second version of the Standard ERP Rest API is used to read and write data in Standard ERP database via HTTP or HTTPS.
In the Access Groups setting, give the user full access to the ‘Rest API’ action.
The API uses the access rights for the user. The user must be able to navigate to and open the register in a normal client and must thus have access to both a module the register is in, and the register itself. For registers that do not appear in any module a customisation to make them appear in some module is needed.
Examples of such registers are RHistVc and MailVc.
If the user has been restricted in viewing some fields in a register, for example with the “View Item’s Cost Price” access, they can still retrieve this field via the API and should thus not have access to the API. This is the same as for exports.
The user should authenticate with OAuth (details at the end of this document).
Requests specify the company and resource to read, in the most basic format:
http://hostname.domain.top/api/1/IVVc
where:
This will fetch all invoices in company 1.
To retrieve information from a block such as Base Currencies, you similarly use:
http:/hostname.domain.top/api/1/BaseCurBlock
Use the Import/Export Format report in the Technics module to obtain a list of Vc and Block codes for each register and setting.
The same data format is used in the request and in the returned data and is hardcoded.
The actual parameter values used for results such as key and range used, version of the server etc. are returned as attributes of the data tag.
The sort parameter will sort the retrieved records on the specified field. The name of the index that was used will be returned in the result. 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.
Example: http://hostname.domain.top/api/1/IVVc?sort=CustCode
Requires the use of the sort parameter.
The range parameter will only retrieve records where the sorted-on field is inside the specified range. The range is inclusive (values matching the start and end values are inside the range). The first and last value of the range are separated with the ":" (colon character). Open ranges where only the 1st or last value is specified are allowed, and will return all records before or after the specified value. If only a singular value is specified (no colon) only records matching that value will be retrieved.
Example 1: http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10101:10104
will return invoices with customers from 10101 to 10104.
Example 2: http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10104:
will return invoices with customers from 10104 until the last customer.
Example 3: http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10104
will return invoices only for customer 10104.
The range parameter is fast to use because it uses an index.
The fields parameter specifies which fields are to be retrieved. The fields are specified comma separated. If the parameter is not present all fields are retrieved. If a field in the matrix and a field in the header has the same name, both will be retrieved. If no field in the matrix are retrieved then the matrix itself (number of rows etc.) will not be present in the result.
Example: http://hostname.domain.top/api/1/IVVcfields=SerNr,OKFlag,Addr0,ArtCode,CustCode,InvDate,TransDate,Objects
Will return all invoices listing only the No., OK flag, Customer Name, Customer Number, Invoice Date, Transaction Date and, from each row, the Item Number and Tags/Objects.
The data can be filtered using the filter parameter. It is specified like this:
http://hostname.domain.top/api/1/IVVc?filter.CustCode=10104
Filter is significantly slower than range, as it will not use an index and scans all records. If you use a range the filter will only scan the records in the range, so try to use the most selective condition possible in the range and all other conditions in filters.
Example:
http://hostname.domain.top/api/1/IVVc?filter.CustCode=10100:10200&Sum4=100:1000
Will retrieve invoices with total sums between 100 and 1000 for customers in the range 10100 to 10200.
If the result is larger than the api user can handle in one request, the result can be retrieved in smaller pieces.
The offset will skip the specified number of records before producing output and the limit will restrict the number of records retrieved.
Example:
http://hostname/api/1/IVVc?offset=0&limit=5
http://hostname/api/1/IVVc?offset=5&limit=5
http://hostname/api/1/IVVc?offset=10&limit=5
Will retrieve the 15 first invoices in 3 separate requests.
Offset and limit works together with all other parameters.
Returns all records that were updated after a given sequence number.
The sequence number is returned in each request and can be saved for later use with updates_after.
Example:
http://hostname/api/1/IVVc?updates_after=5000
Returns all record that were deleted after a given sequence number.
The sequence number is returned in each request and can be saved for later use with deletes_after
Example:
http://hostname/api/1/IVVc?deletes_after=5000
Functionally RecordNew will be called, then each set command will be called in order with its respective window actions (e.g. to fill customer’s name and payment terms). Finally the record will be inserted calling the same record actions and record checks as if a user did it from a client.
There is no limit to the number of set commands you can issue, they can be either in the URL or in post data. Only fields with non-default (non blank) data will be returned.
Note the “url” parameter that uniquely identifies the created record. If you have 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.
If a user would receive messages when entering the data manually in a client, the same messages will be included in the response in the following format:
<message description='message_text'></message>
In case of error while inserting/updating a record, the following will be returned:
<error code='error_code' description='error description' row='row_no' field='field_name'></error>
To create new records you POST to the registers. Use the set_field and set_row_field parameters as follows:
The reply will be in this format:
<data register="IVVc" sequence="9693" url="/api/1/IVVc/10000014" systemversion="8.5.38.66"
<IVVc>
<SerNr>10000010</SerNr>
<InvDate>2021-05-30</InvDate>
<CustCode>001</CustCode>
<Math></Math>
<PayDate>2021-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 rownumber="0">
...
</rows>
...
</IVVc>
</data>
This will create a new invoice for customer 001, adding one row with item 10101 and quantity 3.
If you need to send special or non-alphanumeric characters when testing, use ASCII encoding.
Example:This will create a new contact with Code 301 and Name Test & Co.
Alternatively, use the following syntax:
curl -X POST --data-urlencode "set_field.Name=Test & Co" 'http://SJ:@127.0.0.1:8080/api/1/CUVc?set_field.Code=301'
To change an existing record you PATCH the url given in the POST command. The ‘set’ commands have the same syntax and functionality as with POST.
Example:
curl -X PATCH 'http://SJ:@127.0.0.1:8080/api/1/IVVc/10000014?set_row_field.0.Quant=100'
The reply will be in the same format as POST:
<data register="IVVc" sequence="9729" 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>
...
</row rownumber="0">
...
</rows>
...
</IVVc>
</data>
This will change the quantity in the first row of Invoice 10000014 to 100.
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'
If you need requests and/or responses to be in JSON format, you will need to include an instruction to this effect in the header of the request. For example, the header of a GET request requiring a response in JSON format should contain "-H "Accept: application/json"":
curl -X GET -H "Accept: application/json" 'http://hostname.domain.top:web port/api/1/IVVc'You can use parameters in the way described on pages 2 and 3 above to refine GET requests. For example:
curl -X GET -H "Accept: application/json" 'http://hostname.domain.top:web port/api/1/IVVc?sort=CustCode'POST and PATCH requests in which the request is in JSON format should contain "-H "Content-Type: application/json"" in their headers. In this example PATCH request, the request is in JSON format and a JSON response is required:
curl -X PATCH \This will change the first two lines of the Invoice Address in Invoice 10000014 to "New Address Line 1" and "New Address Line 2" (the Addr1 and Addr2 fields in IVVc). With POST only, you can create more than one record with the same request:
curl -X POST \This will create two Objects TEST1 and TEST2 belonging to the "PERS" Object Type, and the response will only display the Code, Comment and Object Types of those new Objects. The following example will create a Quotation with two rows. Note that row numbers begin at 0:
curl -X POST \Note that if you use set_field and set_row_fields in a POST request, all window actions and all record actions will be carried out. But if you submit a POST request in JSON format, only the record actions will be carried out. This means for example that when sending a Customer Number to a new Invoice, information such as the Customer Name, Payment Term and Price List will not be brought in to the Invoice so you will need to include this information in the request. The record validation check on saving will be carried out so a record will not be saved if there is a problem, and the relevant error message will be included in the JSON response.
To set up a 3rd party application to use OAuth with REST API, the following steps need to be made:
{
"access_token": [access token],
"token_type": "bearer",
"expires_in": 3600,
"refresh_token": [refresh token]
}
If you would like to test the OAuth, you can use Google's Developers Playground as one of the tools.
To configure:
To refresh the access token using the refresh token:
For more information about Rest API please visit our online manuals: REST API manual