Adaco Events API Guide

Introduction

The Events solution in Fourth Adaco is used by our customers for catering planning activities, such as generating recipe sheets and production plans, and submitting purchase and outlet requisitions. This API enables you to create, update and delete events in Adaco.

Partners using this API may also need to integrate with the Adaco Sales Item API to retrieve retail and menu items.

Quick Facts

Integration type HTTP REST with JSON
Authentication Basic Authentication
Availability Fourth Inventory for Hotels customers
Testing Test environment is available on request
More information See the Events API Reference 

Updates

You can find any updates on the Release Notes page for the Adaco Web API.

Get Access

Before integrating, you’ll need to set up a new user account in Fourth with access rights to the API. 

Requests to the Events resource are not restricted by property. This enables you to create and update events for properties in which the user account is not present.

Step 1: create a user group

Create a user group for accessing the API within one of the Fourth properties — we recommend the central purchasing property where there is one.

Screenshot showing the Group Details screen. Under "Edit Permissions", the "API Access" option is ticked.

For security, we also recommend that you limit the user group to access to just the "Events API" and "Sales Item API" as necessary. The setting for this is within the user group's Property > API Access sub-section. The group needs the Create, Update and Delete access right selected for the Events API.

Screenshot showing the "Access Rights" screen. The Event API has 3 options ticked; Create, Edit and Delete.

Step 2: create a user account

In the same property, create a user account. Assign it to the API user group.

Getting locations and menu items

To use this API, you'll need to know the:

  • IDs of the locations (Adaco properties) that you are managing events for. These are the IDs normally agreed between the POS system and Adaco, which are entered as Property Identifier 2 in Adaco.
  • Menu and retail items in Adaco, so that you can include them in the EventItems array.

You can get this data programmatically via the Adaco Sales Item API. This API can also return the RevenueCentre values in Adaco. See the API Guide and Reference for integration details.

Request headers

For all requests, you must provide your authentication details using Basic authentication in the header. Example header:

GET /{customerName}Service/WebApi/Events  HTTP/1.1
Host: instance.example.com
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
Field Description
Authorization Your Events API username and password, separated by a colon, and then base64 encoded. Your ID and password are case-sensitive. 
Content-Type The data format you are using for POST request. Options are: application/json, text/json.

Resources path

The path for Events requests is:

<ROOT>/{customerName}Service/WebApi/Events

The customerName in the URL path is the same as in the URL that our mutual customer uses when logging into Fourth Inventory for Hotels; for example "acme". You also need to add "Service" to the name; for example "acmeService".

Identifiers

The key identifier for an event in all requests is the combination of:

  • location — the Adaco property ID.
  • EventReference — your unique reference for the event.

Example POST or PUT request

Both the POST and PUT Events methods use the same request body. You can send an array of one or more events in a request.

When making a PUT Events request, you must include the full payload for the event. Any optional data that is not included is set to null or zero. This includes all EventItems.

For full details about making POST and PUT Events requests, see the Adaco Web API Reference.

{
             "Location": "45",
             "EventReference": "123",
             "EventName": "Acme Conference",
             "EventType": "Buffet",
             "EventDateTime": "2021-10-20T19:00:00.000Z",
             "TotalForecastCovers": 40,
             "TotalActualCovers": 0,
             "ChargePerCover": 80.00,
             "RevenueCentre": "101",
             "GroupName": "Acme Sales team",
             "Comments": "VIP Customer. Beware of allergen requirements.",
             "EventItems": [
                    {
                          "PLU": "503622",
                          "ForecastCovers": 10,
                          "ActualCovers": 0,
                          "Station": "Hot Mains"
                    },
                    {
                          "PLU": "501671",
                          "ForecastCovers": 15,
                          "ActualCovers": 0,
                          "Station": "Cold Buffet"
                    },
                    {
                          "PLU": "502987",
                          "ForecastCovers": 15,
                          "ActualCovers": 0,
                          "Station": "Desserts"
                    }

             ]
       }
]

Example delete request

To delete an event you only need to send the location and eventReference for the event. You can delete multiple events by sending the events as an array in the request body.

For full details about the DELETE request, see the Adaco Web API Reference.

[
   {
        "Location": "45",
        "EventReference": "123"
   },
   { 
        "Location": "45", 
        "EventReference": "135"
   }
]

Response to requests

