Search
User's guide /

API

The OBS ERP API allows integration and data exchange with third party software products, like other ERP systems, shell scripts, scheduled jobs and other systems. It produces output in JSON format and it uses the OBS ERP privileges module to control the access. The latest version of the API allows the following operations:

I. Insert records.
II. Obtain data.
III. Update records.
IV. Delete records.
V. Copy a specific record.
VI. Specific operations - grenerating invoice, reseting sequence numbers and others.
VII. Initiate process step

In order to use the API, you need to have the CONSTRUCTOR module in your ERP instance. Every call to the API should include credentials in the following format: username and pwd.

1. Example: inserting a new record for a company called "TestCompany" in module "Companies":

shell# curl -d 'name=TestCompany&username=jhon&pwd=smith' "https://acme.obs2go.com/api/companies/add"


Parameters:
1.1. acme - domain of the ERP instance;
1.2. api - telling the ERP to use the OBS2GO API;
1.3. companies - target module. List of all available modules can be found in the CONSTRUCTOR module.
1.4. add - operation type used to insert data
1.5. username & pwd - access credentials
1.6. name - column name. List of available columns can be found in the "Constructor" module -> the record of target module -> button "Fields".

Result - the result is a JSON string in the following format:

{"ExitCode":0,"Error":"","Data":{"message":"Record 54 created","object":54}}

Description of the JSON keys:

1.7. ExitCode: 0 - operation successful; 1 - operation failed
1.8. Error - contains value in case the Exit Code is 1. It describes the error that prevented the operation from completing successfully
1.9. Data.message - contains context dependent data based on the operation type. It is translated to the language as per the user's settings.
1.10. Data.object - unique identifier of the newly created object.

II Obtain data

1. Simple filter:
1.1 Example - getting all invoices generated on 2016-02-04:

# curl -d 'filter__=[{"invoices_issue_date":"2016-02-04"}]&username=john&pwd=smith' 
"https://acme.obs2go.com/api/invoices/all"


1.2. Description:
The API call is comprised of the following components:
1.2.1. acme - domain of the ERP instance;
1.2.2. api - OBS2GO API;
1.2.3. invoices - target module. List of all available modules can be found in the CONSTRUCTOR module;
1.2.4. all - operation type used to obtain information
1.2.5. filter__ - calls the simple filter. It limits the results based on key - value pairs;
1.2.6. invoices_issue_date - filter key - value pair. The name of the key is comprised of two parts concateneted with underscore sign (_):
1.2.6.1. invoices - the name of the module
1.2.6.2. issue_date - the name of the field as described in the Constructor

1.3. Result - the result is a JSON string in the following format:

{"ExitCode":0,"Error":"", "Data":{"data":[[10,"Open Business Solutions", "100.00", "20.00","120.00", "2016-3-5 0:0:0"],["id","company","base_amount", "tax_amount", "total_amount","due_date"]]}}



Description of the JSON keys:
1.3.1. ExitCode: 0 - operation successful; 1 - operation failed
1.3.2. Error - contains value in case the Exit Code is 1. It describes the error that prevented the operation from completing successfully
1.3.3. Data.data - contains context dependent data based on the operation type. In this case a list of invoices created on 2016-02-04. The last element of the JSON array contains the names of the fields.

Additionally, the invoice items related to a particular invoice can be extracted the following way:


curl -d 'filter__=[{"invoice_items_record_id":10}]&username=john&pwd=smith' "https://acme.obs2go.com/api/invoices/all"

JSON Response:

{"ExitCode":0,"Error":"","Data":{"data [[2,"test",null,"100.00","CNT","1.00",null,"100.00"],
 ["id","name","description","price_per_unit", "unit","qty","discount","line_total"]]}}



2. Complex filters :
2.1 Example - getting a list of invoices based on their unique ids.

# curl -d 'multiple_filter__= [{"invoices_id":[1,2,3,4,5,6,7,8,9,10,11]}] &username=john&pwd=smith' "https://acme.obs2go.com/api/invoices/all"

2.2. Description:
The API call is comprised of the following components:
2.2.1. acme - domain of the ERP instance;
2.2.2. api - OBS2GO API;
2.2.3. invoices - target module. List of all available modules can be found in the CONSTRUCTOR module;
2.2.4. all - operation type used to obtain information.
2.2.5. multiple_filter__ - a keyword used to call the complex filter. It imits the result based on key - value pairs. The value can be an array of elements;
2.2.6. invoices_id - filter key - value pair. The name of the key is comprised of two parts concateneted with underscore sign (_):
2.2.6.1. invoices - the name of the module
2.2.6.2. id - the name of the field as described in the CONSTRUCTOR

2.3. Result - the result is a JSON string in the following format:

{"ExitCode":0,"Error":"","Data":{"data":[[]]}}

Description of the JSON keys:
2.3.1. ExitCode: 0 - operation successful; 1 - operation failed
2.3.2. Error - contains value in case the Exit Code is 1. It describes the error that prevented the operation from completing successfully
2.3.3. Data.message - contains context dependent data based on the operation type. In this case a list of invoices created on 2016-02-04. The last element of the JSON array contains the names of the fields.

3. Searching all records created between two dates:

curl -d 'dates__=[{"start_time":"2011-05-02"},{"end_time":"2016-05-25"}]&username=john&pwd=smith'
 "https://acme.obs2go.com/api/invoices/all"

