HW rest api copy - Redigeerimiste ajalugu

Kaupo – 28. aprill 2020, kell 13:35

2020-04-28T13:35:36Z

←Vanem redaktsioon		Redaktsioon: 28. aprill 2020, kell 13:35
121. rida:		121. rida:
	<nowiki>http://hostname/api/1/IVVc?deletes_after=5000</nowiki>		<nowiki>http://hostname/api/1/IVVc?deletes_after=5000</nowiki>

	==== Writing Data to Standard ERP ====		=== Writing Data to Standard ERP ===
	Functionally RecordNew will be called, then each set command will be called in order with it's respective window actions (to fill e.g. customer's name and payment terms). Finally the record will be inserted calling the same record actions as if a user did it with 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 is returned.		Functionally RecordNew will be called, then each set command will be called in order with it's respective window actions (to fill e.g. customer's name and payment terms). Finally the record will be inserted calling the same record actions as if a user did it with 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 is returned.

Kaupo – 14. veebruar 2020, kell 13:51

2020-02-14T13:51:38Z

←Vanem redaktsioon		Redaktsioon: 14. veebruar 2020, kell 13:51
3. rida:		3. rida:
	=== General Description ===		=== General Description ===
	The second version of the Standard ERP Rest API is used to read and write data in Standard ERP database via HTTP requests.		The second version of the Standard ERP Rest API is used to read and write data in Standard ERP database via HTTP requests.

			[[Päringute näidislingid\|Example links are here]], page in estonian but links are international

	=== Compared to the First Version ===		=== Compared to the First Version ===

Kaupo – 15. märts 2019, kell 12:42

2019-03-15T12:42:58Z

←Vanem redaktsioon		Redaktsioon: 15. märts 2019, kell 12:42
29. rida:		29. rida:
	=== Basic Use ===		=== Basic Use ===
	Requests specify the company and resource to read, in the most basic format:		Requests specify the company and resource to read, in the most basic format:
			<nowiki>http://hostname.domain.top/api/1/IVVc</nowiki>
	<nowiki>http://hostname.domain.top/api/1/IVVc</nowiki>

	where:		where:
	* "api" is a mandatory hardcoded string.		* "api" is a mandatory hardcoded string.
39. rida:		37. rida:

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

	=== Data Format ===		=== Data Format ===
53. rida:		50. rida:
	==== sort ====		==== 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.		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.
			<nowiki>http://hostname.domain.top/api/1/IVVc?sort=CustCode</nowiki>
	~~''Example'':~~ <nowiki>http://hostname.domain.top/api/1/IVVc?sort=CustCode</nowiki>

	==== range ====		==== range ====
61. rida:		57. rida:
	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.		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.

	''Example 1'': <nowiki>http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10101:10104</nowiki> ~~will~~ return invoices with customers from 10101 to 10104.		''Example 1'':
			<nowiki>http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10101:10104</nowiki>
			will return invoices with customers from 10101 to 10104.

	''Example 2'': <nowiki>http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10104</nowiki>: ~~will~~ return invoices with customers from 10104 until the last customer.		''Example 2'':
			<nowiki>http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10104</nowiki>:
			will return invoices with customers from 10104 until the last customer.

	''Example 3'': <nowiki>http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10104</nowiki> ~~will~~ return invoices only for customer 10104.		''Example 3'':
			<nowiki>http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10104</nowiki>
			will return invoices only for customer 10104.

	The range parameter is fast to use because it uses an index.		The range parameter is fast to use because it uses an index.
72. rida:		74. rida:
	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.		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'': <nowiki>http://hostname.domain.top/api/1/IVVc?fields=SerNr,OKFlag,Addr0,ArtCode,CustCode,InvDate,TransDate,Objects</nowiki>		''Example'':
			<nowiki>http://hostname.domain.top/api/1/IVVc?fields=SerNr,OKFlag,Addr0,ArtCode,CustCode,InvDate,TransDate,Objects</nowiki>

	==== filter ====		==== filter ====
91. rida:		94. rida:

	''Example'':		''Example'':
			<nowiki>http://hostname/api/1/IVVc?offset=0&limit=5</nowiki>

	<nowiki>http://hostname/api/1/IVVc?offset~~=0&limit=5</nowiki>~~		<nowiki>http://hostname/api/1/IVVc?offset=5&limit=5</nowiki>

	~~<nowiki>http://hostname/api/1/IVVc?offset=5&limit~~=5~~</nowiki>~~

	~~<nowiki>http://hostname/api/1/IVVc?offset=10~~&limit=5</nowiki>

			<nowiki>http://hostname/api/1/IVVc?offset=10&limit=5</nowiki>
	will retrieve the 15 first invoices in 3 separate requests.		will retrieve the 15 first invoices in 3 separate requests.

