Leia kiirelt!

Rest API vers.2 description in englishUuendatud 07. oktoober 2021

HansaWorld’s second version (valid from 8.4 version) of the Rest API is used to read data from the HansaWorld software database via HTTP/HTTPS requests.

Security
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, MailVc.   The user should authenticate with oAuth
The path “api” may be secured with the Webshop&CMS module setting “Access to functions on the web“.
• The default access for HAL functions is off
• The default access for the “api” path is login required
• For all other resources it is public.

If the user has been restricted in viewing some fields on a register, for example with the “view cost price” access, he can still retrieve this field via the API and should thus not have access to it. This is the same as for exports.

Setup
• In the System module, Optional Features setting, the checkbox “Web Rest API” is used to enable the API.
• The user must be given the access right to the action Rest API

Basic Use of GET requests
Requests specify the company and resource to read, in the most basic format:
http://hostname.domain.top/api/1/IVVc

This would fetch all invoices in company 1, where:
• “api” is a mandatory hardcoded string
• “1” is the company code from the companies setting (1st column)
• “IVVc” is the name of the register.

To retrieve information about base currencies, you similarly use:
http://hostname/api/1/BaseCurBlock

Data Format
The data format for request and 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
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.

sort – 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 (request from sales invoices register sorted by customer code):
http://hostname.domain.top/api/1/IVVc?sort=CustCode

range –  Requires the use of the sort parameter. Retrieve only 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.

Example1 (will return invoices with customers from 10101 to 10104):
http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10101:10104

Example2 (will return invoices with customers from 10104 until the last customer):
http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10104:

Example3 (will return invoices only for customer 10104):
http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10104

The range parameter is fast to use because it uses an index.

fields – 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/IVVc? fields=SerNr,OKFlag,Addr0,ArtCode,CustCode,InvDate,TransDate,Objects

filter – The data can be filtered with the filter parameter. The filter is significantly slower than range, as it will not use an index and scan 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. It is specified like this:

http://hostname.domain.top/api/1/IVVc?filter.CustCode=10104

• There can only be one filter per field
• There can be multiple filters on different fields
• Filters can handle ranges of values, with the same syntax as range, including open ranges
• Filters work only on header fields
• Filtering on list fields such as Objects is done by the whole string. a filter.Objects=AB will not match “AB,D10101”

Example (will retrieve invoices with a total sum of 100 to 1000 for customers in the range 10100 to 10200):
http://hostname.domain.top/api/1/IVVc?filter.CustCode=10100:10200&Sum4=100:1000

offset and limit – 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 (will retrieve the 15 first invoices in 3 separate requests):
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

offset and limit work together with all other parameters.

updates_after – 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

deletes_after – 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

 

WRITING DATA TO DATABASE (API POST)

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:
set_field – will send a value to a header field.
set_row_field – will send a value to a row field. The parameter should include the row number (row numbers begin at 0).

Example:
curl -X POST ‘http://SJ:@127.0.0.1:8080/api/1/IVVc?set_field.CustCode=001&set_row_field.0.ArtCode=10101&set_row_field.0.Quant=3’
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:
curl -X POST ‘http://SJ:@127.0.0.1:8080/api/1/CUVc?set_field.Code=301&set_field.Name=Test%20%26%20Co’ 
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’ 
PATCH
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 to 100.
OAuth AUTHENTICATION
To set up a 3rd party application to use OAuth with REST API, the following steps need to be made:
Step 1: Set up new Developer Credentials in the MyStandard portal for your StandardID.
To do that, go to MyStandard >> More >> Developer Credentials and add a new record.
Step 2: In the new record >> Allowed Redirects specify the URL that StandardID will be redirecting after a user logs in with their StandardID and Password (a callback URL).

From the 3rd party application, whenever something triggers the Authorisation, it needs to redirect to:
https://standard-id.hansaworld.com/oauth-authorize with the following GET parameters:
– client_id = Client ID from Developer Credentials in MyStandard
– redirect_uri = Your application URL that will handle the callback from the StandardID server after logging in
– access_type = must be “offline
– response_type = must be “code

Step 3: After redirecting user to the URL generated in step 3, the user will have to log in using their StandardID and Password.

Step 4: If the log-in is successful, StandardID will redirect the user to the specified redirect_uri with GET parameter:
– code = Authorisation Code

Step 5: Next, the redirect_uri should handle the exchange of Authorisation Code to OAuth Token.
Application has to make a call to https://standard-id.hansaworld.com/oauth-token with the following POST parameters:
– client_id = Client ID from Developer Credentials in MyStandard
– client_secret = Client Secret from Developer Credentials in MyStandard
– redirect_uri = Application’s URL that will handle the callback from StandardID that will contain the token
– code = Authorisation Code received in step 4
– grant_type = must be “authorization_code”

Step 6: If the request is successful, StandardID will redirect the user to the redirect_uri with the JSON response that looks as follows:

{

“access_token”: [access token],

“token_type”: “bearer”,

“expires_in”: 3600,

“refresh_token”: [refresh token]

}

Step 7: If the request is not successful, StandardID will redirect the user to the redirect_uri with GET parameter:
– error = server_error

Step 8: Each next API request must have the access token specified in the header of the request:
Authorization: Bearer [access_token]

 

If you would like to test the OAuth, you can use Google’s Developers Playground as one of the tools.
To configure:

  • Step 1: Configure Developer Credentials for your Standard ID in MyStandard. Allowed Redirects should be:
    – https://developers.google.com/oauthplayground
  • Step 2: Go to:
    https://developers.google.com/oauthplayground/
  • Step 3: Configure the settings as follows:
    – OAuth flow = Server-side
    – OAuth endpoints = Custom
    – Authorization endpoint = https://standard-id.hansaworld.com/oauth-authorize
    – Token endpoint = https://standard-id.hansaworld.com/oauth-token
    – Access Token Location = Authorization Header w/ Bearer prefix
    – OAuth Client ID = Client ID from Developer Credentials in MyStandard
    – OAuth Client Secret = Client Secret from Developer Credentials in MyStandard
  • Step 4: After configuring this, enter anything in the Step 1 Select & Authorize APIs >> Input your own scopes and press Authorize APIs
  • Step 5: You should be redirected to Standard ID login page, so perform the login
  • Step 6: You will be brought back to Step 2, with Authorization Code filled in. Press Exchange authorization code for tokens
  • Step 7: Then you will be brought to Step 3, from which you can make API GET, POST, PATCH requests with OAuth to Standard ERP
Täname tagasiside eest! Soovi korral lisa oma kommentaar ja kontaktandmed, et saaksime Sinuga ühendust võtta.
Aitäh tagasiside eest!
Kommentaari saatmine ebaõnnestus