Balance Exchange Service Description

Using Web-services

With Balance Exchange services it is possible to exchange the following documents: master data, documents and typical operations.

Web-Services can be used with the formats

<ServerIPaddress>/Balance_Exchange/hs/Exchange/<URLtemplate>

The name of the published base must be: Balance_Exchange

<ServerIPaddress> - Server address, where Balance database is published.

<URLtemplate> - Means the object of exchange.

In order to use the function of Balance exchange with web-services, it is necessary to make exchange usage available:

•        Tab “administration”
•        Data synchronization settings
•        Check “WS exchange search settings

Clients

<ServerIPaddress>/Balance_Exchange/hs/Exchange/Clients

•        Create – POST method.
•        Update/Create - PUT method.
•        Modify – PATCH method.
•        Read- GET method.

The description of the services is generated from the program.

Sales> Customers > The description of the services;

Clients agreements

<ServerIPaddress>/Balance_Exchange/hs/Exchange/ClientsAgreements

•        Create - POST method.
•        Update/Create - PUT method.
•        Modify - PATCH method.
•        Read- GET method.

The description of the services is generated from the program.

Sales> Customers > The description of the services;

Master Data - Customer Agreements

Vendors

<ServerIPaddress>/Balance_Exchange/hs/Exchange/Vendors

•        Create - POST method.
•        Update/Create - PUT method.
•        Modify - PATCH method.
•        Read- GET method.

The description of the services is generated from the program.

Purchase > Suppliers> The description of the services;

Vendors agreements

<ServerIPaddress>/Balance_Exchange/hs/Exchange/VendorsAgreements

•        Create - POST method.
•        Update/Create - PUT method.
•        Modify - PATCH method.
•        Read- GET method.

The description of the services is generated from the program.

Purchase > Suppliers> The description of the services;

Master data – Vendor Contracts

Employees

<ServerIPaddress>/Balance_Exchange/hs/Exchange/Employees

•        Create - POST method.
•        Update/Create - PUT method.
•        Modify - PATCH method.
•        Read- GET method.

The description of the services is generated from the program.

Salary> Staff> The description of the services;

Fixed assets

<ServerIPaddress>/Balance_Exchange/hs/Exchange/FixedAssets

•        Create - POST method.
•        Update/Create - PUT method.
•        Modify - PATCH method.
•        Read- GET method.

The description of the services is generated from the program.

Fixed Assets> Fixed Assets > The description of the services;

Items

<ServerIPaddress>/Balance_Exchange/hs/Exchange/Items

•        Create - POST method.
•        Update/Create - PUT method.
•        Modify - PATCHmethod.
•        Read - GET method.

The description of the services is generated from the program.

Warehouse > Item > The description of the services;

ცხრილი: Packages

Typical operations

<ServerIPaddress>/Balance_Exchange/hs/Exchange/TypicalOperations/{TemplateCode}

The parameterTemplateCodeis template’s code.

•        Update/Create - PUT method.

Types, defaultfillings and necessaryfields depend on the template.

The description of the services is generated from the program:

Operations > Typical operations > description of web services;

After choosing the template, server address and description will be generated

Purchase

<ServerIPaddress>/Balance_Exchange/hs/Exchange/Purchase

•        Update/Create - PUT method.

The description of the services is generated from the program.

Purchases > purchase > The description of the services;

ცხრილი: AdvancesPaid

ცხრილი: Others

ცხრილი: Items

Sales

<ServerIPaddress>/Balance_Exchange/hs/Exchange/Sale

•        Update/Create - PUT method.

The description of the services is generated from the program.

Sales > Sale > The description of the services;

ცხრილი: AdvancesPaid

ცხრილი: Others

ცხრილი: Items

Sale order

<ServerIPaddress>/Balance_Exchange/hs/Exchange/SalesOrders

•        Update/Create - PUT method.

The description of the services is generated from the program.

Salees > Sales orders > The description of the services;

ცხრილი: Inventory

ცხრილი: Items

Prices

<ServerIPaddress>/Balance_Exchange/hs/Exchange/Prices

•        Read–With GET method.

Optional parameters: Date, PriceType, Item.

Service returns all item prices for given date (Date).

Service will return item prices for current date if parameters ar not given.

If parameters ar given, returned information can be filtered by given one price type (PriceType) and by given one item (Item). Objects will be identified based on search types, indicated in settings. Search types can be found in Settings.

Simultaniosly it is possible to use one or several filters.

For example, for current date all item prices can be returned with:

<ServerIPaddress>/Balance_Exchange/hs/Exchange/Prices

For given date, given price type and given item, prices can be returned with:

<ServerIPaddress>/Balance_Exchange/hs/Exchange/Prices?Date=""&PriceType=""&Item=""

Items will not be returned if no set price was found for given parameters.

Restrictions:

As a default service have access to all prices for any price type.

It is possible to grant access to prices for one given price type in the program.

To view or edit list of permitted price types, go to:

Administration > Data synchronization settings > All price types are allowed

