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:

How to generate an access token?
I. Insert records.
II. Obtain data.
III. Update records.
IV. Delete records.
V. Copy a specific record.
VI. Specific operations
VII. Initiate process step
VIII. Other operations

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.

How to generate an access token?

Open the control panel and go to section "API". Generate a new access token and store it somewhere. Additionally, you can restrict the API access to a specific IP address.

I. Insert records

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

shell# curl -X POST -d "token={$TOKEN}" "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. -d "token={$TOKEN}" - access token;
1.6. name - column name. List of available columns can be found in the "Constructor" module -> the record of target module -> button "Fields";
1.7. -X POST - method. You can skip this option. It simply illustrates that we issue a post request.

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 -X POST -d 'token={$TOKEN}&filter__=[{"invoices_issue_date":"2016-02-04"}]' 
"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 obtained using this method:

# curl -d 'token={$TOKEN}&filter__=[{"invoice_items_record_id":10}]' "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 'token={$TOKEN}&multiple_filter__= [{"invoices_id":[1,2,3,4,5,6,7,8,9,10,11]}]' "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 limits 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  -X POST  -d 'token={$TOKEN}&dates__=[{"start_time":"2011-05-02"},{"end_time":"2016-05-25"}]'
 "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  -X POST  -d 'token={$TOKEN}&dates_map__=[{"check_in":{"start":"2018-06-01","end":"2018-08-15"}}]&dates__=[{"start_time":"2011-05-02"},{"end_time":"2016-05-25"}]'
 "https://acme.obs2go.com/api/invoices/all"

4. Getting full record information:

The method below allows extraction of full data:

curl  -d 'token={$TOKEN}'  "https://acme.obs.bg/api/projects/get_record/1"<200b>

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 -X POST  -d 'token={$TOKEN}' "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 "token={$TOKEN}"  "https://acme.obs.bg/api/projects/get/1?sort_order=ASC&order_by_column_id=2"<200b><200b>

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 "token={$TOKEN}" 'https://acme.obs.bg//api/get_record_by_map/unit_tests/{"name":"George", "surname":"Smith"}'

9. Unformatted numbers
By default the numbers are formatted with comma and dot, e.g. 1,132.50. To swith to raw numbers, you could use the following flag:

curl -d "token={$TOKEN}"  'https://acme.obs.bg/api/invoice_items/all?unformatted_numbers=true

unformatted_numbers - TRUE or FALSE

10. Reading results from SQL functions:

curl -d "token={$TOKEN}"  'https://acme.obs.bg/functions/base64_staff_images?mode=json&rpp=1&page_id=3

Where:
- base64_staff_images - the name of the function created in module "SQL Functions";
- mode=json - returns the data in JSON format;
- rpp=1 - rows per page;
- page_id=3 - page offset.

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 'token={$TOKEN}&vat_number=111222&name=ACME INC&bank_account=CB123456789&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. -H "Authorization: Bearer ${KEY} Role ${ROLE}" - 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.

IV. Delete record

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

# curl -d "token={$TOKEN}" "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. -H "Authorization: Bearer ${KEY} Role ${ROLE}" - access credentials
2.6. 56 - unique identifier of the updated row.

3. Result:

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

V. Copy a specified record

1. Example. Copying company record 54 :

# curl -d "token={$TOKEN}"  "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. -H "Authorization: Bearer ${KEY} Role ${ROLE}" - 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]}}}

VI. Specific operations

generating invoice, resetting sequence numbers and others
TBD

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.

VI. Other endpoints

1. get_record_by_key_val - find record by a key and a value. For example: find a warehouse slip related to order ID 3433

Example

# curl -d "token={$TOKEN}" "https://acme.obs2go.com/api/warehouse_slips/get_record_by_key_val?key=order_id&value=3433

GET Parameters:

key
value

Result

{
  "ExitCode": 0,
  "Error": "",
  "Data": {
    "shipping_terms": null,
    "status_id": 1,
    "tax_amount": null,
    .....
  }
}

2. get_col_by_key_val - the same as the above, but returns only a specific field (faster)

Example

# curl -d "token={$TOKEN}" "https://acme.obs2go.com/api/warehouse_slips/get_col_by_key_val?key=order_id&value=3433&col=id

GET Parameters:

key
value
col

Result

{
  "ExitCode": 0,
  "Error": "",
  "Data": {
      "val": 5901
  }
}

4. get_col_by_id - finds the value of a field in a record.

Example

# curl -d "token={$TOKEN}" "https://acme.obs2go.com/api/users/get_col_by_id?record_id=2&col=username

GET Parameters:

record_id - the id of the record
col - the field value you are checking

{
  "ExitCode": 0,
  "Error": "",
  "Data": {
    "val": "employee"
  }
}

< Prev

API

How to generate an access token?

I. Insert records

II. Obtain data

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

III. Update record

IV. Delete record

V. Copy a specified record

1. Example. Copying company record 54 :

VI. Specific operations

VII. Initiate specific process

VI. Other endpoints

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