JSON API

Purpose & Use Cases

JSON API lets partner applications attach extra data to the records stored in Erply—"extend" the records with custom data.

In Erply's data model, each record has one additional JSON field. The tables in the database have the following layout:

This JSON field:

1. Is intended to be shared by all applications that need to write and read extra data.
2. Has a global schema defining fields it may contain. The schema is the same for all Erply accounts.

Thus, storing extended data in JSON is best suited for common applications that will be used by many customers. Fields that we will add to the schema should generally benefit many customers and their meaning should be well-understood, allowing applications to interoperate on the data if needed.

For building custom integrations, you may prefer to use attributes. Attributes can be defined ad-hoc and do not require a schema.

Use cases supported:

1. Attach JSON to a record. (One by one, or in bulk.)
2. Retrieve the JSON attached to a record.
3. Remove the JSON attached to a record.
4. Retrieve all records with an attached JSON.

Use cases we intend to support soon:

1. Find a record by a JSON field value (eg. return all orders with field packing.packingStatus equal to "PENDING")

At the moment, this functionality stands a bit separate from the rest of Erply APIs. However, where needed, we intend to provide a better integration between the "extended" data and "standard" data, such as allowing lookup by a JSON field in the "standard" API calls, or allowing to use the JSON data on Actual Reports customized printouts.

To request a field to be added to the JSON schema, please get in touch with Erply customer support, who will forward the request to backend development team.

Attaching Extra Data to Invoice Rows

This use case deserves a separate walkthrough. Previously, it was not possible to "extend" sales document rows with extra information at all.

First step: Retrieve the "stable IDs" of the sales document rows. Please note that the "regular" IDs of sales document rows change every time the document is edited. For integration purposes, we thus assign special "stable" IDs to these rows. These are returned by not only getSalesDocuments, but also saveSalesDocument.

Sample saveSalesDocument output:

{
    "status": {
        "request": "saveSalesDocument",
        "responseStatus": "ok",
        ...
    },
    "records": [
        {
            "invoiceID": 446,
            "invoiceNo": "100012",
            ...
            "rows": [
                {
                    "rowID": 1351,
                    "stableRowID": 1348, <--- This is the value to use for JSON API
                    "productID": 38,
                    "serviceID": 0,
                    "amount": "1"
                }
            ]
        }
    ]
}

Second step: To attach extra data to that invoice row, make a call to JSON API:

PUT /v1/json_object/inv_rows/1348

("table_name" is "inv_rows".)

Request body:

{
    "json_object": {"MyApp":{"deliveryDate":"2020-08-01"}}
}

For this call to work, the key "MyApp" (and subkey "deliveryDate") must be added to the global schema of sales document rows, by Erply.

Get Started With JSON API

This is a REST API following Erply's new microservice standards. Key points:

1. To find the endpoint specific for your account, use the "getServiceEndpoints" call.
2. Each endpoint provides Swagger documentation. For an example, see the documentation provided by the sandbox endpoint: https://api-json-eu10.erply.com/documentation/index.html
3. Use an Erply client code and API session key to make requests. (Send these as headers "clientCode" and "sessionKey".)