User's guide /

API

OBS2GO ERP allows integration and data exchange with third-party software products, such as other ERP systems, shell scripts, scheduled jobs, and other systems. It produces output in JSON format and uses the OBS ERP privileges module to control 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 password.

How to generate an access token?

Open the control panel and go to the "API" section. Generate a new access token and store it somewhere securely. 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 the "Companies" module:

    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 - indicates the OBS2GO API
1.3. companies - target module
1.4. add - operation type used to insert data
1.5. -d "token={$TOKEN}" - access token
1.6. name - column name
1.7. -X POST - method for issuing 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:

ExitCode: 0 - operation successful; 1 - operation failed
Error - describes the error if the ExitCode is 1
Data.message - contains context-dependent data based on the operation type
Data.object - unique identifier of the newly created object

II. Obtain data

1. Simple filter:

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"

Description:

acme - domain of the ERP instance
api - OBS2GO API
invoices - target module
all - operation type to obtain information
filter__ - limits the results based on key-value pairs
invoices_issue_date - filter key-value pair

Result - JSON 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 JSON keys:

ExitCode: 0 - operation successful; 1 - operation failed
Error - describes the error if ExitCode is 1
Data.data - context-dependent data, including a list of invoices created on the specified date

2. Complex filters:

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"

Description:

multiple_filter__ - keyword used for complex filters with key-value pairs, where the value can be an array of elements
invoices_id - filter key-value pair

Result - JSON format:

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

3. Searching 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"

To specify a custom date field:

    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:

To extract full data, use this method:

    curl -d 'token={$TOKEN}' "https://acme.obs2go.com/api/projects/get_record/1"

5. Getting basic record information:

Similar to the previous method but without related records:

    curl -X POST -d 'token={$TOKEN}' "https://acme.obs2go.com/api/projects/get/1"

6. Ordering:

Specifies order of appearance. Must be ASC or DESC.

    curl -d "token={$TOKEN}" "https://acme.obs2go.com/api/projects/get/1?sort_order=ASC&order_by_column_id=2"

7. Pagination:

Parameters:

page_num - Starts from 0
rowsperpage - Max number of rows, must be between 0 and 100

8. Custom JSON output:

Create custom reports with specific fields. Example:

    curl -d 'token={$TOKEN}' 'https://acme.obs2go.com/api/invoices/all?table_report=true'

III. Update record

Example: Updating record 54 in the "Companies" module, setting the bank account to CB123456789, VAT number to 111222, and company name to "ACME INC":

    curl  -d 'token={$TOKEN}&vat_number=111222&name=ACME INC&bank_account=CB123456789&id=54' "https://acme.obs2go.com/api/companies/edit"

Result:

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

IV. Delete record

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

    curl -d "token={$TOKEN}" "https://acme.obs2go.com/api/companies/del_app_object/56"

Result:

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

V. Copy a specified record

Example: Copying company record 54:

    curl -d "token={$TOKEN}"  "https://acme.obs2go.com/api/companies/copy/54"

Result:

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

VI. Specific operations

Generating invoice, resetting sequence numbers, and more TBD.

VII. Initiate specific process

Example API call for initiating a 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, contact an OBS representative.

VIII. Other endpoints

1. Find a record by a key-value pair (e.g., find warehouse slip related to order ID 3433):

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

Result:

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

2. Getting a specific field:

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

3. Retrieving a value by record ID:

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

< Prev Next >