Adaco Web API Release Notes
This page explains the changes that have happened to our Adaco Web API since 2017.
These Release Notes are up-to-date at the time of the release. Further improvements or corrections to our API documentation will normally occur in the guides and reference only. These are:
If you have already integrated with Fourth would like to be kept abreast of API changes via email, please fill in this form.
09 July 2018 — Launch of ExchangeRates resource!
Adaco ExchangeRates resource launched within the Adaco Web API!
The ExchangeRates resource enables you to create and update exchange rates in Fourth for a customer account. You can supply rates for both individual properties and every property, simply and within the same request.
04 April 2018 — Authentication method for the Product resource now Basic Authentication
The authentication method for using the Product resource is now Basic Authentication.
Accessing the API using Basic Authentication requires an authentication header submitting as part of http requests to the API. The Authentication Header is comprised of a value which is generated by encoding a combination of the user name and password key into Base64 (the username and password will be provided by the Adaco customer). The username and password should be concatenated with a colon delimiter such as [username]:[password] and then encoded to Base64.
More information on Basic Authentication can be found at: https://en.wikipedia.org/wiki/Basic_access_authentication
04 January 2018 — Product: Amendments to Account, Vendor and Category matching
The account, vendor and category matching has been updated for the Product resource. Please see the following from the guide.
Creating products in multiple properties
Each submission will create products in all of the Adaco properties specified in the AdacoProperties collection and the values specified will be common to all properties. For example, a Primary Vendor specified will be marked as the Primary Vendor for the product in all properties in which it is created.
When matching submitted values against existing data (such as Accounts, Categories, Sub Categories, Segments and Vendors) the matching will be made with existing data from within the parent (or grandparent) property. For example, where a new product is created in one or more properties the matching of an Account would be made against existing accounts within the Central Property (CP) above the properties.
Each product must be assigned to a General Ledger account. The general ledger account can be specified using either the account name, the Adaco Account Number (internal ID for the account) or the Account Cross Reference value which is typically the account number as specified within the accounting system. The submitted account will first be matched against existing data using the submitted AccountName value. This match will be case insensitive and will ignore the word “and” or the “&” character. If this matching fails then a match will be attempted using the submitted AccountXReference value against both the internal Adaco account number and the Account Cross Reference value and where a matching account is found this will be assigned to the new product.
Where a matching account is not found then a new account will be created in the parent property and pushed to all properties in which the new product is being created. Where a new account is being created the new account will be assigned an internal ID which will be derived as the maximum current account number + 1 (next available account number). The name given to the newly created account will be the value of AccountName where a value has been submitted and where no value is submitted then the submitted AccountXReference value will be used as both the Account Cross Reference and the Account Name. Where an AccountName has been submitted but no AccountXReference then the new account will be created without an AccountXReference value.
Each product must be assigned to a Sub Category, a Category and a Segment. The Sub Category submitted will be matched against existing sub categories in the parent or grandparent property. When matching the sub category against existing sub categories the matching will be case insensitive, will ignore special characters and will also ignore the sequence of words. The word “and” and the character “&” will also be ignored. For example, an existing sub category called “Fruit & Vegetables” would match against submitted values “FRUIT AND VEGETABLES”, “Vegetables & Fruit”, “Fruit / Vegetables”, “vegetables – fruit”.
Where the submitted sub category is matched against more than existing one sub category then the submitted category will also be matched against the existing categories. Where one category is found to match then that category / sub category combination will be used. Where more than one category is found to match then the first matching category / sub category will be used. Where no matching categories are found then a new category and sub category will be created.
Where no matching sub category is found then a new sub category will be created. The new sub category will be created in the category matched against the CategoryName value (matching of categories follows the same rules as matching of sub categories). Where there is no matching category then the Category will also be created. The Category will be created in the Segment which matches the submitted SegmentName value. Where there is no matching Segment then the Segment will be created. In all cases the Segment, Category and / or Sub Category will be created in the parent (or grandparent) property and copied to the properties in which the product will be created.
When creating new products a Primary Vendor can be assigned to the product. The Primary Vendor can be specified either by including the vendor’s name in the PrimaryVendorName field or by including either the internal Adaco vendor number or the vendor’s AP X Reference value in the PrimaryVendorXReference field. When assigning a primary vendor the following matching logic will be followed:
- Look for a matching vendor based on the PrimaryVendorName (if it is submitted)
- If not found or there is no PrimaryVendorName submitted then try to match the submitted PrimaryVendorXReference value against the vendor’s AP X Reference value
- If not found then try to match the submitted PrimaryVendorXReference value against the vendor’s internal Adaco vendor number
- If not found and there is a PrimaryVendorName submitted then a new vendor will be created in the parent property and the specified property. The vendor will be created using the PrimaryVendorName submitted and where there is also a PrimaryVendorXReference submitted this will be used to populate the vendor’s AP X Reference value. The vendor will be assigned the culture of the parent property.
23 October 2017 — Launch of Product resource!
A Product resource is now available in the Adaco Web API, enabling you to easily add products in Fourth Adaco. As well, the API can create the underlying reference data on the fly, with new segments, categories, sub-categories, accounts and vendors are all created as necessary.
When using this resource, you send in human-readable categories, such as “fruit and veg”, rather than codes. The API checks that duplications don’t occur and, by only allowing POST requests, ensures that integrated vendors or partners don’t accidentally overwrite or remove products from the customer's catalog if they no longer stock the item.
23 Nov 2017 — Catalogue: Addition of paging
These Catalogue endpoints now includes paging.
- Get products for a property:
- Get products for a property by segment:
- Get products for a property by category:
Paging was created as the three resources potentially return a large payload, so by default they will only return a maximum of 100 products. However, the number of products returned in the response can be managed by specifying a page size using the search.pageSize parameter.
For example, this will return 25 products, per response:
Using the search.Page parameter specific pages can be called. For example, this will return products 26 to 50:
19 May 2017 — Launch of Catalogue resource!
A Catalogue resource is now available in the Adaco Web API, providing access to product details in Adaco.
The data you can retrieve with this API is rich, with all but custom fields (used by POS systems only) returned. This means you can retrieve anything known about the product, such as vendor-specific purchase products and sizes, or the underlying categorizations.