Konstantin: file not found response explained

2018-07-19T14:00:23Z

file not found response explained

←Vanem redaktsioon		Redaktsioon: 19. juuli 2018, kell 14:00
517. rida:		517. rida:

	=== Response body format ===		=== Response body format ===
			If the response is<syntaxhighlight>
			<HTML><HEAD><TITLE>File not found!</TITLE></HEAD><BODY>File not found! WebPOSTAPI</BODY></HTML>
			</syntaxhighlight>it means that the connection with specified IP and port number is established, but either authorisation error has happened or the resource (WebPOSTAPI) is not available on the server.

	Response is in JSON format.		Response is in JSON format.

Konstantin: http and authorization information details

2018-07-19T13:53:59Z

http and authorization information details

←Vanem redaktsioon		Redaktsioon: 19. juuli 2018, kell 13:53
3. rida:		3. rida:
	=== Request ===		=== Request ===

	==== With authorization ====		==== With authorization in URL ====
	<syntaxhighlight>		<syntaxhighlight>
	http://username:password@ipAddress:portNumber/WebPOSTAPI.hal?company=compNumber&param2=value&param3=value		http://username:password@ipAddress:portNumber/WebPOSTAPI.hal?company=compNumber&param2=value&param3=value
			</syntaxhighlight>

			==== With authorization in request header ====
			<syntaxhighlight>
			http://ipAddress:portNumber/WebPOSTAPI.hal?company=compNumber&param2=value&param3=value
			and additional header
			Authorization: Basic [base64 encoded user:password string]
	</syntaxhighlight>''UKU testdatabase:''<syntaxhighlight>		</syntaxhighlight>''UKU testdatabase:''<syntaxhighlight>
	https://s001.excellent.ee:6443/WebPOSTAPI.hal?company=1		HTTPS
			https://s001.excellent.ee:6443/WebPOSTAPI.hal?company=1
			HTTP
			http://s001.excellent.ee:1639/WebPOSTAPI.hal?company=1
	</syntaxhighlight>Companies implemented 1,2,3,4,5		</syntaxhighlight>Companies implemented 1,2,3,4,5

19. rida:		29. rida:
	* TBD		* TBD
	Example: <syntaxhighlight>		Example: <syntaxhighlight>
	http://testuser:testpassword@localhost:~~8989~~/WebPOSTAPI.hal?company=1		http://testuser:testpassword@localhost:1639/WebPOSTAPI.hal?company=1
	</syntaxhighlight>		</syntaxhighlight>

25. rida:		35. rida:
	Request header must contain at minimum the following header:		Request header must contain at minimum the following header:
	* Content-Type: application/xml		* Content-Type: application/xml
			In order to authorise not from URL but with POST request, additional header is required
			* Authorization: Basic [base64 encoded user:password string]
			** ''example Authorization: Basic YXBpOmFwaQ==''
	* ''JSON not supported at the moment''		* ''JSON not supported at the moment''

Tanel: /* Response body format */

2018-07-06T06:44:25Z

Response body format

@@ 560. rida: / 560. rida: @@
 ''Example'': <syntaxhighlight>
 http://testuser:testpassword@localhost:8989/WebGETAPI.hal?company=1&report=MainRn
 </syntaxhighlight>

Tanel: /* Create */

2018-07-05T11:21:24Z

Create

Näita muudatusi

Tanel: Uus lehekülg: '== POST == === Request === ==== With authorization ==== http://username:password@ipAddress:portNumber/WebPOSTAPI.hal?company=About:blank|comp...'

2018-07-05T10:54:43Z

Uus lehekülg: '== POST == === Request === ==== With authorization ==== <nowiki>http://username:password@ipAddress</nowiki>:portNumber/WebPOSTAPI.hal?company=About:blank|comp...'

Uus lehekülg

== POST ==

=== Request ===

==== With authorization ====
<nowiki>http://username:password@ipAddress</nowiki>:[[About:blank|portNumber]]/WebPOSTAPI.hal?company=[[About:blank|compNumber]]&param2=value&param3=value

UKU testdatabase:

<nowiki>https://s001.excellent.ee:6443/WebPOSTAPI.hal?company=1</nowiki>

