API Version 1.50.0

14. juuli 2021


Jul 7, 2020

New Features

  1. API call saveSalesDocument now supports idempotency when creating new sales documents.

    API client can add input parameter "temporaryUUID" to the request. Subsequent calls with the same "temporaryUUID" will be rejected with error code 1206. (And should it happen that two calls with the same "temporaryUUID" are sent simultaneously, one of them will be rejected with error code 1204).

    There is no lookup by "temporaryUUID". If unsure whether a document got processed or not, API client should just repeat the call.

    The keys will be retained for 24 hours. After that, Erply discards the key and it can be re-used if needed.

    (Additionally, the attribute source-uuid from Berlin POS — in addition to being saved as usual — will also be treated equivalently to "temporaryUUID".)

    Read more about the feature: https://learn-api.erply.com/reliability/idempotency

  2. API now also guards against multiple simultaneous edits of the same sales document, to avoid race conditions. If two API clients have simultaneously issued a saveSalesDocument call with the same document ID (or one client has issued the same call multiple times), the calls will be processed in sequence.

    In case one of the calls takes an exceedingly long time (at the moment, configured as 5 seconds), the other calls will be dropped and will return error code 1205. This should generally never happen and has been implemented just as a last-resort protection.

    Generally, API clients should avoid editing the same document with multiple calls at the same time: the outcome may be unpredictable. With this change, API will accommodate such situations to a certain extent (by processing the calls in-order), but within reasonable technical limitations.

  3. API now emits an event if a product has been removed from price list.

    For a web shop, removal of a product from a price list may signify that the product's price MAY have changed (but does not necessarily mean that it HAS changed — perhaps the price list is actually expired, associated with a different location, overridden etc.). However, the web shop integration can re-query for this product's current effective price and update it if needed.

    Other changes, such as a product being added to a price list, or a price list price being modified, are already retrievable over API.

    To subscribe to these events and have them sent to your specified endpoint, please use the Web Hook Manager.

    More information is available at: https://manual.erply.com/eng/erply-api/web-hooks

    This particular event looks as follows:

    {
      "id": "5f06fa1ef4884c4eb7890947",
      "hmac": "e1effa2126df813cc7a43a66e49eed2d97532ad425dbd15e318c4a77a0a5a59b",
      "clientCode": "{Account}",
      "table": "pricelist_product_removed",
      "action": "delete",
      "eventCount": 1,
      "items": [
        {
          "rowId": {productID},
          "timestamp": "{EventTimestamp}"
        }
      ]
    }
  4. API calls deleteInventoryWriteOff and deleteInventoryTransfer have been added.

  5. API call getProductsFromSupplierPriceLists has been added.

  6. API call getGiftCardTypes has been added.

  7. Registers (points of sale) now have a type, to optionally indicate which kind of register it is. Field "type" and filter "type" have been added to API call getPointsOfSale.

  8. Field "showInWebShop" has been added to API call getProductGroups.

Improvements

  1. Filter "numberOrCustomer" in API call getSalesDocuments has been improved and no longer fails to return expected matches. A two-step search — finding customers matching the search phrase, then returning documents associated with these customers — has been replaced with one-step search that applies all filter conditions at once.

  2. The existing duplicate prevention in API calls saveSalesDocument and savePayment — which works by comparing input parameters to existing documents, and returns the ID of the previous document if it detects a duplicate — has been updated. Until now, API expected the client to send input parameters "date" and "time", but Berlin POS no longer sends those parameters and therefore detection did not actually work.

    Now API uses the "employeeID" field instead.

    This feature is documented in more detail here: https://learn-api.erply.com/reliability/duplicate-prevention

  3. Fixed: if a sales document is identified as a duplicate, API still accepted the payment sent in the same bulk request, and this created orphaned duplicate payments. If a bulk request contains a savePayment call with documentID = CURRENT_INVOICE_ID and the sales document gets identified as a duplicate, the payment will now be ignored, too.

Fixes

  1. Fixed: filter "shipToID" in API call getSalesReport did not work.