After entering the price types in the list, service will only have access to item prices for entered price types.

Responses:

400 Invalid date format

404 Price type / Item not found

200 OK

Stocks

<ServerIPaddress>/Balance_Exchange/hs/Exchange/Stocks

•        Read–With GET method.

Optional parameters: Date, Item, Warehouse, Branch.

Service returns all item stocks for given date (Date).

Service will return item stocks for current date if parameters ar not given.

If parameters ar given, returned information can be filtered by given one item (Item), by given one warehouse (Warehouse) and by given one branch (Branch). Objects will be identified based on search types, indicated in settings. Search types can be found in Settings.

Simultaniosly it is possible to use one or several filters.

For example, for current date all item stocks can be returned with:

<ServerIPaddress>/Balance_Exchange/hs/Exchange/Stocks

For given date, given item, given warehouse and given branch, stocks can be returned with:

<ServerIPaddress>/Balance_Exchange/hs/Exchange/Stocks?Date=""&Item=""&Warehouse=""&Branch=""

Items will not be returned if no free stock was found for given parameters.

Restrictions:

As a default service have access to all item stocks for any warehouse.

It is possible to grant access to item stocks for one given warehouse in the program.

To view or edit list of permitted warehouses, go to:

Administration > Data synchronization settings > All warehouses are allowed

After entering the warehouses in the list, service will only have access to item stocks for entered warehouses.

Responses:

400 Invalid date format

404 Item / Warehouse / Branch not found

200 OK

Vendor Balances

<ServerIPaddress>/Balance_Exchange/hs/Exchange/VendorsBalances

•        Read – With GET method.

Optional parameters: Date, Vendor, VendorAgreement, Branch.

Service returns all vendors balances for given date (Date).

Service will return vendors balances for current date if parameters ar not given.

If parameters ar given, returned information can be filtered by given one vendor (Vendor), by given vendor agreement (VendorAgreement) and by given one branch (Branch). Objects will be identified based on search types, indicated in settings. Search types can be found in Settings.

Simultaniosly it is possible to use one or several filters.

For example, for current date all vendors balances can be returned with:

<ServerIPaddress>/Balance_Exchange/hs/Exchange/VendorsBalances

For given date, given vendor, given vendor agreement and given branch, balances can be returned with:

<ServerIPaddress>/Balance_Exchange/hs/Exchange/VendorsBalances?Date=""&Vendor=""&VendorAgreement=""&Branch=""

Vendors will not be returned if no debt balance was found for given parameters.

Responses:

400 Invalid date format

404Vendor / VendorAgreement / Branch not found

200 OK

Client Balances

<ServerIPaddress>/Balance_Exchange/hs/Exchange/ClientsBalances

•        Read – With GET method.

Optional parameters: Date, Client, ClientAgreement, Branch.

Service returns all clients balances for given date (Date).

Service will return clients balances for current date if parameters ar not given.

If parameters ar given, returned information can be filtered by given one client (Client), by given client agreement (ClientAgreement) and by given one branch (Branch). Objects will be identified based on search types, indicated in settings. Search types can be found in Settings.

Simultaniosly it is possible to use one or several filters.

For example, for current date all clients balances can be returned with:

<ServerIPaddress>/Balance_Exchange/hs/Exchange/ClientsBalances

For given date, given client, given client agreement and given branch, balances can be returned with:

<ServerIPaddress>/Balance_Exchange/hs/Exchange/ClientsBalances?Date=""&Client=""&ClientAgreement=""&Branch=""

Clients will not be returned if no debt balance was found for given parameters.

Responses:

400 Invalid date format

404Client / ClientAgreement / Branch not found

200 OK

Description of Web-Services

Catalogs

Web-service description is generated from the program for any Catalog object.

For example, for clients:

•        Select “Sales” tab
•        Select Clients from Master data

Select “Description of Web Services” on list of clients 

List of clients:

Parameters description table and JSON code is generated:

  Agreements

Open description for client or vendor agreements and select desired agreement:

Methods

Create – With POST method.

Only used for new objects.

It is necessary to give all parameters. (Parameters that will not be given, will be filled with default values or will remain empty).

Objects are identified according to settings. If object already exists in the database response will be an error.

New object will get new unique identifier or given uid.

* Used for only one object. Incase of posting catalogue, only the first object will be created.

Responses:

400 Bad Request (JSON cannot be read. E.g. Syntax error.)

400 Invalid uid (Invalid uid was given.)

400 Not saved (Object cannot be saved. Detailed information in the text.)

409 Already exists (Object already exists.)

201 Created (Object was created successfully)

Location: Link of created object. Returns it’s data incase of GET method.

Update/Create – With PUT method.

Existing objects can be updated or created new ones.

It is necessary to give all parameters. (Parameters that will not be given, will be filled with default values or will be cleared/will remain empty).

Objects are identified according to settings. If object cannot be found in database, it will be created. (New object will get new unique identifier or given uid.)