Companies implemented 1,2,3,4,5

User: API

Password: api

Required parameters:

●    compNumber is the sequence number of the company in Hansa DB starting from 1

Optional parameters:

TBD

Example:

<nowiki>http://testuser:testpassword@localhost:8989/WebPOSTAPI.hal?company=1</nowiki>

==== Request headers ====
Request header must contain at minimum the following header:

Content-Type: application/xml

''JSON not supported at the moment''

==== Request body (POST data) format ====
Must be in XML format.

General format template as follows.

Notes:

●    <rows> element is optional;

●     IVVc is the internal system name of Invoice register in Hansa. Only following registers are supported at the moment:

○     IVVc - Invoices

○     CUVc - Contacts

○     INVc - Items

●     the register name (“IVVc”) is now included into <nowiki><data> element of request body, but is subject to review and may be moved to URL as parameter instead.</nowiki>

●    Possible to pass several ''<IVVc> elements to send several records.''

●     “method” attribute of the <nowiki><data> element defines the action. Actions supported at the moment: “create”, “delete”.</nowiki>

●     sequence="106357" systemversion="8.4.20.504" are not used in API right now, only used for example, can ignore it for the moment.

== CUVc (Contacts) ==

=== Create ===
Supported fields fields
{| class="wikitable"
|'''Kood'''
|'''Kirjeldus'''
|'''Pikkus, tüüp'''
|'''Kohustuslik'''
|-
|'''RefStr'''
|Ostu viide
|''60, string''
|Ei
|-
|'''Code'''
|Kontakti kood HansaWorldi tarkvaras. Unikaalne per kontakt
|''20, code''
|Jah
|-
|'''Name'''
|Kontakti nimi
|''200, string''
|Jah
|-
|'''CUType'''
|Kliendi linnuke. 0 = ei ole; 1 = on
|''0, flag''
|Jah
|-
|'''VEType'''
|Hankija linnuke. 0 = ei ole; 1 = on
|''0, flag''
|Jah
|-
|'''Person'''
|Kontaktisik
|''60, string''
|Ei
|-
|'''WarnText1'''
|Hoiatus
|''255, string''
|Ei
|-
|'''InvAddr0'''
|Aadress, rida 1
|''60, string''
|Ei
|-
|'''InvAddr1'''
|Aadress, rida 2
|''60, string''
|Ei
|-
|'''InvAddr2'''
|Aadress, rida 3
|''60, string''
|Ei
|-
|'''CustCat'''
|Kliendiklass
|''5, code''
|Ei
|-
|Comment
|Kommentaar
|''60, string''
|Ei
|-
|'''PayDeal'''
|Tasumistingimus
|''2, code''
|Ei
|-
|'''CountryCode'''
|Riigi kood
|''5, Code''
|Ei
|-
|'''RegNr1'''
|Registreerimisnumber 1. Eestis Äriregistri kood
|''20, string''
|Ei
|-
|'''VATNr'''
|KMKR nr
|''20, string''
|Ei
|-
|'''ExportFlag'''
|Käibemaksutsoon

0 = „Eesti“

1 = „EL“,

2 = „EL (konteeri KM)“,

3 = „Mitte EL“

4 = „Mitte EL (konteeri KM)
|''1, Code''
|Ei
|}
More field descriptions:

[[Hausing - Register Kontaktid|https://kaust.excellent.ee/opendoc/index.php/Hausing_-_Register_Kontaktid]]

''Example of minimal XML body''

''<?xml version="1.0" encoding="UTF-8"?>''

''<nowiki><data register="CUVc" method="create" sequence="106357" systemversion="8.4.20.504"></nowiki>''

''<CUVc>''

''<nowiki><Code>101</Code></nowiki>''

    ''<Name>New Customer LTD</Name>''

    ''<CUType>1</CUType>''

    ''<VEType>0</VEType>''

''</CUVc>''

''<nowiki></data></nowiki>''

''Example of implemented fields XML''

''<nowiki><data register="CUVc" method="create" sequence="271742" systemversion="8.4.20.1204"></nowiki>''

''<CUVc>''

   ''<UUID>EB62BDDB-166D1436-771C5803-96D9E8CF-3D9B4352</UUID>''

   ''<ServerSequence>0</ServerSequence>''

    ''<SyncFlags>1</SyncFlags>''

    ''<nowiki><Code>987654321</Code></nowiki>''

    ''<Name>New Test Company</Name>''

    ''<Person>Annika Ainus</Person>''

    ''<CUType>1</CUType>''

    ''<VEType>0</VEType>''

    ''<WarnText1>Hoiatus</WarnText1>''

    ''<InvAddr0>12 Tänav</InvAddr0>''

    ''<InvAddr1>Linn</InvAddr1>''

    ''<InvAddr2>12345 Maakond</InvAddr2>''

    ''<CustCat>TEST</CustCat>''

    ''<Comment>Kommentaar</Comment>''

    ''<PayDeal>7</PayDeal>''

    ''<InterestFlag>1</InterestFlag>''

    ''<CountryCode>EE</CountryCode>''

    ''<RegNr1>123456789</RegNr1>''

    ''<VATNr>EE112211221</VATNr>''

    ''<ExportFlag>0</ExportFlag>''

''</CUVc>''

''<nowiki></data></nowiki>''

== IVVc (Invoices) ==

=== Create ===
'''Header and footer fields.'''

'''Supported:'''

TransDate, SerNr, InvDate, RefStr, CustCode, PayDeal, PayDate, Addr0, Addr1, Addr2, Addr3, InvAddr3, InvAddr4, Objects, CustCat, SalesMan, CurncyCode, InvComment, PriceList, Sum1, Sum3, Sum4, Location, OKFlag, LangCode, TransTime

'''Required:'''
{| class="wikitable"
|Field
|Description
|Length, type
|Comments
|-
|InvDate
|Arve kuupäev
|0, In Dataformat Order
|Current date by default if empty
|-
|TransDate
|Kande kp.
|0, In Dataformat Order
|Current date by default if empty, used for assigning of SerNr to record
|-
|CustCode
|Kliendi kood
|20, Code String
|Must be existing code in Hansa
|-
|InvType
|Arve tüüp (1=tavaline, 2=sularahaarve, 3=kreeditarve)
|0, Small Value with No Decimals
|Not visible in interface

Supported values: 1,2,3
|-
|PayDeal
|Tasumistingimuse kood
|2, Code String
|Automatically filled for given CustCode, but required if that is empty

Must be existing code in Hansa
|}

'''Row fields.'''

'''Supported:'''

stp, ArtCode, Quant, Price, Spec, SalesAcc, VATCode, Sum

'''Required:'''
{| class="wikitable"
|stp
|Rea tüüp

1 = tavaline
|1, Integer
|Not visible in interface

Supported values: 1
|-
|ArtCode
|Artiklikood
|20, Code String
|Required if row stp == 1
|-
|Quant
|Kogus
|0, Value with minimum Decimals
|Required if row stp == 1
|-
|Price
|Hind
|0, Value with 2 or 3 Decimals
|Required if row stp == 1
|-
|Sum
|Kokku
|0, Value 2 or 3 Decimals
|Required if row stp == 1
|-
|VATCode
|KM kood
|10, Code String
|Required if row stp == 1
|}

=== Example of simple data invoice ===

''<?xml version="1.0" encoding="UTF-8"?>''

''<nowiki><data register="IVVc" method="create" sequence="106357" systemversion="8.4.20.504"></nowiki>''

   ''<IVVc>''

     ''<RefStr>1289</RefStr>''

     ''<CustCode>0012</CustCode>''

     ''<Addr0>Audio Kaubad Eesti AS</Addr0>''

     ''<InvDate>2018.05.28</InvDate>''

     ''<SerNr>181006</SerNr>''

     ''<InvType>1</InvType>''

     ''<Sum1>100</Sum1>''

     ''<Sum3>20</Sum3>''

     ''<Sum4>120</Sum4>''

     ''<OKFlag>0</OKFlag>''

     ''<rows>''

       ''<row rownumber="0">''

         ''<stp>1</stp>''

                       ''<ArtCode>001</ArtCode>''

             ''<Quant>1</Quant>''

             ''<Price>15,59</Price>''

             ''<Sum>15,59</Sum>''

             ''<vRebate />''

            ''<SalesAcc>3100</SalesAcc>''

            ''<Objects>ANNIKA,KAUPO,KONT</Objects>''

             ''<OrdRow />''

           ''<BasePrice>13,00</BasePrice>''

             ''<rowGP>2,59</rowGP>''

             ''<FIFO />''

             ''<Spec>Raadio "Multi"</Spec>''

             ''<VATCode>1</VATCode>''

        ''</row>''

     ''</rows>''

   ''</IVVc>''

''<nowiki></data></nowiki>''

More field descriptions:

[[Hausing - Register Arved|https://kaust.excellent.ee/opendoc/index.php/Hausing_-_Register_Arved]]

=== Delete ===
Allows to delete only records that are allowed to delete by Hansa internal logic. OK-d invoices are not allowed to be deleted.

''General structure template''

<?xml version="1.0" encoding="UTF-8"?>

<nowiki><data register="IVVc" method="delete" sequence="106357" systemversion="8.4.20.504"></nowiki>

<IVVc>

<SerNr>serNr1</SerNr>

</IVVc>

<IVVc>

<SerNr>serNr2</SerNr>

</IVVc>

<nowiki></data></nowiki>

== INVc (Items) ==

==== Create ====
'''Header and footer fields.'''

'''Supported:'''

AlternativeCode, Code, Name, ItemType, UPrice1, InPrice, VATCode

{| class="wikitable"
|Field
|Description
|Length, type
|Comments
|-
|AlternativeCode
|Arve kuupäev
|40, String
|
|-
|Code
|Kood
|20, Code String
|If not presented, Hansa will save as next available ne according to settings
|-
|Name
|Artikli nimetus
|100, String
|Mandatory
|-
|ItemType
|Artikli tüüp (Tavaline, laoartikkel jne. 0=tavaline, 1=laoartikkel, 2=Struktuurartikkel, 3=teenus)
|0, Small Value with No Decimals
|Supported values: 0,1,2,3
|-
|UPrice1
|Baasmüügihind
|0, Value with 2 or 3 Decimals
|
|-
|InPrice
|Ostuhind
|0, Value with All Decimals
|
|-
|VATCode
|Käibemaksukood
|10, Code String
|If presented, must be existing code in Hansa
|}

''Example of minimal XML body''

''<?xml version="1.0" encoding="UTF-8"?>''

''<nowiki><data register="INVc" method="create" sequence="106357" systemversion="8.4.20.504"></nowiki>''

''<INVc>''

   ''<AlternativeCode>your_reference_code</AlternativeCode>''

    ''<Name>Name of the article</Name>''

    ''<ItemType>1</ItemType>''

    ''<UPrice1>100</UPrice1>''

    ''<InPrice>50</InPrice>''

    ''<VATCode>1</VATCode>''

''</INVc>''

''<nowiki></data></nowiki>''

''More field descriptions:''

''[[Hausing - Register Artiklid|https://kaust.excellent.ee/opendoc/index.php/Hausing_-_Register_Artiklid]]''

''Response''

''{''

''"responseType": "INVcCreate",''

''"records": [''

    ''{''

      ''"record": "0",''

      ''"AlternativeCode": "your_reference_code",''

      ''"OKCode": "1",''

      ''"Code": "003"''

    ''}''

  '']''

''}''

== VATCodeBlock (VAT Codes) ==

==== Create ====
'''Header and footer fields.'''

'''Supported:'''

VATCode, ExVatpr, IncVatpr, SalesVATAcc, PaySalesVATAcc, PurchVATAcc, PayPurchVATAcc, Comment, Tax1pr, Tax1Acc, CorSalesVATAcc, CorPurchVATAcc, CredSalesVATAcc, CredPurchVATAcc, TaxMatrixVariance

'''Required:'''

{| class="wikitable"
|Field
|Description
|Length, type
|Comments
|-
|VATCode
|Kood
|10, Code String
|
|-
|ExVatpr
|%-ta
|0, Value with 2 or 3 Decimals
|
|-
|IncVatpr
|% -ga"
|0, Value with 6 Decimals
|
|-
|SalesVATAcc
|Müügi KM
|10, Code String
|Must be existing Account in Hansa
|-
|PaySalesVATAcc
|Laek.KM
|10, Code String
|Must be existing Account in Hansa
|-
|PurchVATAcc
|Ostu KM
|10, Code String
|Must be existing Account in Hansa
|-
|PayPurchVATAcc
|Tas.KM
|10, Code String
|Must be existing Account in Hansa
|-
|Tax1pr
|Maksu %
|0, Value with 2 or 3 Decimals
|
|-
|Tax1Acc
|Maks.konto
|10, Code String
|Must be existing Account in Hansa
|}

''Example of minimal XML body''

''<?xml version="1.0" encoding="UTF-8"?>''

''<nowiki><data register="VATCodeBlock" method="create" sequence="106357" systemversion="8.4.20.504"></nowiki>''

''<VATCodeBlock>''

    ''<VATCode>6</VATCode>''

    ''<ExVatpr>20</ExVatpr>''

    ''<IncVatpr>30</IncVatpr>''

    ''<SalesVATAcc>1010</SalesVATAcc>''

   ''<PaySalesVATAcc>1020</PaySalesVATAcc>''

    ''<PurchVATAcc>3000</PurchVATAcc>''

   ''<PayPurchVATAcc>4000</PayPurchVATAcc>''

    ''<Tax1pr>40</Tax1pr>''

    ''<Tax1Acc>1210</Tax1Acc>''

    ''<Comment>New VAT code</Comment>''

''</VATCodeBlock>''

''<nowiki></data></nowiki>''

=== Response body format ===
Response is in JSON format.

''Content-Type: application/json''

General format template as follows.

Notes:

●     “InsertIVVc” is the type of request, to which the response is sent

●     “records” is array of responses for every passed record in POST request body

●     “record” is a sequence number of the passed record. If 3 records are sent in one POST request, their numbers will be 0,1,2

●     “RefStr” is a reference number which was passed in POST request (mandatory field)

●     “OKCode” can be 0 or 1. 0 means record was incorrect and error occured. 1 means OK.

●     “FaultMsg” - contains the available additional information if the “OKCode” is 0

●     “SerNr” - is a serial number of stored record in Hansa, if the “OKCode” was 1

{

'''"responseType"''':"InsertIVVc",

'''"records"''':[

{

'''"record"''':"recordNumber",

'''"RefStr"''':"givenRefStr",

'''"OKCode"''':"okCode",

'''"FaultMsg"''':"the message"

},

{

'''"record"''':"recordNumber",

'''"RefStr"''':"givenRefStr",

'''"OKCode"''':"okCode",

'''"FaultMsg"''':"the message"

},

{

'''"record"''':"recordNumber",

'''"RefStr"''':"givenRefStr",

'''"OKCode"''':"okCode",

'''"SerNr"''':"assignedSerNumber"

}

]

}

== GET (for reports) ==

=== Request ===

=== With authorization ===
<nowiki>http://username:password@ipAddress</nowiki>:[[About:blank|portNumber]]/WebGETAPI.hal?company=[[About:blank|compNumber]]&report=reportName

Required parameters:

●    compNumber is the sequence number of the company in Hansa DB starting from 1

●    reportName is the internal Books report name

Optional parameters (default value will be selected by Books if missing):

●     periodStart in format dd.mm.yyyy

●     periodEnd in format dd.mm.yyyy

Example:

<nowiki>http://testuser:testpassword@localhost:8989/WebGETAPI.hal?company=1&report=MainRn</nowiki>

=== Response body format ===
In HTML format

== GET Registers (standard) ==
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.

Examples:

<nowiki>http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10101:10104</nowiki>

Will return invoices with customers from 10101 to 10104

<nowiki>http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10104</nowiki>:

Will return invoices with customers from 10104 until the last customer

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

UKU & Standard Books'i API - Redigeerimiste ajalugu

Konstantin: file not found response explained

Konstantin: http and authorization information details

Tanel: /* Response body format */

Tanel: /* Create */

Tanel: Uus lehekülg: '== POST == === Request === ==== With authorization ==== http://username:password@ipAddress:portNumber/WebPOSTAPI.hal?company=About:blank|comp...'