107. rida:		108. rida:
	The sequence number is returned in each request and can be saved for later use with updates_after		The sequence number is returned in each request and can be saved for later use with updates_after

	''Example'': <nowiki>http://hostname/api/1/IVVc?updates_after=5000</nowiki>		''Example'':
			<nowiki>http://hostname/api/1/IVVc?updates_after=5000</nowiki>

	==== deletes_after ====		==== deletes_after ====
114. rida:		116. rida:
	The sequence number is returned in each request and can be saved for later use with deletes_after		The sequence number is returned in each request and can be saved for later use with deletes_after

	''Example'': <nowiki>http://hostname/api/1/IVVc?deletes_after=5000</nowiki>		''Example'':
			<nowiki>http://hostname/api/1/IVVc?deletes_after=5000</nowiki>

	==== Writing Data to Standard ERP ====		==== Writing Data to Standard ERP ====
129. rida:		132. rida:

	''Example'':		''Example'':
			curl -X POST '<nowiki>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'</nowiki>;
	curl -X POST '<nowiki>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'</nowiki>;

	The reply will be in this format:		The reply will be in this format:

Kaupo – 15. märts 2019, kell 12:17

2019-03-15T12:17:04Z

←Vanem redaktsioon		Redaktsioon: 15. märts 2019, kell 12:17
133. rida:		133. rida:

	The reply will be in this format:		The reply will be in this format:

	<~~code><nowiki~~><data register="IVVc" sequence="9693" url="/api/1/IVVc/10000014" systemversion="8.5.15.5"		<syntaxhighlight lang="xml">
	<IVVc>		<data register="IVVc" sequence="9693" url="/api/1/IVVc/10000014" systemversion="8.5.15.5" <IVVc>
	<SerNr>10000010</SerNr>		<SerNr>10000010</SerNr>
	<InvDate>2018-05-30</InvDate>		<InvDate>2018-05-30</InvDate>
	<CustCode>001</CustCode>		<CustCode>001</CustCode>
	<Math></~~Math~~>		<Math/>
	<PayDate>2018-06-29</PayDate>		<PayDate>2018-06-29</PayDate>
	<Addr0>Against All Odds Trading Co</Addr0>		<Addr0>Against All Odds Trading Co</Addr0> ... <rows>
			<row rownumber="0">
	...		<stp>1</stp>
			<ArtCode>10101</ArtCode>
	<rows>		<Quant>3</Quant>
	<row rownumber="0">		<Price>25.00</Price>
	<stp>1</stp>		<Sum>71.25</Sum>
	<ArtCode>10101</ArtCode>		</syntaxhighlight>
	<Quant>3</Quant>
	<Price>25.00</Price>
	<Sum>71.25</Sum></~~nowiki~~>~~</code>~~


	This will create a new invoice for 001 customer, adding 3 10101 items.		This will create a new invoice for 001 customer, adding 3 10101 items.

163. rida:		159. rida:
	curl -X PATCH '<nowiki>http://SJ:@127.0.0.1:8080/api/1/IVVc/10000014?set_row_field.0.Quant=100'</nowiki>		curl -X PATCH '<nowiki>http://SJ:@127.0.0.1:8080/api/1/IVVc/10000014?set_row_field.0.Quant=100'</nowiki>

	The reply will be in the same format:		The reply will be in the same format:<syntaxhighlight lang="xml">
			<data register="IVVc" sequence="9729" url="/api/1/IVVc/10000014" systemversion="8.5.15.6" <IVVc>
	<~~code><nowiki~~><data register="IVVc" sequence="9729" url="/api/1/IVVc/10000014" systemversion="8.5.15.6"		<SerNr>10000014</SerNr> ... <rows>
	<IVVc>		<row rownumber="0">
	<SerNr>10000014</SerNr>		<stp>1</stp>
			<ArtCode>10101</ArtCode>
	...		<Quant>100</Quant>
			<Price>25.00</Price>
	<rows>		<Sum>2375.00</Sum>
	<row rownumber="0">		</syntaxhighlight>
	<stp>1</stp>
	<ArtCode>10101</ArtCode>
	<Quant>100</Quant>
	<Price>25.00</Price>
	<Sum>2375.00</Sum></~~nowiki~~>~~</code>~~


	This will change the quantity to 100.		This will change the quantity to 100.

