Adaco Web API Release Notes

Overview

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 and would like to be kept abreast of API changes via email, please fill in this form.

Breaking change notification

20th August 2023

As part of its ongoing commitment to the security of its customer’s information, Fourth will be updating its platform to require all connections to use TLS 1.2 or higher from 9 January 2024. Older versions of TLS will be retired.

TLS is the encryption method used to secure communications over HTTPS. This will have no impact on SFTP connections.

23 August 2022 — Launch of Inventory resources!

New ItemInventory and OutletInventory resources have launched for Adaco that enable you to manage stock levels across Adaco outlets using near real-time inventory data.

These resources are designed for busy days at event spaces, resorts, and other large restaurant and hotel businesses. By integrating relevant third-party systems with this API, businesses can track key items and active outlets, enabling them to rapidly requisition and post items.

ItemInventory

Get stock levels by outlet for an item

GET request available from the 23rd August:

GET <ROOT>/{customerName}Service/WebApi/ItemInventory/{propertyNumber}/{itemNumber}

This endpoint gets the stock levels in each outlet for the specified item. Benefits include:

  • Keeping track as to whether a specific item is low in stock across some or all outlets.
  • Checking the stock levels in outlets marked as "inventory outlets", which are normally the store rooms from which other outlets can requisition items.

OutletInventory

Get inventory levels for an outlet

GET request available from the 23rd August:

GET <ROOT>/{customerName}Service/WebApi/OutletInventory/{propertyNumber}/{outletNumber}

This endpoint gets near real-time inventory levels for an outlet. Benefits include:

  • Validating the opening and period-end stock to reconcile against physical stock
  • Monitoring the use of products within recipes to assess the popularity of products during the period

Create an inventory adjustment

POST request available from the 27th September:

POST <ROOT>/{customerName}Service/WebApi/OutletInventory/{propertyNumber}

This endpoint creates an inventory adjustment. Benefits include:

  • Ensuring that stock movements not recorded in Adaco on busy days are easily updated via an integrated third-party system
  • Flexibility to either send in the exact value of the stock on-hand, or an adjustment by addition/subtraction

Integrating

For information on integrating with these resources, please visit the:

6 June 2022 — Requisitions: new POST method lets you create requisitions

A new POST method for the requisitions resource means that you can now create requisitions from your own system. This enables venues to manage requisitions via third-party applications, such as a POS device, mobile app, or other display.

The URL for these requests is:

  • POST <ROOT>/{customerName}Service/Adaco/WebApi/Requisitions/{propertyNumber}

The request body can include your own reference RequistionReference to allow you to track your requests.

The following example includes this, as well as all mandatory fields for the request:

[
  {
    "RequisitionReference": "A1B2C3",
    "FromOutlet": 123,
    "ToOutlet": 321,
    "NeedByDate": "2022-07-05",
    "RequisitionItems": [
      {
        "ItemNumber": 456,
        "ProductDetailNumber": 567,
        "ItemType": "P",
        "RequestedQuantity": 6
      }
    ]
  }
]

Successful requests receive the following response from Fourth:

[
   {
      "RequisitionNumber": 1009,
      "RequisitionReference": " A1B2C3",
      "Status": "Created",
      "Errors":  [],
      "UnMatchedItems":  [],
      "UnMatchedAccounts":  []
    }
]

For further information about POST Requisitions requests, please see the:

25 October 2021 — Launch of Requisitions resource!

The Adaco Requisitions resource has launched within the Adaco Web API! This resource enables partners to retrieve information about the requisition requests occurring for Adaco outlets, as well as the historic requests. Requisition items are typically either products or menu items (recipes). The response includes requisitions that were both issued and received by the specified property.

Details for integrating with the resource are available here:

Making requisition requests

The resource supports GET requests only. The URL for requests is:

<ROOT>/{customerName}Service/WebApi/Requisitions/{propertyNumber}

There are four optional parameters which can be included in the URL query string: pageSize and page let you determine how many requisitions you want returned in the response, while status and modifiedsince let you filter the responses.

Authentication

All resources in the Adaco Web API use Basic authentication.

