Adaco Exchange Rate Guide

Introduction

This resource enables you to create and update corporate exchange rates in one or more properties within a customer's Adaco instance.

The API receives POST requests for this resource only. If you need Fourth to instead fetch the data, you will need our Fourth Connect team to create an interface between this API and the relevant other data source (or API). Customers can request this by contacting their Fourth customer success manager.

Quick Facts

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 and resource. 

Requests to the ExchangeRates resource is not restricted by property. This enables you to create and update exchange rates 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.

For security, we also recommend that you limit the user group to access to just the “Exchange Rate API”. The setting for this is within the user group's Property > API Access sub-section. The group only needs the Edit access right selected for the Exchange Rate API.

Step 2: create a user account

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

Updating by property

To update an exchange rate for all properties at once, leave the AdacoProperties array blank:

  {
    "AdacoProperties": [ ],
    "FromCurrency": "USD",
    "ToCurrency": "EUR",
    "Rate": 1.5
  }

To update specific properties, include their property number (or property identifier) in the AdacoProperties array. You can find these values in the Fourth UI. 

Duplicates in the request

Your request can include multiple updates for the same currency exchange and properties. The updates are applied in read order. For example, this request sets the exchange rate for USD to EUR for all properties, then for just property 121 updates this rate:

  {
    "AdacoProperties": [ ],
    "FromCurrency": "USD",
    "ToCurrency": "EUR",
    "Rate": 1.5
  },
  {
    "AdacoProperties": [ "121" ],
    "FromCurrency": "USD",
    "ToCurrency": "EUR",
    "Rate": 1.6
   }

Currency conversion

Fourth converts the FromCurrency to the ToCurrency using the supplied Rate.

For example:

"FromCurrency": "EUR", 
"ToCurrency": "USD", 
"Rate": 1.25

Would result in 100 euros being converted to 125 US dollars.

However, once received, the exchange rate you provide is also used to convert currency in the opposite direction. This means that if you provide an EUR to USD conversion, this also automatically creates the USD to EUR rate (in this example, to 0.80).

You cannot have separate exchange rates for the different directions; if you provide both directions, then value of the last received exchange rate is used for to calculate both directions.

Request header

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

GET /{customerName}Service/WebApi/ExchangeRates  HTTP/1.1
Host: instance.example.com
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json

Resources path

The path for ExchangeRates requests is:

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

This is made of:

• The domain name of the Fourth cloud, referenced as <ROOT> above.
• A customer-specific customerName — this is the same name in the URL that is used when the customer logs into Fourth Inventory for Hotels. You must also add "Service" to the name; e.g. "acmeService".

Response to requests

Successful requests

Successfully submitted requests receive an HTTP 200 OK response. The response body contains an object that mirrors your original request's body, but with an additional status value. You must use this value to determine whether each exchange rate was successfully created or updated.

When you submit an array of exchange rates, objects with valid data are updated, while those with invalid data are ignored. See the example below.

Status messages

Unsuccessful requests

Requests that failed submission receive an HTTP 400-599 response, with an error message in the response body.

Example request and response

This example request is accepted by Fourth, however, note that:

• The first object in the array is a valid example.
• The second object has an invalid property (99999).
• The third object specifies the same currency it is trying to replace.
• The fourth object has invalid country codes. 

This means that only the data in the first object is applied to the specified properties.

[
  {
    "AdacoProperties": [ "121", "126" ],
    "FromCurrency": "USD",
    "ToCurrency": "EUR",
    "Rate": 1.5
  },
  {
    "AdacoProperties": [ "121", "99999" ],
    "FromCurrency": "USD",
    "ToCurrency": "GBP",
    "Rate": 1.50
  },
  {
    "AdacoProperties": [ "121", "126" ],
    "FromCurrency": "USD",
    "ToCurrency": "USD",
    "Rate": 1.6
  },
  {
    "AdacoProperties": [ "121", "126" ],
    "FromCurrency": "US$",
    "ToCurrency": "GPP",
    "Rate": 1.6
  }
]

The above request results in the following response.

{
  {
    "FromCurrency": "USD",
    "ToCurrency": "EUR",
    "Rate": 1.5,
    "Status": "Exchange Rate updated",
    "AdacoProperties": [ "121", "126" ]
  },
  {
    "FromCurrency": "USD",
    "ToCurrency": "GBP",
    "Rate": 1.5,
    "Status": "The list of properties contains invalid numbers/identifiers: 99999. The rate was not updated.",
    "AdacoProperties": [ "121", "99999" ]
  },
  {
    "FromCurrency": "USD",
    "ToCurrency": "USD",
    "Rate": 1.6,
    "Status": "\"From Currency\" and \"To Currency\" should be different, exchange rate not updated",
    "AdacoProperties": [ "121", "126" ]
  },
  {
    "FromCurrency": "US$",
    "ToCurrency": "GPP",
    "Rate": 1.6,
    "Status": "Currency code US$ does not exist, exchange rate not updated",
    "AdacoProperties": [ "121", "126" ]
  }