The HTTP Status responses provided by Fourth Adaco will be one of:

  • 200 — The request was fully or partially successful. The response body contains more details including a status field and error messages that will confirm the status for the request.
  • 400 — The request was unsuccessful. The response body contains more details including a status field and error messages that will confirm the status for the request.
  • 401 — Unauthorised, with a generic response body.
  • 403 — Forbidden, with a generic response body.

Arrays

If you sent an array of events, then the response will be 200 OK regardless of whether part of the request failed. You will need to use the status and error messages for your requests to check that the request was successful, rather than rely solely on the HTTP status code.

Unmatched items

When an event is created or updated, Adaco checks that each event item's PLU matches an existing retail or menu item in Adaco. If for some reason a matching item is not found, then the PLU is sent back in the UnmatchedItems array.

Adaco creates or updates the event regardless of any unmatched PLUs.

Example response

[
       {
             "Location": "99",
             "EventReference": "1",
             "EventName": "Event 1",
             "Status": "Created",
             "Errors": [
                    {
                    }
             ],
             "UnMatchedItems": [
                    {
                          "123456",
                          "654321"
                    }
             ]
       },
       {
             "Location": "99",
             "EventReference": "2",
             "EventName": "Event 2",
             "Status": "Created",
             "Errors": [
                    {
                    }
             ],
             "UnMatchedItems": [
                    {
                    }
             ]
       },
       {
             "Location": "77",
             "EventReference": "3",
             "EventName": "",
             "Status": "Not created",
             "Errors": [
                    {
                          "The submitted location value could not be matched to an Adaco property",
                          "Event name must be provided"
                    }
             ],
             "UnMatchedItems": [
                    {
                    }
             ]
       }
]

Status options

Method HTTP code Status Description
POST 200 Created The event was successfully created in Adaco.
POST 200 Created with Unmatched Items The event was created but one or more PLUs did not match to existing Adaco items.
POST 200 or 400 Not Created The event was not created due to missing or invalid data. The Errors array will have a description of the error.
PUT 200 Updated The event was successfully updated in Adaco.
PUT

200

Updated with Unmatched Items The event was updated but one or more PLUs did not match to existing Adaco items.
PUT 200 or 400 Not Updated The event was not updated due to missing or invalid data. The Errors array will have a description of the error.
DELETE 200 Deleted The event was deleted.
DELETE 200 or 400 Not Deleted

No matching event was found to delete. This could be due to the:

  • Event being previously deleted.
  • Event having never existed; for example, if the original POST Events request for the event failed.
  • Values in the DELETE request being malformed.

Error messages

The Errors array holds one or more error messages. If you receive an error message, this means that the event has not been created, updated or deleted.

Error message

Description
Location [value] is not assigned to a property

The location value did not match an existing property in Adaco.

You can get location values using the Adaco Sales Item API or by talking to your customer, who can see these values via the Adaco user interface. Location values are not case-sensitive.

Event Reference should not be empty and have a length up to 50 characters. You are missing a value for your EventReference. Adaco cannot create an event without this.
Event [value] already exists

The eventReference sent in your POST request already exists. Reasons for this message include:

  • You tried to update an event using the POST method. You can use PUT for updating events, but not POST.
  • There is an issue with the way you are creating event references, which means that you have duplicated an event reference.
Event [value] not found in [location]

The eventReference sent in the PUT or DELETE request did not match an existing event. Reasons for this message include:

  • You tried to create an event using the PUT method. You can use POST for creating events, but not PUT.
  • There is an issue with the way you are creating event references. For example, if you dynamically create references, and change the format in some way, you may find that you cannot edit existing events.
  • You (or an end user) have previously deleted this event.
Event name must be provided For PUT and POST requests, an EventName is mandatory.
Event date / time must be provided

For PUT and POST requests, an EventDateTime is mandatory. You may receive this mesage if there is no value, or the timestamp format is wrong. The correct format is: yyyy-MM-ddT00:00:00.000Z.

Revenue Centre [value] not mapped to an outlet

The revenue center was either not provided or did not match an existing one in Adaco. If necessary, check the revenue centers in Adaco by either:

  • Contacting your customer to confirm the centers are keyed in correctly
  • Making a GET /Sites request via the Sales Item API

Forecast Covers must be greater than 0.

Each event item must have at a value of 1 or higher for the forecast covers.

If you are updating an event, and the forecast covers are now zero for a menu item, then your PUT event request should exclude the event item from the request. This will remove the item from the event in Adaco.