Kaupo: Uus lehekülg: '= REST API v2.2 = === General Description === The second version of the Standard ERP Rest API is used to read and write data in Standard ERP database via HTTP requests. === Com...'

2019-03-15T12:15:06Z

Uus lehekülg: '= REST API v2.2 = === General Description === The second version of the Standard ERP Rest API is used to read and write data in Standard ERP database via HTTP requests. === Com...'

Uus lehekülg

= REST API v2.2 =

=== General Description ===
The second version of the Standard ERP Rest API is used to read and write data in Standard ERP database via HTTP requests.

=== Compared to the First Version ===
* Read values from any register or block in the database including customised registers and blocks.
* Expanded options to filter and sort records.
* Retrieve changes since a previous API call.
* Improved security features.
* Ability to write data to Standard ERP database.
* Support for changing existing records.
* Fetch only wanted fields, making the response smaller.

=== 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 and MailVc.
* The user should authenticate with oAuth.
* The path "api" may be secured with the 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 ===
Requests specify the company and resource to read, in the most basic format:

<nowiki>http://hostname.domain.top/api/1/IVVc</nowiki>

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.
This would fetch all invoices in company 1.

To retrieve information about base currencies, you similarly use:

<nowiki>http://hostname/api/1/BaseCurBlock</nowiki>

=== 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'': <nowiki>http://hostname.domain.top/api/1/IVVc?sort=CustCode</nowiki>

==== 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.

''Example 1'': <nowiki>http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10101:10104</nowiki> will return invoices with customers from 10101 to 10104.

''Example 2'': <nowiki>http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10104</nowiki>: will return invoices with customers from 10104 until the last customer.

''Example 3'': <nowiki>http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10104</nowiki> will return invoices only for customer 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'': <nowiki>http://hostname.domain.top/api/1/IVVc?fields=SerNr,OKFlag,Addr0,ArtCode,CustCode,InvDate,TransDate,Objects</nowiki>

==== filter ====
The data can be filtered with the filter parameter. It is specified like this: <nowiki>http://hostname.domain.top/api/1/IVVc?filter.CustCode=10104</nowiki>

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.
* 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: <nowiki>http://hostname.domain.top/api/1/IVVc?filter.CustCode=10100:10200&Sum4=100:1000</nowiki> will retrieve invoices with a total sum of 100 to 1000 for customers in the range 10100 to 10200.

==== 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'':

<nowiki>http://hostname/api/1/IVVc?offset=0&limit=5</nowiki>

<nowiki>http://hostname/api/1/IVVc?offset=5&limit=5</nowiki>

<nowiki>http://hostname/api/1/IVVc?offset=10&limit=5</nowiki>

will retrieve the 15 first invoices in 3 separate requests.

offset and limit works together will 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'': <nowiki>http://hostname/api/1/IVVc?updates_after=5000</nowiki>

==== 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'': <nowiki>http://hostname/api/1/IVVc?deletes_after=5000</nowiki>

==== Writing Data to Standard ERP ====
Functionally RecordNew will be called, then each set command will be called in order with it's respective window actions (to fill e.g. customer's name and payment terms). Finally the record will be inserted calling the same record actions as if a user did it with 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 is 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.

In case of any messages that user would receive when entering the data manually, these messages will be returned in following format: <code><message description='message_text'></message></code>

In case of error while inserting/updating a record, following will be returned: <code><error code='error_code' description='error description' row='row_no' field='field_name'></error></code>

==== POST ====
To create new records you POST to the registers. The 'set' commands have the same syntax and functionality as with POST.

''Example'':

curl -X POST '<nowiki>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'</nowiki>;

The reply will be in this format:

<code><nowiki><data register="IVVc" sequence="9693" url="/api/1/IVVc/10000014" systemversion="8.5.15.5"
<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></nowiki></code>

This will create a new invoice for 001 customer, adding 3 10101 items.

==== PATCH ====
To change an existing record you PATCH the url given in the POST command.

''Example'':

curl -X PATCH '<nowiki>http://SJ:@127.0.0.1:8080/api/1/IVVc/10000014?set_row_field.0.Quant=100'</nowiki>

The reply will be in the same format:

<code><nowiki><data register="IVVc" sequence="9729" url="/api/1/IVVc/10000014" systemversion="8.5.15.6"
<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></nowiki></code>

This will change the quantity to 100.