UKU & Standard Books'i API: erinevus redaktsioonide vahel

Allikas: Excellent || Opendoc
Mine navigeerimisribale Mine otsikasti
(Uus lehekülg: '== POST == === Request === ==== With authorization ==== <nowiki>http://username:password@ipAddress</nowiki>:portNumber/WebPOSTAPI.hal?company=About:blank|comp...')
 
4. rida: 4. rida:


==== With authorization ====
==== With authorization ====
<nowiki>http://username:password@ipAddress</nowiki>:[[About:blank|portNumber]]/WebPOSTAPI.hal?company=[[About:blank|compNumber]]&param2=value&param3=value
<syntaxhighlight>
http://username:password@ipAddress:portNumber/WebPOSTAPI.hal?company=compNumber&param2=value&param3=value
</syntaxhighlight>''UKU testdatabase:''<syntaxhighlight>
https://s001.excellent.ee:6443/WebPOSTAPI.hal?company=1
</syntaxhighlight>Companies implemented 1,2,3,4,5


UKU testdatabase:
'''User''': API


<nowiki>https://s001.excellent.ee:6443/WebPOSTAPI.hal?company=1</nowiki>
'''Password''': api
 
Companies implemented 1,2,3,4,5
 
User: API
 
Password: api


Required parameters:  
Required parameters:  
 
* compNumber is the sequence number of the company in Hansa DB starting from 1  
●    compNumber is the sequence number of the company in Hansa DB starting from 1
 
Optional parameters:  
Optional parameters:  
 
* TBD  
TBD
Example: <syntaxhighlight>
 
http://testuser:testpassword@localhost:8989/WebPOSTAPI.hal?company=1
Example:  
</syntaxhighlight>
 
<nowiki>http://testuser:testpassword@localhost:8989/WebPOSTAPI.hal?company=1</nowiki>


==== Request headers ====
==== Request headers ====
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
* ''JSON not supported at the moment''
 
''JSON not supported at the moment''


==== Request body (POST data) format ====
==== Request body (POST data) format ====
41. rida: 33. rida:


Notes:
Notes:
 
* <rows> element is optional;
●    <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
●     IVVc is the internal system name of Invoice register in Hansa. Only following registers are supported at the moment:
** CUVc - Contacts
 
** INVc - Items
○     IVVc - Invoices
* 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.''
○     CUVc - Contacts
* “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.
○     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) ==
== CUVc (Contacts) ==
70. rida: 53. rida:
|'''Kohustuslik'''
|'''Kohustuslik'''
|-
|-
|'''RefStr'''
|'''''RefStr'''''
|Ostu viide
|Ostu viide
|''60,  string''
|''60,  string''
|Ei
|Ei
|-
|-
|'''Code'''
|'''''Code'''''
|Kontakti kood  HansaWorldi tarkvaras. Unikaalne per kontakt
|Kontakti kood  HansaWorldi tarkvaras. Unikaalne per kontakt
|''20,  code''
|''20,  code''
|Jah
|Jah
|-
|-
|'''Name'''
|'''''Name'''''
|Kontakti nimi
|Kontakti nimi
|''200,  string''
|''200,  string''
|Jah
|Jah
|-
|-
|'''CUType'''
|'''''CUType'''''
|Kliendi linnuke. 0 =  ei ole; 1 = on
|Kliendi linnuke. 0 =  ei ole; 1 = on
|''0,  flag''
|''0,  flag''
|Jah
|Jah
|-
|-
|'''VEType'''
|'''''VEType'''''
|Hankija linnuke. 0 =  ei ole; 1 = on
|Hankija linnuke. 0 =  ei ole; 1 = on
|''0,  flag''
|''0,  flag''
|Jah
|Jah
|-
|-
|'''Person'''
|'''''Person'''''
|Kontaktisik
|Kontaktisik
|''60,  string''
|''60,  string''
|Ei
|Ei
|-
|-
|'''WarnText1'''
|'''''WarnText1'''''
|Hoiatus
|Hoiatus
|''255,  string''
|''255,  string''
|Ei
|Ei
|-
|-
|'''InvAddr0'''
|'''''InvAddr0'''''
|Aadress, rida 1
|Aadress, rida 1
|''60,  string''
|''60,  string''
|Ei
|Ei
|-
|-
|'''InvAddr1'''
|'''''InvAddr1'''''
|Aadress, rida 2
|Aadress, rida 2
|''60,  string''
|''60,  string''
|Ei
|Ei
|-
|-
|'''InvAddr2'''
|'''''InvAddr2'''''
|Aadress, rida 3
|Aadress, rida 3
|''60,  string''
|''60,  string''
|Ei
|Ei
|-
|-
|'''CustCat'''
|'''''CustCat'''''
|Kliendiklass
|Kliendiklass
|''5,  code''
|''5,  code''
|Ei
|Ei
|-
|-
|Comment
|'''''Comment'''''
|Kommentaar
|Kommentaar
|''60,  string''
|''60,  string''
|Ei
|Ei
|-
|-
|'''PayDeal'''
|'''''PayDeal'''''
|Tasumistingimus
|Tasumistingimus
|''2,  code''
|''2,  code''
|Ei
|Ei
|-
|-
|'''CountryCode'''
|'''''CountryCode'''''
|Riigi kood
|Riigi kood
|''5,  Code''
|''5,  Code''
|Ei
|Ei
|-
|-
|'''RegNr1'''
|'''''RegNr1'''''
|Registreerimisnumber  1. Eestis Äriregistri kood
|Registreerimisnumber  1. Eestis Äriregistri kood
|''20, string'' 
|''20, string'' 
|Ei
|Ei
|-
|-
|'''VATNr'''
|'''''VATNr'''''
|KMKR nr
|KMKR nr
|''20, string'' 
|''20, string'' 
|Ei
|Ei
|-
|-
|'''ExportFlag'''
|'''''ExportFlag'''''
|Käibemaksutsoon
|Käibemaksutsoon