3.1. Pointing custom date field:

Use date_field key to specify a custom date field, e.g. date_field=created_at

3.2. Searching by multiple date fields: 

dates_map__: contains a json as shown below

curl -d 'dates_map__=[{"check_in":{"start":"2018-06-01","end":"2018-08-15"}}]&dates__=[{"start_time":"2011-05-02"},{"end_time":"2016-05-25"}]&username=john&pwd=smith'
 "https://acme.obs2go.com/api/invoices/all"

4. Getting full record information:

The method below allows extraction of full data:

curl -d 'username=john&pwd=smith' "https://acme.obs.bg/api/projects/get_record/1"​

The get_record method provides full information about a record. It lists related information about related records as well.

5. Getting full record information:

Same as point 4, but without information about related records

curl -d 'username=john&pwd=smith' "https://acme.obs.bg/api/projects/get/1"​​

5. Ordering

sort_order - Specifies the order of appearance. Must be one of ASC or DESC
order_by_column_id - Specifies the ID of the column to order the results. Starting from 1 to N

curl -d 'username=john&pwd=smith' "https://acme.obs.bg/api/projects/get/1?sort_order=ASC&order_by_column_id=2"​​

6. Pagination

page_num - Starting from 0 to N
rowsperpage - Specifies the maximum number of rows returned. The value must be from 0 to 100.

7. Custom JSON output

To create custom JSON output containing specific fields, you need to create a custom report in OBS ERP.
Open the module and using the gearbox above the table specify the columns you would like to see in your custom report. As soon as you are happy with the result, you can obtain the report using the API:

table_report - boolean. Accepts 0, 1, true or false. Specifies if custom report should be obtained. In case custom reports are not present, the default report will be returned

8. Getting record information by key => value:

curl -d 'username=john&pwd=smith' 'https://acme.obs.bg//api/get_record_by_map/unit_tests/{"name":"George", "surname":"Smith"}'

III. Update record

In order to update a record, the user needs to specify the unique ID of the record that will be updated in the API call. As an example, let us update record 54 in the "Companies" module.
1. Example
Setting bank account to CB123456789, VAT registration number to 111222 and company name to "ACME INC" is done the following way:

# curl -d 'vat_number=111222&name=ACME INC&bank_account=CB123456789&username=jhon&pwd=smith&id=54' 
"https://acme.obs2go.com/api/companies/edit"

2. Description:
2.1. acme - domain of the ERP instance;
2.2. api - telling the ERP to use the OBS2GO API;
2.3. companies - target module. List of all available modules can be found in the CONSTRUCTOR module.
2.4. edit - operation type used to update a record.
2.5. username & pwd - access credentials
2.6. id - unique identifier of the updated row.
2.7. vat_number, name, bank_account - update fields. List of available fields can be found in the "Constructor" module -> the record of target module -> button "Fields".

3. Result:

{"ExitCode":0,"Error":"","Data":{"message":"Record 54 updated","object":54}}

Description of the JSON keys:
3.1. ExitCode: 0 - operation successful; 1 - operation failed
3.2. Error - contains value in case the Exit Code is 1. It describes the error that prevented the operation from completing successfully
3.3. Data.message - contains context dependent data based on the operation type.

1. Example. Deleting record 56 from the "Companies" module:

# curl -d 'username=jhon&pwd=smith' "https://acme.obs2go.com/api/companies/del_app_object/56

2. Description:
2.1. acme - domain of the ERP instance;
2.2. api - telling the ERP to use the OBS2GO API;
2.3. companies - target module. List of all available modules can be found in the CONSTRUCTOR module.
2.4. del_app_object - operation type used to delete a record.
2.5. username & pwd - access credentials
2.6. 56 - unique identifier of the updated row.

3. Result:

{"ExitCode":0,"Error":"","Data":{"message":"Record 56 deleted","object":56}}

Description of the JSON keys:
3.1. ExitCode: 0 - operation successful; 1 - operation failed
3.2. Error - contains value in case the Exit Code is 1. It describes the error that prevented the operation from completing successfully
3.3. Data.message - contains context dependent data based on the operation type.

1. Example. Copying company record 54 :

# curl -d 'username=jhon&pwd=smith' "https://acme.obs2go.com/api/companies/copy/54

2. Description:
2.1. acme - domain of the ERP instance;
2.2. api - telling the ERP to use the OBS2GO API;
2.3. companies - target module. List of all available modules can be found in the CONSTRUCTOR module.
2.4. copy - operation type used to copy a record.
2.5. username & pwd - access credentials
2.6. 56 - unique identifier of the updated row.

Note: all fields that have an unique constraint will be renamed to a temporary name following this convention

[8 character random string]_originalname

3. Result:

{"ExitCode":0,"Error":"","Data":{"data":{"companies":[57]}}}

Description of the JSON keys:
3.1. ExitCode: 0 - operation successful; 1 - operation failed
3.2. Error - contains value in case the Exit Code is 1. It describes the error that prevented the operation from completing successfully
3.3. Data.data - the ID of the newly created record


VII. Initiate specific process

http://d.obs.bg/api/quotations/process/1?
&mode=process
&id_=1
&module=quotations
&process_name=status_id
&step_id=7

For custom use cases, please contact OBS representative.