If object has tabular parts, only the necessary table data should be given. If empty parameters will be given, an empty line will be added.

* Used for only one object. Incase of putting catalogue, only the first object will be created / updated.

* Use POST method for creating new objects.

Responses:

400 Bad Request (JSON cannot be read. E.g. Syntax error.)

400 Invalid uid (Invalid uid was given.)

400 Not saved (Object cannot be saved. Detailed information in the text.)

400 Not posted. Required fields are empty

400 Not posted (document cannot be posted. Detailed information in the text.)

404 Template not found

200 OK (Catalog/document updated/posted successfully.)

201 Created (Catalog/document created/posted successfully.)

Location: Link of created object. Returns it’s data using GET method.

Modify – With PATCH method.

Used only for existing objects.

Only those parameters can be given, that need to be updated (Not given parameters won’t be modified).

Objects are identified according to settings. If object cannot be found in database, response will be error.

* Used for only one object. Incase of patching catalogue, only the first object will be modified.

Responses:

400 Bad Request (JSON cannot be read. E.g. Syntax error.)

400 Invalid uid (Invalid uid was given.)

400 Not saved (Object cannot be saved. Detailed information in the text.)

404 Unknown parameter

404 Not Found (Object not found.)

200 OK (Object was modified successfully.)

Read– With GET method.

Used for reading existing objects.

Can read one or more object, or even the whole catalogue.

Method returns JSON code or consequent response.

To read whole catalogue, use same format.

For example, for clients address will be:

<ServerIPaddress>/Balance_Exchange/hs/Exchange/Clients

To read pack of the catalogue, pack number and pack size should be given as a parameter.

For example, to read the third pack of a twenty items, address will be:

ServerIPaddress>/Balance_Exchange/hs/Exchange/Items?Pack=3&PackSize=20

If PackSize is not given as a parameter, default packsize will be 1000

To read one object, use search type and value as a parameter.

For given object, any search type can be used.

For example, to read client, with ID – “01234567890”, address will be:

<ServerIPaddress>/Balance_Exchange/hs/Exchange/Clients?ID=01234567890

Search types can be found insettings.

! Important

* To read client/vendor agreements, additionally can be searched by Owner. With folowing address:

<ServerIPaddress>/Balance_Exchange/hs/Exchange/ClientsAgreements?Owner=01234567890

Owner will be idetified, by search type indicated to client/vendor settings.

Responses:

404 Unknown parameter

400 Invalid uid

404 Not Found (Object not found.)

200 OK (Object was successfully read.)

Search settings

To view or edit search settings, go to;

Administration > Data synchronization settings > WS exchange search settings

Search type can only be selected for listed objects.

Selected search type will be used for identify objects while creating, updating and reading. (Other objects will be identifed with Guid).

E.g. clients van be identified by one of these listed types:

To use desired search type to identify object, select it in the list and press “Save”. After this, you should use this parameter when you want to transfer Client data with web services. This parameter will be used to search objects while updating it or choosing it in the document.

Guid – Generate unique identifier

Guid can be generated for any object, that exists in the database. It can be geneated from list form of desired object (Catalog element/document).

For example, to fill currency with EUR for clients, we should generate Guid of EUR:

•        Select “Sales” tab
•        Select Clients from Master data
•        Select “Description of Web Services” on list of clients
•        Select “Guid Generator”
•        Select Add > Tip > Currency > EUR
•        Unique identifier will generate in Guid column

\

Default fillings

Default Accounts

Accounts, that are filled in default accounts on quick menu tab.

Accounting Currency

Currency indicated in “Accounting currency” on Admnistration tab > Accounting settings > Financial accounting

Default Accrual Type

Value of same constant name. (Is filled with “ხელფასი“ (Salary), by default if it exists in the database.)

Default Price Type

Price type indicated in user settings.

Default Department

Department indicated in user settings.

Default Branch

Branch indicated in user settings.

Default Warehouse

Warehouse indicated in user settings.

Current Currency Rate

Exchange rate of currency indicated in the object for object date.

Description of types

Number – Maximum length with format (Int / Fraction). For rational numbers, maximum length of parameter will be sum of length of integer and fraction part of the number (Int + Fraction).

String -  Maximum length is indicated.

Boolean – Standard JSON format: 'true' / 'false', 1 / 0.

Date – Standard JSON format. E.g: 'yyyy'-'MM'-'dd'T'HH':'mm':'ss'

Catalog – Master data

Is identifed by Guid identifier or it depends on search settings.

Document

Is identifed by Guid identifier

Account

Is identified by account code. (String type.)

List

Is identified by string values from the list.

Analytics

Depends on an account, of which analytics you are filling. (indicated in Type.) Values can be given by it’s own analytics rule.

Guid – Unique Identifier

Format: xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx

List

Legal forms

VAT taxable types

Item correspondence

Waybill correspondence control

Individual gender

Employee status

Leasing status

Fixed assets status

Fixed assets possession form

Depreciation parameters

Item types

Purchase operation types