167. rida: 150. rida:
More field descriptions:
More field descriptions:


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


''Example of minimal XML body''  
==== ''Example of minimal XML body:'' ====
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<data register="CUVc" method="create" sequence="106357" systemversion="8.4.20.504">
  <CUVc>
      <Code>101</Code>
      <Name>New Customer LTD</Name>
      <CUType>1</CUType>
      <VEType>0</VEType>
  </CUVc>
</data>
</syntaxhighlight>


''<?xml version="1.0" encoding="UTF-8"?>''
==== ''Example of implemented fields XML'' ====
 
<syntaxhighlight lang="xml">
''<nowiki><data register="CUVc" method="create" sequence="106357" systemversion="8.4.20.504"></nowiki>''
<?xml version="1.0" encoding="UTF-8"?>
 
<data register="CUVc" method="create" sequence="271742" systemversion="8.4.20.1204">
  ''<CUVc>''
  <CUVc>
 
      <UUID>EB62BDDB-166D1436-771C5803-96D9E8CF-3D9B4352</UUID>
''<nowiki><Code>101</Code></nowiki>''
      <ServerSequence>0</ServerSequence>
 
      <SyncFlags>1</SyncFlags>
    ''<Name>New Customer LTD</Name>''
      <Code>987654321</Code>
 
      <Name>New Test Company</Name>
    ''<CUType>1</CUType>''
      <Person>Annika Ainus</Person>
 
      <CUType>1</CUType>
    ''<VEType>0</VEType>''
      <VEType>0</VEType>
 
      <WarnText1>Hoiatus</WarnText1>
  ''</CUVc>''
      <InvAddr0>12 Tänav</InvAddr0>
 
      <InvAddr1>Linn</InvAddr1>
''<nowiki></data></nowiki>'' 
      <InvAddr2>12345 Maakond</InvAddr2>
 
      <CustCat>TEST</CustCat>
''Example of implemented fields XML'' 
      <Comment>Kommentaar</Comment>
 
      <PayDeal>7</PayDeal>
''<nowiki><data register="CUVc" method="create" sequence="271742" systemversion="8.4.20.1204"></nowiki>''
      <InterestFlag>1</InterestFlag>
 
      <CountryCode>EE</CountryCode>
  ''<CUVc>''
      <RegNr1>123456789</RegNr1>
 
      <VATNr>EE112211221</VATNr>
   ''<UUID>EB62BDDB-166D1436-771C5803-96D9E8CF-3D9B4352</UUID>''
      <ExportFlag>0</ExportFlag>  
 
  </CUVc>
   ''<ServerSequence>0</ServerSequence>''
</data>
 
</syntaxhighlight>
    ''<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) ==
