Last modified: Fri Sep 20 2019 11:21:30 GMT+0000 (Coordinated Universal Time)

How to publish inventory

In this tutorial, you will learn how to publish a very simple offer.

Requirements

Step by step

Let's say your name is Frank, you are living in Washington, DC, you are going out of town for a weekend, and you want to offer your apartment to other travelers.

Preparing the data

In this tutorial, we will tackle two concepts:

Note

You are not limited to Winding Tree Data Model, you can use any API standard you want if you know that your business partners will be able to consume it.

Let's start with the hotel data. It is divided into the following groups:

  • general description
  • inventory
  • prices
  • availability

We are going to construct the data document necessary to register your apartment in the Winding Tree ecosystem and offer it to the world.

General description

This part identifies you as a property owner and contains basic information about both you and the property. In Frank's case, it will look like this:

{
  "description": {
    "name": "Frank's apartment",
    "description": "Beautiful apartment near city center.",
    "contacts": {
      "general": {
        "email": "[email protected]",
        "phone": "+12023581900"
      }
    },
    "address": {
      "road": "E. Street SW, Suite 5R30",
      "houseNumber": "300",
      "city": "Washington",
      "state": "DC",
      "postcode": "20546",
      "countryCode": "US"
    },
    "timezone": "America/New_York",
    "currency": "USD",
    "defaultCancellationAmount": 100
  }
}

The defaultCancellationAmount is necessary for handling situations where the travelers need to cancel their reservation. The value 100 simply means that cancellations are not possible and the money cannot be returned.

Inventory

Inventory describes the property itself, in our case, we are offering the apartment as a whole and we do not want more than 3 people there.

{
  "roomTypes": [
    {
      "id": "franks-apartment",
      "name": "Whole apartment",
      "description": "This is a whole apartment",
      "totalQuantity": 1,
      "occupancy": {
        "max": 3
      }
    }
  ]
}

Prices

Prices are defined as a set of rate plans that can be adjusted and combined to individual needs. In this instance, we are happy with a fixed price of 125 USD per night.

{
  "ratePlans": [
    {
      "id": "franks-price",
      "name": "Fixed price",
      "price": 125,
      "roomTypeIds": [
        "franks-apartment"
      ]
    }
  ]
}

Availability

Of course Frank wants to list his apartment only for the weekend when he is out of town, so we need to set the availability for those dates. The apartment will be free for three nights - from Thursday to Sunday.

{
  "availability": {
    "roomTypes": [
      {
        "roomTypeId": "franks-apartment",
        "date": "2019-07-04",
        "quantity": 1
      },
      {
        "roomTypeId": "franks-apartment",
        "date": "2019-07-05",
        "quantity": 1
      },
      {
        "roomTypeId": "franks-apartment",
        "date": "2019-07-06",
        "quantity": 1
      }
    ]
  }
}

Special fields

In addition to the aforementioned sections, the data can contain a few more special fields.

Since we don't currently offer a way of localizing the textual data, we at least allow you to declare in which defaultLocale the content is. It can be used to for example translate the text automatically on the client side.

Another special field is called booking and contains URI of the Booking API instance.

Adding ORG.ID and uploading the data

The Write API wants all of the data in a single request, so we need to combine everything together. Notice that the inventory is actually part of the description section.

All of the hotel data is also nested under a hotel key. Apart from that, we need to add a legalEntity used as an identification of ORG.ID.

We will store the data into a file called franks-apartment.json.

{
  "legalEntity": {
    "name": "Frank's apartment",
    "contacts": {
      "general": {
        "email": "[email protected]"
      }
    },
    "address": {
      "road": "E. Street SW, Suite 5R30",
      "houseNumber": "300",
      "city": "Washington",
      "state": "DC",
      "postcode": "20546",
      "countryCode": "US"
    }
  },
  "hotel": {
    "description": {
      "name": "Frank's apartment",
      "description": "Beautiful apartment near city center.",
      "website": "https://frank.mysite.com",
      "contacts": {
        "general": {
          "email": "[email protected]",
          "phone": "+12023581900"
        }
      },
      "address": {
        "road": "E. Street SW, Suite 5R30",
        "houseNumber": "300",
        "city": "Washington",
        "state": "DC",
        "postcode": "20546",
        "countryCode": "US"
      },
      "roomTypes": [
        {
          "id": "franks-apartment",
          "name": "Whole apartment",
          "description": "This is a whole apartment",
          "totalQuantity": 1,
          "occupancy": {
            "max": 3
          }
        }
      ],
      "timezone": "America/New_York",
      "currency": "USD",
      "defaultCancellationAmount": 100
    },
    "ratePlans": [
      {
        "id": "franks-price",
        "name": "Fixed price",
        "price": 125,
        "roomTypeIds": [
          "franks-apartment"
        ]
      }
    ],
    "availability": {
      "roomTypes": [
        {
          "roomTypeId": "franks-apartment",
          "date": "2019-07-04",
          "quantity": 1
        },
        {
          "roomTypeId": "franks-apartment",
          "date": "2019-07-05",
          "quantity": 1
        },
        {
          "roomTypeId": "franks-apartment",
          "date": "2019-07-06",
          "quantity": 1
        }
      ]
    },
    "defaultLocale": "en",
    "booking": "https://franks.example-booking-domain.com"
  }
}

In order to list the apartment, we will call the Write API's /hotels endpoint and use the account you configured on the WT Write API.

$ curl -X POST https://madrid-write-api.windingtree.com/hotels \
  -H 'Content-Type: application/json' \
  -H 'X-Access-Key: write-api-account-access-key' \
  -H 'X-Wallet-Password: ethereum-wallet-password' \
  --data @franks-apartment.json

In the response, you will get an Ethereum address of Frank's apartment ORG.ID. That address belongs only to the holder of the used Ethereum wallet and noone else can modify the record stored there.

{"address":"0xA603FF7EA9A1B81FB45EF6AeC92A323a88211f40"}

If Frank would like to improve his trustworthiness, it might be worth adding adding some trust clues to this ORG.ID.

Where to next