Upgrading our API to version 2 – November 2020 is time for us to release a major upgrade to our API. We call this “V2” as this is the endpoint path for this. Making private applications has never been easier and with V2. We are also releasing our Zapier integration.
The major change coming with V2 is a move to the industry-standard authentication technology called OAuth2. If you are a programmer and you are not yet familiar with OAuth2, now is the time to get up to speed, because “everyone :-) ” is using it. What OAuth2 means to the end user is a simple and smooth authentication process for external apps using their familiar Manu Online user credentials.
The move to OAuth2 is using our own authentication server. There is no longer a need to register an account with the 3Scale company as was used for V1 of our API. Apps are registered in your Manu Online account directly. So you have one less user name and password to deal with.
Apart from the move to OAuth2 there are some other minor changes in the endpoints. Most importantly the key fields of a document are changing through out to “id”. So for instance “itemid” is replaced by “id”. The obsolete fields are still included for backwards compatibility but will be removed in the next few months, so it is good to check through your code now and get them replaced.
Call to Action!
Upgrade your V1 app over the next few months. Our schedule date for decommissioning v1 is 28.2.2020
Upgrade steps:
- Check that you or your programmers are familiar with the principles of OAuth2. Here is some more technical information about OAuth2
- Check that you have “Private apps (API)” licensed on your account.
- Create a private app in Manu Online (Admin – Integrations – Private apps).
- Set user permissions on one user. (We recommend creating a user just for your app.)
- Contact us with a ticket or contact form to get your app approved. (We are checking that all apps are bona fide only, not for content or functionality.)
- Make the necessary changes to your app:
- Implement OAuth2
- Change the end point path from https://api.manuonline.com/api/ to https://api.manuonline.com/v2/
- Check from our documentation for any obsolete fields, particularly id fields
- Test the endpoints that you use, for instance using Postman.
- Publish the app to your users. You’re done!
Check out the help link in the private apps page in your Manu Online account.
Please let us know how you get on, but note that our support staff are not programmers, so they will not be able to help you with your OAuth2 coding, but there are a lot of resources out there, for instance here. We would also like to know that you have successfully decommissioned your V1 app.
Note that the documentation pages for V1 will be switched off immediately we release V2. If you need to access to these, please contact us.
Sorting
We have implemented sorting on multiple end points. You can now specify a sort order. For instance to get the last sales order use the GET sales order endpoint and set parameters of pageIndex=0&pageSize=1&orderBy=id&orderType=desc. OrderBy can be “id”. For partners and items the sort order can also be “lastmodifieddate” as the id field is not necessarily sequential.
Changes to fields in our Version 2
The following are changes to endpoint data that is implemented in our version 2. When fields are being replaced the API will return both obsolete and current fields for the immediate future. Obsolete fields will be removed at a future date, currently targeted to 28/2/2021.
We are adopting a standard that key fields of a data set (e.g. sales order) are being named “id”.
The id field is implemented on the following endpoints:
- SalesOrder
- PurchaseOrder
- SalesDispatch
- Agreement
- Item
- Partner
- PickList
- SerialNumber
- SalesInvoice
- PurchaseInvoice
Other changes to endpoints released with V2 (Upgrading our API to version 2)
- Implement 400 errors for business logic errors on otherwise successful calls.
- Check that item, partner, sales order, direct sale, dispatch can all be posted and updated using external system name and external system id. Return item or partner id as “id”.
- Post and Get use similar data models. Noted that Get also has expanded sections that post does not have e.g. sales order.
- Make “id” key field. For post when not specified then return the id in result. When it is specified in the post then do an update, only fields that are in the post are updated. (ie. works like PATCH). If id is specified and the record does not exist continue to give an error that partner id is not found.
- Check that partner post will also update when used with ExternalSystemName and ExternalSystemObjectid if the record is found with mappings. i.e. posting with id or (ExternalSystemName and ExternalSystemObjectid) works in the same way.
- ShortName – now an optional field. If it is not specified then a new short name is created in similar way as importing from a bookkeeping system.
- If ShortName is specified checks that it is unique and if not gives an error message “Error – short name is already in use by another partner. Shortname must be unique.”
- ProjectID: Fixed so that it returns the users id
- DfltProject: remove duplicate, please check.
- On post, improved the logic of country code. When data contains 2 digits, looks up use the 3 char. When either 3 or 2 char code is successfully in the post, then the country is marked as in use.
- Removed the obsolete block for properties. It is replaced by the blocks for Materials etc
- Changed field name “ShortName” to “Description” to match screen name
- Descriptions/isDefault. Fixed.
- Change field “NoCost” to “ExcludeFromCostCalculations” to match the screen name
- ExcludeFromNegativeStockCheck fixed to return true or false
- ManufacturerID – removed this system id field
- Sales order endpoint – remove the obsolete duplicate field for SalesorderID. SalesOrderNbr will now become id.
- For post. if order number (or external data is included to find order number) if order exists and is under construction and also version 1, then delete the data in Manu and replace with the post. If not then give an error “The specified order is not in a status that can be modified”
- Get. Added theme name to businessunit block
- Remove dropshipment and backtobackPo from the header. These fields are on the lines. On the UI these are only for user defaults while entering the orders.
- Search endpoint: If parameter is “Expand=Lines” or “Expand=Partners” >> it returns the Partner blocks, but only returns a value in the PartnerId and ShortName fields. Other fields are null
- Change Usersid to id.
Date formatting
- Change date format to include utc time zone marking by adding Z to end of the time characters.