== IVVc (Invoices) ==
250. rida: 205. rida:
'''Required:'''
'''Required:'''
{| class="wikitable"
{| class="wikitable"
|Field
|'''Field'''
|Description
|'''Description'''
|Length,  type
|'''Length,  type'''
|Comments
|'''Comments'''
|-
|-
|InvDate
|'''''InvDate'''''
|Arve  kuupäev
|Arve  kuupäev
|0, In  Dataformat Order
|0, In  Dataformat Order
|Current  date by default if empty
|Current  date by default if empty
|-
|-
|TransDate
|'''''TransDate'''''
|Kande kp.
|Kande kp.
|0, In  Dataformat Order
|0, In  Dataformat Order
|Current  date by default if empty, used for assigning of SerNr to record
|Current  date by default if empty, used for assigning of SerNr to record
|-
|-
|CustCode
|'''''CustCode'''''
|Kliendi  kood
|Kliendi  kood
|20, Code  String
|20, Code  String
|Must be existing code in Hansa
|Must be existing code in Hansa
|-
|-
|InvType
|'''''InvType'''''
|Arve tüüp  (1=tavaline,  2=sularahaarve, 3=kreeditarve)
|Arve tüüp  (1=tavaline,  2=sularahaarve, 3=kreeditarve)
|0, Small  Value with No Decimals
|0, Small  Value with No Decimals
277. rida: 232. rida:
Supported  values: 1,2,3
Supported  values: 1,2,3
|-
|-
|PayDeal
|'''''PayDeal'''''
|Tasumistingimuse  kood
|Tasumistingimuse  kood
|2, Code  String
|2, Code  String
293. rida: 248. rida:
'''Required:'''
'''Required:'''
{| class="wikitable"
{| class="wikitable"
|stp
|'''''stp'''''
|Rea tüüp
|Rea tüüp


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


=== Example of simple data invoice === 
==== ''Example of simple data invoice:'' ====
 
<syntaxhighlight lang="xml">
''<?xml version="1.0" encoding="UTF-8"?>''
<?xml version="1.0" encoding="UTF-8"?>
 
<data register="IVVc" method="create" sequence="106357" systemversion="8.4.20.504">
 ''<nowiki><data register="IVVc" method="create" sequence="106357" systemversion="8.4.20.504"></nowiki>''
  <IVVc>
 
      <RefStr>1289</RefStr>
   ''<IVVc>''
      <CustCode>0012</CustCode>
 
      <Addr0>Audio Kaubad Eesti AS</Addr0>
     ''<RefStr>1289</RefStr>''
      <InvDate>2018.05.28</InvDate>
 
      <SerNr>181006</SerNr>
     ''<CustCode>0012</CustCode>''
      <InvType>1</InvType>
 
      <Sum1>100</Sum1>
     ''<Addr0>Audio Kaubad Eesti AS</Addr0>''
      <Sum3>20</Sum3>
 
      <Sum4>120</Sum4>
     ''<InvDate>2018.05.28</InvDate>''
      <OKFlag>0</OKFlag>
 
      <rows>
     ''<SerNr>181006</SerNr>''
        <row rownumber="0">
 
            <!-- required, number defines the row in Hansa, starts with 0 -->
     ''<InvType>1</InvType>''
            <stp>1</stp>
 
            <ArtCode>001</ArtCode>
     ''<Sum1>100</Sum1>''
            <Quant>1</Quant>
 
            <Price>15,59</Price>
     ''<Sum3>20</Sum3>''
            <Sum>15,59</Sum>
 
            <vRebate />
     ''<Sum4>120</Sum4>''
            <SalesAcc>3100</SalesAcc>
 
            <Objects>ANNIKA,KAUPO,KONT</Objects>
     ''<OKFlag>0</OKFlag>''
            <OrdRow />
 
            <BasePrice>13,00</BasePrice>
     ''<rows>''
            <rowGP>2,59</rowGP>
 
            <FIFO />
       ''<row rownumber="0"><!-- required, number defines the row in Hansa, starts with 0 -->''
            <Spec>Raadio "Multi"</Spec>
 
            <VATCode>1</VATCode>
         ''<stp>1</stp>''
        </row>
 
      </rows>
                       ''<ArtCode>001</ArtCode>''
  </IVVc>
 
</data>
             ''<Quant>1</Quant>''
</syntaxhighlight>More field descriptions:
 
             ''<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]]  
[[Hausing - Register Arved|https://kaust.excellent.ee/opendoc/index.php/Hausing_-_Register_Arved]]  
403. rida: 326. rida:
Allows to delete only records that are allowed to delete by Hansa internal logic. OK-d invoices are not allowed to be deleted.
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'' 
''General structure template''<syntaxhighlight lang="xml">
 
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
 
<data register="IVVc" method="delete" sequence="106357" systemversion="8.4.20.504">
<nowiki><data register="IVVc" method="delete" sequence="106357" systemversion="8.4.20.504"></nowiki>
  <IVVc>
 
      <SerNr>serNr1</SerNr>
<IVVc>
  </IVVc>
 
  <IVVc>
<SerNr>serNr1</SerNr>
      <SerNr>serNr2</SerNr>
 
  </IVVc>
</IVVc>
</data>
 
</syntaxhighlight>
<IVVc>
 
<SerNr>serNr2</SerNr>
 
</IVVc>
 
<nowiki></data></nowiki> 


== INVc (Items) ==
== INVc (Items) ==


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


433. rida: 348. rida:


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


''Example of minimal XML body''
==== ''Example of minimal XML body'' ====
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<data register="INVc" method="create" sequence="106357" systemversion="8.4.20.504">
  <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>
</data>
</syntaxhighlight>More field descriptions:


''<?xml version="1.0" encoding="UTF-8"?>''
[[Hausing - Register Artiklid|https://kaust.excellent.ee/opendoc/index.php/Hausing_-_Register_Artiklid]]


''<nowiki><data register="INVc" method="create" sequence="106357" systemversion="8.4.20.504"></nowiki>''
==== ''Response:'' ====
 
<syntaxhighlight lang="json">
  ''<INVc>''
{
 
  "responseType": "INVcCreate",
   ''<AlternativeCode>your_reference_code</AlternativeCode>''
  "records": [
 
    {
    ''<Name>Name of the article</Name>''
      "record": "0",
 
      "AlternativeCode": "your_reference_code",
    ''<ItemType>1</ItemType>''
      "OKCode": "1",
 
      "Code": "003"
    ''<UPrice1>100</UPrice1>''
    }
 
    ]
    ''<InPrice>50</InPrice>''
}
 
</syntaxhighlight>
    ''<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) ==
== VATCodeBlock (VAT Codes) ==


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


538. rida: 433. rida:


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


''Example of minimal XML body''
==== ''Example of minimal XML body'' ====
 
<syntaxhighlight lang="xml">
''<?xml version="1.0" encoding="UTF-8"?>''
<?xml version="1.0" encoding="UTF-8"?>
 
<data register="VATCodeBlock" method="create" sequence="106357" systemversion="8.4.20.504">
''<nowiki><data register="VATCodeBlock" method="create" sequence="106357" systemversion="8.4.20.504"></nowiki>''
  <VATCodeBlock>
 
      <VATCode>6</VATCode>
  ''<VATCodeBlock>''
      <ExVatpr>20</ExVatpr>
 
      <IncVatpr>30</IncVatpr>
    ''<VATCode>6</VATCode>''
      <SalesVATAcc>1010</SalesVATAcc>
 
      <PaySalesVATAcc>1020</PaySalesVATAcc>
    ''<ExVatpr>20</ExVatpr>''
      <PurchVATAcc>3000</PurchVATAcc>
 
      <PayPurchVATAcc>4000</PayPurchVATAcc>
    ''<IncVatpr>30</IncVatpr>''
      <Tax1pr>40</Tax1pr>
 
      <Tax1Acc>1210</Tax1Acc>
    ''<SalesVATAcc>1010</SalesVATAcc>''
      <Comment>New VAT code</Comment>
 
  </VATCodeBlock>
   ''<PaySalesVATAcc>1020</PaySalesVATAcc>''
</data>
 
</syntaxhighlight>
    ''<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 body format ===
629. rida: 511. rida:


Notes:
Notes:
 
* “InsertIVVc” is the type of request, to which the response is sent
●     “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
●     “records”  is array of responses for every passed record in POST request body
* “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.
●     “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
* “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
●     “RefStr” is a reference number which was passed in POST request (mandatory field)
<syntaxhighlight lang="json">
 
{
●     “OKCode” can be 0 or 1. 0 means record was incorrect and error occured. 1 means OK.
  "responseType":"InsertIVVc",
 
  "records":[
●     “FaultMsg” - contains the available additional information if the “OKCode” is 0
      {
 
        "record":"recordNumber",
●     “SerNr” - is a serial number of stored record in Hansa, if the “OKCode” was 1
        "RefStr":"givenRefStr",
 
        "OKCode":"okCode",
{ 
        "FaultMsg":"the message"
 
      },
'''"responseType"''':"InsertIVVc",
      {
 
        "record":"recordNumber",
'''"records"''':[ 
        "RefStr":"givenRefStr",
 
        "OKCode":"okCode",
{ 
        "FaultMsg":"the message"
 
      },
'''"record"''':"recordNumber",
      {
 
        "record":"recordNumber",
'''"RefStr"''':"givenRefStr",
        "RefStr":"givenRefStr",
 
        "OKCode":"okCode",
'''"OKCode"''':"okCode",
        "SerNr":"assignedSerNumber"
 
      }
'''"FaultMsg"''':"the message"
  ]
 
},
 
{ 
 
'''"record"''':"recordNumber",
 
'''"RefStr"''':"givenRefStr",
 
'''"OKCode"''':"okCode",
 
'''"FaultMsg"''':"the message"
 
},
 
{ 
 
'''"record"''':"recordNumber",
 
'''"RefStr"''':"givenRefStr",
 
'''"OKCode"''':"okCode",
 
'''"SerNr"''':"assignedSerNumber"
 
}
}


]
</syntaxhighlight>
 
}


== GET (for reports) ==
== GET (for reports) ==
695. rida: 550. rida:


=== With authorization ===
=== With authorization ===
<nowiki>http://username:password@ipAddress</nowiki>:[[About:blank|portNumber]]/WebGETAPI.hal?company=[[About:blank|compNumber]]&report=reportName
<syntaxhighlight>
 
http://username:password@ipAddress:portNumber/WebGETAPI.hal?company=compNumber&report=reportName
Required parameters:
</syntaxhighlight>Required parameters:
 
* compNumber is the sequence number of the company in Hansa DB starting from 1
●    compNumber is the sequence number of the company in Hansa DB starting from 1
* reportName is the internal Books report name
 
●    reportName is the internal Books report name
 
Optional parameters (default value will be selected by Books if missing):
Optional parameters (default value will be selected by Books if missing):
 
* periodStart in format dd.mm.yyyy
●     periodStart in format dd.mm.yyyy
* periodEnd in format dd.mm.yyyy
 
''Example'': <syntaxhighlight>
●     periodEnd in format dd.mm.yyyy
http://testuser:testpassword@localhost:8989/WebGETAPI.hal?company=1&report=MainRn
 
</syntaxhighlight>
Example:  
 
<nowiki>http://testuser:testpassword@localhost:8989/WebGETAPI.hal?company=1&report=MainRn</nowiki>


=== Response body format ===
=== Response body format ===
In HTML format
''*In HTML format*''


== GET Registers (standard) ==
== GET Registers (standard) ==
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:<syntaxhighlight>
 
http://hostname.domain.top/api/1/IVVc
<nowiki>http://hostname.domain.top/api/1/IVVc</nowiki>
</syntaxhighlight>where: 
 
* "api" is a mandatory hardcoded string 
where: 
* "1" is the company code from the companies setting (1st column) 
 
* "IVVc" is the name of the register 
"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.
This would fetch all invoices in company 1.


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


=== Data Format ===
=== Data Format ===
The data format for request and returned data is the same and hardcoded.
The data format for request and returned data is the same and hardcoded.
 
* The decimal point is "." (period)
The decimal point is "." (period) 
* There is no thousand separator
 
* Dates are in ISO format YYYY-MM-DD
There is no thousand separator 
 
Dates are in ISO format YYYY-MM-DD


=== Parameters ===
=== Parameters ===
750. rida: 590. rida:
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.


Example: 
''Example'': <syntaxhighlight>
 
http://hostname.domain.top/api/1/IVVc?sort=CustCode
<nowiki>http://hostname.domain.top/api/1/IVVc?sort=CustCode</nowiki>
</syntaxhighlight>


==== range ====
==== range ====
759. rida: 599. 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.


Examples: 
''Examples'': <syntaxhighlight>
 
http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10101:10104
<nowiki>http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10101:10104</nowiki> 
</syntaxhighlight>Will return invoices with customers from 10101 to 10104<syntaxhighlight>
 
http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10104
Will return invoices with customers from 10101 to 10104
</syntaxhighlight>Will return invoices with customers from 10104 until the last customer<syntaxhighlight>
 
http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10104
<nowiki>http://hostname.domain.top/api/1/IVVc?sort=CustCode&range=10104</nowiki>
</syntaxhighlight>Will return invoices only for customer 10104
 
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.
the range parameter is fast to use because it uses an index.
778. rida: 612. 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: 
Example: <syntaxhighlight>
 
http://hostname.domain.top/api/1/IVVc?fields=SerNr,OKFlag,Addr0,ArtCode,CustCode,InvDate,TransDate,Objects
<nowiki>http://hostname.domain.top/api/1/IVVc?fields=SerNr,OKFlag,Addr0,ArtCode,CustCode,InvDate,TransDate,Objects</nowiki>
</syntaxhighlight>


==== filter ====
==== filter ====
788. rida: 622. rida:


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.
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 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
There can be multiple filters on different fields 
* 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"
Filters can handle ranges of values, with the same syntax as range, including open ranges 
''Example'': <syntaxhighlight>
 
http://hostname.domain.top/api/1/IVVc?filter.CustCode=10100:10200&Sum4=100:1000
Filters work only on header fields 
</syntaxhighlight>Will retrieve invoices with a total sum of 100 to 1000 for customers in the range 10100 to 10200.
 
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 ====
==== offset and limit ====
810. rida: 636. rida:
The offset will skip the specified number of records before producing output and the limit will restrict the number of records retrieved.
The offset will skip the specified number of records before producing output and the limit will restrict the number of records retrieved.


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


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


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


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


will retrieve the 15 first invoices in 3 separate requests. 
</syntaxhighlight>will retrieve the 15 first invoices in 3 separate requests.


offset and limit works together will all other parameters
offset and limit works together will all other parameters
827. rida: 655. 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: 
''Example'': <syntaxhighlight>
 
http://hostname/api/1/IVVc?updates_after=5000
<nowiki>http://hostname/api/1/IVVc?updates_after=5000</nowiki>
</syntaxhighlight>


==== deletes_after ====
==== deletes_after ====
836. rida: 664. 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: 
''Example'': <syntaxhighlight>
 
http://hostname/api/1/IVVc?deletes_after=5000
<nowiki>http://hostname/api/1/IVVc?deletes_after=5000</nowiki>
</syntaxhighlight>

Redaktsioon: 5. juuli 2018, kell 11:21

POST

Request

With authorization

http://username:password@ipAddress:portNumber/WebPOSTAPI.hal?company=compNumber&param2=value&param3=value

UKU testdatabase:

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

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:

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

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 <data> element of request body, but is subject to review and may be moved to URL as parameter instead.
  • Possible to pass several <IVVc> elements to send several records.
  • “method” attribute of the <data> element defines the action. Actions supported at the moment: “create”, “delete”.
  • 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

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:

https://kaust.excellent.ee/opendoc/index.php/Hausing_-_Register_Kontaktid

Example of minimal XML body:

<?xml version="1.0" encoding="UTF-8"?>
<data register="CUVc" method="create" sequence="106357" systemversion="8.4.20.504">
   <CUVc>
      <Code>101</Code>
      <Name>New Customer LTD</Name>
      <CUType>1</CUType>
      <VEType>0</VEType>
   </CUVc>
</data>

Example of implemented fields XML

<?xml version="1.0" encoding="UTF-8"?>
<data register="CUVc" method="create" sequence="271742" systemversion="8.4.20.1204">
   <CUVc>
      <UUID>EB62BDDB-166D1436-771C5803-96D9E8CF-3D9B4352</UUID>
      <ServerSequence>0</ServerSequence>
      <SyncFlags>1</SyncFlags>
      <Code>987654321</Code>
      <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>
</data>

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:

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:

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"?>
<data register="IVVc" method="create" sequence="106357" systemversion="8.4.20.504">
   <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">
            <!-- required, number defines the row in Hansa, starts with 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>
</data>

More field descriptions:

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"?>
<data register="IVVc" method="delete" sequence="106357" systemversion="8.4.20.504">
   <IVVc>
      <SerNr>serNr1</SerNr>
   </IVVc>
   <IVVc>
      <SerNr>serNr2</SerNr>
   </IVVc>
</data>

INVc (Items)

Create

Header and footer fields.

Supported:

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

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"?>
<data register="INVc" method="create" sequence="106357" systemversion="8.4.20.504">
   <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>
</data>

More field descriptions:

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:

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"?>
<data register="VATCodeBlock" method="create" sequence="106357" systemversion="8.4.20.504">
   <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>
</data>

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

http://username:password@ipAddress:portNumber/WebGETAPI.hal?company=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:

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

Response body format

*In HTML format*

GET Registers (standard)

Requests specify the company and resource to read, in the most basic format:

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

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:

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

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.

Examples

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

Will return invoices with customers from 10101 to 10104

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

Will return invoices with customers from 10104 until the last customer

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.

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. it is specified like this:

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

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

http://hostname.domain.top/api/1/IVVc?filter.CustCode=10100:10200&Sum4=100:1000

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

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

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