Example response

{
   "Page":1,
   "PageSize":20,
   "Total":178,
   "Items":[
      {
         "RequisitionNumber":123,
         "FromOutlet":{
            "PropertyNumber":1,
            "PropertyName":"Acme Example Hotel Group",
            "OutletNumber":89,
            "OutletName":"Main Stockroom",
            "ExternalId":4673952949
         },
         "ToOutlet":{
            "PropertyNumber":1,
            "PropertyName":"Acme Example Hotel Group",
            "OutletNumber":5,
            "OutletName":"Main restaurant",
            "ExternalId":4267301949
         },
         "Description":"Auto Generated Requisition",
         "Comments":"Urgent",
         "NeedByDate":"2020-10-20T00:00:00.000Z",
         "CreatedDateTime":"2020-10-20T14:29:17.817Z",
         "CreatedByUser":"Jon Snow",
         "LastModifiedDateTime":"2020-10-20T14:29:17.817Z",
         "LastModifiedByUser":"Jon Snow",
         "ReleasedDateTime":"2020-10-20T14:29:17.817Z",
         "PostedDateTime":"2020-10-20T14:29:17.817Z",
         "PostedByUser":"Jon Snow",
         "Status":"posted",
         "ReqisitionItems":[
            {
               "LineNumber":1,
               "ItemNumber":123,
               "ProductDetailNumber":1,
               "ItemDescription":"Coors Lite",
               "IssueSize":"CASE, 24 x 16oz",
               "IssueUnit":"Case",
               "ExternalId":2305983746710110209,
               "ItemType":"P",
               "UnitCost":12.5,
               "RequestedQuantity":10,
               "IssuedQuantity":9,
               "ChargedAmount":112.5,
               "ItemComment":"Chilled please",
               "FromAccount":{
                  "AccountNumber":1,
                  "AccountName":"Beverage Inventory",
                  "AccountXReference":"43300"
               },
               "ToAccount":{
                  "AccountNumber":2,
                  "AccountName":"Beverage Cost of Sales",
                  "AccountXReference":"12300"
               }
            }
         ]
      }
   ]
}

08 April 2021 — Launch of Events resource!

The Adaco Events resource has launched within the Adaco Web API! This resource enables a third-party system, such as a Banqueting Event Order system, to create, update and delete Events within Fourth Adaco. The type of data passed in the API includes the number of covers, the PLUs for menu and retail items, the date and time of the event, and the event location.

This API is designed for large venues that use a POS or Banqueting Event Order system to manage banqueting events across multiple event areas. It improves the venue’s user experience significantly by enabling end users to manage the core event details — time & date, place, and requested menu items — from the partner platform, without needing workarounds such as re-key details into Fourth Adaco or running both platforms simultaneously during a booking.

For more information, see the Events Guide and the Adaco Web API Reference.

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.

For more information, see the exchangeRate endpoints see the Exchange Rate guide and the Adaco Web API reference.

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.

Accounts

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.

Categorization

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.

Vendors 

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:

  1. Look for a matching vendor based on the PrimaryVendorName (if it is submitted)
  2. 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
  3. If not found then try to match the submitted PrimaryVendorXReference value against the vendor’s internal Adaco vendor number
  4. 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 catalogue if they no longer stock the item.

For more information about this endpoint, please see the Product & Catalogue guide and the Adaco Web API reference.

23 Nov 2017 — Catalogue: Addition of paging

These Catalogue endpoints now includes paging.  

  • Get products for a property:
    /Catalogue/{propertyNumber}/Products
  • Get products for a property by segment:
    /Catalogue/{propertyNumber}/Segments/{segmentNumber}/Products
  • Get products for a property by category:
    /Catalogue/{propertyNumber}/Categories/{categoryNumber}/Products

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:

  •  /[PropertyNumber]/Products?search.pageSize=25

Using the search.Page parameter specific pages can be called. For example, this will return products 26 to 50:

  • /[PropertyNumber]/Products?search.pageSize=25&search.Page=2

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.

For more information about this endpoint, please see the Product & Catalogue guide and the Adaco Web API reference.