Bulk API calls

It is possible to send API calls in bulk. In other words, you can compose an HTTP request that contains many API calls; API will process all the calls and return all results simultaneously.

Bulk calls must be independent of each other. The bulk feature is suitable for imports (eg. sending many saveProduct calls), but not for combining a saveSalesDocument and a savePayment call — because for storing the payment, you need to know the ID of the invoice that you just created.

In case of bulk API calls, input parameters must be sent not as POST parameters, but as a JSON structure, named “requests”. (You can still retrieve results as JSON or XML as needed, but input must always be JSON.)

[
    {"requestName":"getProducts","recordsOnPage":1,"requestID":1},
    {"requestName":"getSalesDocuments","recordsOnPage":1,"requestID":2}
]

Sending just these three POST parameters should be sufficient:

• sessionKey
• clientCode
• requests

The response structure will look like this. There is a general header (which may contain a general error code that applies to the whole request), and there are sub-structures for each individual request.

{
    "status":
    {
        "requestUnixTime":1369410559,
        "responseStatus":"ok",
        "errorCode":0,
        "generationTime":0.58838200569153
    },
    "requests":
    [
        {
            "status":
            {
                "requestName":"getProducts",
                "requestID":1,
                "requestUnixTime":1369410559,
                "responseStatus":"ok",
                "errorCode":0,
                "generationTime":0.1500449180603,
                "recordsTotal":76,
                "recordsInResponse":1
            },
            "records":
            [
                {...}, ...
            ]
        },
        {
            "status":
            {
                "requestName":"getSalesDocuments",
                "requestID":2,
                "requestUnixTime":1369410559,
                "responseStatus":"ok",
                "errorCode":0,
                "generationTime":0.58054494857788,
                "recordsTotal":166,
                "recordsInResponse":1
            },
            "records":
            [
                {...}, ...
            ]
        }
    ]
}

A bulk call may contain at most 100 requests. If you send more requests, API will return error code 1020 and will not process any of the calls.

If there is an error code in the general header, API will most likely return no results at all. As a general error, API may return:

1. a 100x error (an issue with API, the account, request parameters missing etc.)
2. a 105x error (authentication)

In any other case, API will make an effort to return a response for each of the requests — but it is not guaranteed. The requests are processed in the same order as specified in input. For additional verification, you may assign a requestID to each of the sub-requests; the same value will be returned in response header.

Some usage notes and tips:

1. Processing bulk calls will take considerably longer that processing a single call. Use a longer request timeout.
2. The following input parameters must be sent as top-level parameters and apply to the whole request. You cannot vary these input parameters from one request to another:
   • lang
   • clientCode
   • sessionKey
   • responseType
   • responseMode