NAV
shell
Generated 2023-06-22

Introduction

Welcome to the igumbi Hotelsoftware REST API.

As a developer you can use our API to access the igumbi API endpoint, where you can get information on the Hotel, Reservations, Persons, Productcategories, Rooms, Products, Invoices in our system. There are methods availablo to integrate a Gastro POS system with the igumbi Hotelsoftware.

All API responses are in JSON format.

The server-side REST API is available at this endoint:

https://api.igumbi.net/api/v1

Some of the Objects can be created and modified via the API.

We have described the language bindings in shell and show you code samples with curl. You can view code examples in the dark area to the right.

Authentication

To authenticate, use this code:

# With shell, you can just pass the correct header with each request

curl "https://api.igumbi.net/api/v1"
  -H "Authorization: auth_token=isYA67869adflhiuzf"

Make sure to replace isYA67869adflhiuzf with your API key.

igumbi uses the auth_token param passed in the header field Authorization to allow access to the API.

igumbi expects for the auth_token to be included in all API requests to the server in a header that looks like the following:

Authorization: auth_token=isYA67869adflhiuzf

User Registration

Create a new igumbi User

The email needs to be unique.

if no parameter ‘username’ is supplied the email will be used as username. The password is set by the user.

An Auth token is returned. This can be used to sign subsequent messages to the api endpoint.


With shell, you can just pass the correct Authorization, 
Accept and Content-Type header with each request.

    curl -X POST 
    -H "Accept: application/json" 
    -H "Content-Type: application/json" 
      -d '{"user":{
              "email": "peg4@othrwise.com",
              "firstname": "Peter", 
              "name": "Gruber", 
              "password": "lahsgdlkhkjalsdhzut675"
              }
            }'
   "https://api.igumbi.net/api/v1/registrations"

   The response with status code 200 is.


{
  "info": "Benutzer peg4@othrwise.com im Demo Hotel angelegt",
  "user": {
    "status": "demo",
    "hotel_id": 8,
    "auth_token": "HsSzxxK9197A0zQ1_9yq",
    "username": "peg4@othrwise.com",
    "email": "peg4@othrwise.com"
  },
  "success": true
}
If the User is already registered

 {
    "errors": [
        [
            "email",
            "ist bereits vergeben"
        ],
        [
            "username",
            "ist bereits vergeben"
        ]
    ],
    "info": "Es gab ein Problem beim Anlegen des Benutzers",
    "errors_full_messages": [
        "Email ist bereits vergeben",
        "Username ist bereits vergeben"
    ],
    "user": {},
    "success": false
}

Hotel

Create a Hotel

Creates a Hotel for the currently logged in user. Typically you do this only once at the beginning when interacting with igumbi.

Usually a Hotel will already be set up and you do not need to perform this step.

If you do decide to add an Hotel, specify at least these fields when setting up a new hotel.:

Expect this to run some 5-10 seconds. There is quite a bit of heavy lifting going on when setting up a new hotel in the igumbi system.

With shell, you can just pass the correct Authorization, Accept and Content-Type header with each request.

    curl -X POST
    -H "Accept: application/json"
    -H "Content-Type: application/json"
    -H "Authorization: auth_token=isYA67869adflhiuzf"
    -d '{"hotel":
         {
           "name": "Hotel Grüber",
           "nrrooms": "8",
           "city": "Wien"
         }
       }'
   "https://api.igumbi.net/api/v1/hotels"

When a Hotel was added successfully this is returned:

{
    "info": "Betrieb Hotel Grüber wurde angelegt",
    "hotel": {
        "status": "eval",
        "nrrooms": 8,
        "name": "Hotel Grüber",
        "city": "Wien",
        "id": 2456
    },
    "success": true
}

We set some defaults for Productcategories and Products when a new Hotel is created.

Show Hotel Details

Usually when you start interacting with igumbi a hotel is allready set up.

The Hotel details, address, form of payments, currency, etc. are shown. Some of the objects describing the hotel are delivered as well:

As a next step you will probably want to get the list of rooms. With shell, you can just pass the correct Authorization, Accept and Content-Type Header with each request.

     curl -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
     "https://api.igumbi.net/api/v1/hotels/2374.json"

This JSON object of the hotel is returned:

{
  "states": [
    {
      "position": 0,
      "name": "igumbi",
      "id": 21428
    },
    {
      "position": 1,
      "name": "nosh",
      "id": 21429
    },
    {
      "position": 2,
      "name": "angefragt",
      "id": 21430
    },
    {
      "position": 3,
      "name": "beantwortet",
      "id": 21431
    },
    {
      "position": 4,
      "name": "kreditkarte",
      "id": 21432
    },
    {
      "position": 5,
      "name": "angezahlt",
      "id": 21433
    },
    {
      "position": 6,
      "name": "eingecheckt",
      "id": 21434
    },
    {
      "position": 7,
      "name": "bezahlt",
      "id": 21435
    },
    {
      "position": 8,
      "name": "ausgecheckt",
      "id": 21436
    }
  ],
  "bookingsources": [
    {
      "default": null,
      "source": "igumbi",
      "direct": true,
      "commission": null,
      "id": 21234
    },
    {
      "default": null,
      "source": "mail",
      "direct": true,
      "commission": null,
      "id": 21232
    },
    {
      "default": null,
      "source": "stammgast",
      "direct": true,
      "commission": null,
      "id": 21235
    },
    {
      "default": null,
      "source": "telefon",
      "direct": true,
      "commission": null,
      "id": 21233
    },
    {
      "default": null,
      "source": "walkin",
      "direct": true,
      "commission": null,
      "id": 21236
    },
    {
      "default": null,
      "source": "Booking",
      "direct": false,
      "commission": null,
      "id": 21237
    },
    {
      "default": null,
      "source": "Feratel",
      "direct": false,
      "commission": null,
      "id": 21239
    },
    {
      "default": null,
      "source": "Hotel.de",
      "direct": false,
      "commission": null,
      "id": 21240
    },
    {
      "default": null,
      "source": "Hrs",
      "direct": false,
      "commission": null,
      "id": 21238
    }
  ],
  "nrrooms": 6,
  "street": null,
  "country": null,
  "zip": null,
  "currency_symbol": "€",
  "tel": null,
  "priority_countries": "DE AT CH",
  "name": "Hotel Grüber",
  "city": "Wien",
  "id": 2378,
  "email": "peg3@othrwise.com",
  "productcategories": [
    {
      "position": 1,
      "standard_occupancy": 1,
      "name": "Einzel",
      "id": 6058
    },
    {
      "position": 2,
      "standard_occupancy": 2,
      "name": "Doppel",
      "id": 6059
    }
  ]
}

List of 15 active hotels of current user ordered by id of hotel

Productcategories

Get a list of Productcategories for a Hotel

Returns an array with a list of productcategories.

A productcategoriey describes a group of rooms with the same attributes. The Productacetgory is the bridge between rooms with products (the individual prices).

Role of the Productcategory

Reservations made by booking portals are usually based on Productcategories and it is the task of the igumbi Hotelsoftware to deal with individual room assignments.

The daily availability is based on number of rooms available for each productcategory. The daily availability and the applicable prices can be queried with the Level Object.

If you are dealing with a holiday rentals with a few apartments, and each apartment is different (size, the bedproductcategories or sleeping places, balconies, baths) you will most likely have a situation where one room is one productcategory.

The field levelmanged indicates whether the Productcategory is a room / apartment that is handled via the level-logic of igumbi or if the products of the categories are “extras” with no manageable capacity (e.g. breakfast, parking spaces, etc.).


With shell, you can just pass the correct Authorization,
Accept and Content-Type header with each request.

    curl
     -H "Authorization: auth_token=isYA67869adflhiuzf"
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     "https://api.igumbi.net/api/v1/productcategories.json"

JSON Output for the list of Productcategories:
You can see the details for Room 1 and 2, both are double productcategories.

[
    {
        "created_at": "2016/06/04 12:15:52 +0200",
        "description": "Einzelzimmer mit Bad/Dusche, WLAN",
        "hotel_id": 2051,
        "id": 5237,
        "levelmanaged": true,
        "max_occupancy": 2,
        "min_occupancy": 1,
        "name": "Karl",
        "picture_file_name": "Einzelzimmer.jpg",
        "picture_updated_at": "2017/04/24 11:51:38 +0200",
        "position": null,
        "roomscount": 1,
        "seller_picture": "https://s3.amazonaws.com/igumbi/productcategories/pictures/5237/original.jpg?1493027498",
        "standard_occupancy": 2,
        "updated_at": "2017/04/26 15:29:40 +0200"
    },
    {
        "created_at": "2016/06/04 12:15:53 +0200",
        "description": "Doppelzimmer Bad/Dusche, WLAN, inkl. Frühstückskörbchen",
        "hotel_id": 2051,
        "id": 5238,
        "levelmanaged": true,
        "max_occupancy": 3,
        "min_occupancy": 1,
        "name": "Fanni",
        "picture_file_name": "Doppelzimmer.jpg",
        "picture_updated_at": "2016/06/04 18:43:15 +0200",
        "position": null,
        "roomscount": 1,
        "seller_picture": "https://s3.amazonaws.com/igumbi/productcategories/pictures/5238/original.jpg?1465058595",
        "standard_occupancy": 2,
        "updated_at": "2017/04/26 15:29:48 +0200"
    }
]

Rooms

Get a list of Rooms for a Hotel

Returns an array with a list of rooms with the attributes roomnumber, position, description, location description.

Details of the productcategory: id, position and name are also listed.

A room describes a rental unit. If it is an apartment it will also be repressented as a room object.

Role of the Productcategory

Reservations made by booking portals are usually based on Productcategories and it is the task of the igumbi Hotelsoftware to deal with individual room assignments.

The daily availability is based on number of rooms available for each productcategory. The daily availability and the applicable prices can be queried with the Level Object.

If you are dealing with a holiday rentals with a few apartments, and each apartment is different (size, the bedrooms or sleeping places, balconies, baths) you will most likely have a situation where one room is one productcategory.


With shell, you can just pass the correct Authorization,
Accept and Content-Type header with each request.

    curl
     -H "Authorization: auth_token=isYA67869adflhiuzf"
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     "https://api.igumbi.net/api/v1/rooms.json"

JSON Output for the list of Rooms:
You can see the details for Room 1 and 2, both are double rooms.


[
  {
    "productcategory_levelmanaged": true,
    "productcategory_position": 2,
    "position": null,
    "description": null,
    "number": 1,
    "productcategory_name": "Doppel",
    "id": 214004,
    "pcname": "Dopp",
    "productcategory_id": 6061,
    "location_desc": null
  },
  {
    "productcategory_levelmanaged": true,
    "productcategory_position": 2,
    "position": null,
    "description": null,
    "number": 2,
    "productcategory_name": "Doppel",
    "id": 214005,
    "pcname": "Dopp",
    "productcategory_id": 6061,
    "location_desc": null
  },...
]

Products

Get a List of Products

Retrieves a List of Products.

The unique product_source_id references a product record if the Product record is created and updated from your side.

To ensure you can only modify the non-room products that you have created: When the levelmanaged field of Productcategory is false or null and the product_source_id is set then the Product can be modified.

    curl
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
    "https://api.igumbi.net/api/v1/products"

  [
    {
        "updated_at": "2017-05-17T14:37:22+02:00",
        "productcategory_id": 6475,
        "price": 38.4,
        "created_at": "2017-05-05T11:25:45+02:00",
        "product_source_id": null,
        "id": 32139,
        "tax": 13,
        "name": "Einzelzimmer",
        "productcategory": {
            "levelmanaged": true,
            "id": 6475,
            "name": "Single"
        }
    },
    {
        "updated_at": "2017-05-17T14:37:09+02:00",
        "productcategory_id": 6475,
        "price": 33.4,
        "created_at": "2017-05-02T14:20:58+02:00",
        "product_source_id": null,
        "id": 32074,
        "tax": 13,
        "name": "Einzelzimmer",
        "productcategory": {
            "levelmanaged": true,
            "id": 6475,
            "name": "Single"
        }
    },
    {
        "updated_at": "2017-05-17T14:36:52+02:00",
        "productcategory_id": 6475,
        "price": 33.4,
        "created_at": "2017-05-05T11:25:21+02:00",
        "product_source_id": null,
        "id": 32138,
        "tax": 13,
        "name": "Einzelzimmer",
        "productcategory": {
            "levelmanaged": true,
            "id": 6475,
            "name": "Single"
        }
    },
    {
        "updated_at": "2017-05-08T13:16:39+02:00",
        "productcategory_id": 0,
        "price": 7,
        "created_at": "2017-05-02T14:20:58+02:00",
        "product_source_id": null,
        "id": 32080,
        "tax": 10,
        "name": "Frühstück"
    },
    {
        "updated_at": "2017-05-03T10:22:53+02:00",
        "productcategory_id": 0,
        "price": 1.6,
        "created_at": "2017-05-02T14:20:58+02:00",
        "product_source_id": null,
        "id": 32081,
        "tax": 0,
        "name": "Ortstaxe"
    }
]

Get a Short List of Products

If the parameter ?product_source_id=true is added to the call, a conciser listing of id, product_source_id and updated_at is returned.

This is usefull for a synchronization logic where your system will want to reconcile Product records with igumbi and you want to check if the record in your system is present and how current the record is in igumbi.

The Product listing is sorted by updated_at descending.

The default limit value is 100. The highest value of limit is 500. If you need more records you need to make multiple calls with adjusted offset values.

With limit and offset parameters

   curl
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
    "https://api.igumbi.net/api/v1/products?limit=3&offset=5

## List of editable Products

The non levelemanaged products can be modified via the API. Add the parameter ?nonlevelmanaged=true to the URL


    curl
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
    "https://api.igumbi.net/api/v1/products?nonlevelmanaged=true

   Concise listing only nonlevelmanaged

    curl
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
    "https://api.igumbi.net/api/v1/products??product_source_id=true&nonlevelmanaged=true

[
    {
        "price": 6.3,
        "updated_at": "2017-09-07T16:43:19+02:00",
        "created_at": "2017-09-07T16:38:08+02:00",
        "id": 43914,
        "product_source_id": "AB4581te",
        "productcategory_id": 7222
    },
    {
        "price": 9.5,
        "updated_at": "2017-09-07T16:42:13+02:00",
        "created_at": "2017-09-07T16:37:14+02:00",
        "id": 43912,
        "product_source_id": "AB4568xf",
        "productcategory_id": 7223
    },
    {
        "price": 7.5,
        "updated_at": "2017-09-07T16:41:33+02:00",
        "created_at": "2017-09-07T16:36:56+02:00",
        "id": 43911,
        "product_source_id": "AB4567ze",
        "productcategory_id": 7223
    }
]

Create a Product Record

The mandatory fields for a Product are hotel_id

Country codes are two letter ISO codes: e.g. AT,DE,GB,US,ES.

The field “product_source_id” is the unique identifier of the product record in your system. It is stored in igumbi as as a string. When you want to retrieve single records later you can use the unique identifier you have previously sent.

    curl -X POST
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
     -d '{
        "product": {
              "name": "Sehr Sehr Junger Winzer",
              "tax":20,
              "price": 12.3,
              "hotel_id": 2535,
              "product_source_id": "AB4585er",
              "productcategory_id":7222,
              "valid_from": "2017-09-01",
              "valid_to": "2019-12-31"
        }
     }'
    "https://api.igumbi.net/api/v1/products"
  #```

This returns a Product object.

```json
{
    "valid_from": "2017-09-06",
    "name": "Junger Winzer",
    "productcategory": {
        "name": "Weißwein",
        "standard_occupancy": 2,
        "position": null,
        "max_occupancy": 2,
        "min_occupancy": 1,
        "updated_at": "2017-09-07T16:39:13+02:00",
        "roomscount": 0,
        "created_at": "2017-09-07T16:35:29+02:00",
        "picture_updated_at": null,
        "hotel_id": 2535,
        "picture_file_name": null,
        "id": 7222,
        "levelmanaged": false
    },
    "valid_to": "2020-09-07",
    "updated_at": "2017-09-07T17:34:51+02:00",
    "price": 7.4,
    "created_at": "2017-09-07T16:38:08+02:00",
    "product_source_id": "AB4581te",
    "id": 43914,
    "tax": 20,
    "productcategory_id": 7222
}

Retrieve a Product

Retrieves a Product by ID or by product_source_id.

    curl
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
    "https://api.igumbi.net/api/v1/products/43914"

 Or retrieve by product_source_id

    curl
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
    "https://api.igumbi.net/api/v1/products/AB4581te"

A newly created Product or a Product retrieval returns a complex JSON object. The Product has relations to these objects:

  {
    "valid_from": "2017-09-06",
    "name": "Sehr Junger Winzer",
    "productcategory": {
        "name": "Weißwein",
        "standard_occupancy": 2,
        "position": null,
        "max_occupancy": 2,
        "min_occupancy": 1,
        "updated_at": "2017-09-07T16:39:13+02:00",
        "roomscount": 0,
        "created_at": "2017-09-07T16:35:29+02:00",
        "picture_updated_at": null,
        "hotel_id": 2535,
        "picture_file_name": null,
        "id": 7222,
        "levelmanaged": false
    },
    "valid_to": "2020-09-07",
    "updated_at": "2017-09-07T17:17:24+02:00",
    "price": 9.3,
    "created_at": "2017-09-07T16:38:08+02:00",
    "product_source_id": "AB4581te",
    "id": 43914,
    "tax": 20,
    "productcategory_id": 7222
}

Update a Product Record

You can only update Product records via the API if the product record was created via your system. To access the record to update you need to use your unique identifier that we have stored in product_source_id.

    curl -X PUT
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
     -d '{
      "product": {
          "name": "Sehr Junger Winzer",
          "price": 9.3,
          "hotel_id": 2535,
          "product_source_id": "AB4581te",
          "productcategory_id":7222
          }
    }'
    "https://api.igumbi.net/api/v1/products/AB4581te"
{
    "valid_from": "2017-09-06",
    "name": "Sehr Junger Winzer",
    "productcategory": {
        "name": "Weißwein",
        "standard_occupancy": 2,
        "position": null,
        "max_occupancy": 2,
        "min_occupancy": 1,
        "updated_at": "2017-09-07T16:39:13+02:00",
        "roomscount": 0,
        "created_at": "2017-09-07T16:35:29+02:00",
        "picture_updated_at": null,
        "hotel_id": 2535,
        "picture_file_name": null,
        "id": 7222,
        "levelmanaged": false
    },
    "valid_to": "2020-09-07",
    "updated_at": "2017-09-07T17:37:20+02:00",
    "price": 6.1,
    "created_at": "2017-09-07T16:38:08+02:00",
    "product_source_id": "AB4581te",
    "id": 43914,
    "tax": 20,
    "productcategory_id": 7222
}

Persons

Get a List of Persons

Retrieves a list of Persons. We store the person and company address, telefone number, email data associated with one or more reservations. the person record is associated with:

The unique person_source_id references a person record if the Person record is created and you want to store a key unique to retrieve that person.

    curl
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
    "https://api.igumbi.net/api/v1/persons"

  [
    {
        "lastname": "Gruber",
        "zip": "1090",
        "person_source_id": "Abe4569ZUert",
        "dob": "1979-10-04",
        "firstname": "Peter",
        "telephone": "+43 1 675 65 678 121",
        "street": "Berggasse 5",
        "city": "Wien",
        "gender": "m",
        "formal": null,
        "created_at": "2017-09-05T08:59:16+02:00",
        "hotel_id": 2535,
        "language": "DE",
        "company": "Gruber GmbH",
        "country": "AT",
        "updated_at": "2017-09-05T08:59:16+02:00",
        "id": 364866,
        "salutation": "Herr",
        "company2": null,
        "uid": "ATU1236789",
        "email": "peter.gruber@gmail.com"
    },
    {
        "lastname": "Buteter",
        "zip": "2851",
        "person_source_id": null,
        "dob": "1974-12-01",
        "firstname": "Petra",
        "telephone": "",
        "street": "Linzergasse 4",
        "city": "Salzburg",
        "gender": "w",
        "formal": null,
        "created_at": "2017-09-01T08:37:58+02:00",
        "hotel_id": 2535,
        "language": "DE",
        "company": "",
        "country": "AT",
        "updated_at": "2017-09-04T11:22:59+02:00",
        "id": 364005,
        "salutation": "Frau",
        "company2": null,
        "uid": null,
        "email": ""
    }
]

Get a Short List of Persons for synching

If the parameter ?person_source_id=true is added to the call, a conciser listing of id, person_source_id and updated_at is returned.

This is usefull for a synchronization logic where your system will want to reconcile Person records with igumbi and you want to check if the record in your system is present and how current the record is in igumbi.

The Person listing is sorted by updated_at descending.

The highest value of limit is 100. If you need more records you need to make multiple calls with adjusted offset values.

    curl
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
    "https://api.igumbi.net/api/v1/persons?person_source_id=true"

 With limit and offset parameters

    curl
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
    "https://api.igumbi.net/api/v1/persons?person_source_id=true&limit=3&offset=5
[
    {
        "person_source_id": "Ab2786779",
        "created_at": "2017-08-25T10:22:50+02:00",
        "updated_at": "2017-08-25T10:24:06+02:00",
        "id": 362163
    },
    {
        "person_source_id": "Ze345ssx",
        "created_at": "2017-08-25T10:18:43+02:00",
        "updated_at": "2017-08-25T10:21:33+02:00",
        "id": 362161
    },
    {
        "person_source_id": null,
        "created_at": "2017-08-25T09:02:35+02:00",
        "updated_at": "2017-08-25T09:05:08+02:00",
        "id": 362144
    }
]

Create a Person Record

The mandatory fields for a Person are hotel_id and lastname or company

Country codes are two letter ISO codes: e.g. AT,DE,GB,US,ES.

Language (“DE”, “EN”, “ES”, …) and gender (“m” or “w”) are important fields for e-mail sending.

The field “person_source_id” is the unique identifier of the person record in your system. It is stored in igumbi as as a string. When you want to retrieve single records later you can use the unique identifier you have previously sent.

    curl -X POST
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
#      -d '{
        "person": {
          "salutation": "Herr",
          "firstname": "Peter",
          "lastname": "Gruber",
          "company": "Gruber GmbH",
          "uid": "ATU1236789",
          "hotel_id": 2378,
          "email": "peter.gruber@gmail.com",
          "telephone": "+43 1 675 65 678 121",
          "street": "Berggasse 5",
          "zip": "1090",
          "city": "Wien",
          "country": "AT",
          "language": "DE",
          "gender": "m",
          "dob": "1979-10-04",
          "note": "Stammgast vom Vorbesitzer".
          "person_source_id": "Abe4569ZUert"
        }
     }'
    "https://api.igumbi.net/api/v1/persons"

This returns a Person object. See details below in the Section “Retrieve a Person”.

Retrieve a Person

Retrieves a Person by ID or by person_source_id.

    curl
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
    "https://api.igumbi.net/api/v1/persons/362775.json"

A newly created Person or a Person retrieval returns a complex JSON object. The Person has relations to these objects:

  {
    "lastname": "Berger",
    "zip": "6200",
    "person_source_id": null,
    "invoices": [
        {
            "lineitems": [
                {
                    "product_id": 32425,
                    "invoice_id": 183099,
                    "product_attributes": {
                        "productcategory_name": "Doppel",
                        "price": 65.8,
                        "productcategory_id": 6476,
                        "name": "Doppelzimmer",
                        "tax": 13,
                        "id": 32425
                    },
                    "taxrate": 13,
                    "nights": 1,
                    "quantity": 1,
                    "price": 64,
                    "reservation_id": 364948,
                    "unitprice": 64,
                    "updated_at": "2017-08-25T10:23:42+02:00",
                    "netto": 56.64,
                    "tax": 7.36,
                    "billed": 1,
                    "id": 633943
                },
                {
                    "product_id": 32081,
                    "invoice_id": 183099,
                    "product_attributes": {
                        "productcategory_name": null,
                        "price": 1.6,
                        "productcategory_id": 0,
                        "name": "Ortstaxe",
                        "tax": 0,
                        "id": 32081
                    },
                    "taxrate": 0,
                    "nights": 1,
                    "quantity": 2,
                    "price": 3.2,
                    "reservation_id": 364948,
                    "unitprice": 1.6,
                    "updated_at": "2017-08-25T10:23:42+02:00",
                    "netto": 3.2,
                    "tax": 0,
                    "billed": 1,
                    "id": 633944
                },
                {
                    "product_id": 32080,
                    "invoice_id": 183099,
                    "product_attributes": {
                        "productcategory_name": null,
                        "price": 7,
                        "productcategory_id": 0,
                        "name": "Frühstück",
                        "tax": 10,
                        "id": 32080
                    },
                    "taxrate": 10,
                    "nights": 1,
                    "quantity": 2,
                    "price": 14,
                    "reservation_id": 364948,
                    "unitprice": 7,
                    "updated_at": "2017-08-25T10:23:43+02:00",
                    "netto": 12.73,
                    "tax": 1.27,
                    "billed": 1,
                    "id": 633945
                }
            ],
            "orig_invoice_id": null,
            "number": 184,
            "date": "2017-08-25",
            "created_at": "2017-08-25T10:23:42+02:00",
            "hotel_id": 2535,
            "open_amount": 0,
            "updated_at": "2017-08-25T10:24:05+02:00",
            "id": 183099,
            "person_id": 362163
        }
    ],
    "dob": "1971-09-19",
    "city": "Salzburg",
    "street": "Linzer straße 10",
    "telephone": "",
    "firstname": "Thomas",
    "created_at": "2017-08-25T10:22:50+02:00",
    "formal": null,
    "gender": "m",
    "language": "DE",
    "hotel_id": 2535,
    "updated_at": "2017-08-25T10:24:06+02:00",
    "country": "DE",
    "company": "",
    "reservations": [
        {
            "arrival_date": "2017-08-24",
            "persons": 2,
            "departure_date": "2017-08-25",
            "created_at": "2017-08-25T10:22:50+02:00",
            "nrrooms": 1,
            "updated_at": "2017-08-25T10:24:06+02:00",
            "id": 364948
        }
    ],
    "email": "",
    "uid": null,
    "company2": null,
    "salutation": "Herr",
    "id": 362163
}

Update a Person Record

You can only update Person records via the API if the person record was created via your system. To access the record to update you need to use your unique identifier that we have stored in person_source_id.

#@person.message(“Modified”,current_user)

Reservations

Get a List of Reservations

Retrieves a list of reservations starting with departure date as of last weeks Sunday. The list contains only the most neccessary details and key information so that is is possible to get a full list of reservations of one hotel in one go without pagination.

Sections and table_x and table_y are fields used to position the reservation on a reservation plan. It is used in the igumbi iPhone app.

invoiceids and gbsheetids are indicators whether invoices have been issued or the guest has been registered. Only the person name is shown.

The field “arr_dep_string” pre renders the arrival and departure date string representation.

The ID of the person_id references a person record.

    curl
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
    "https://api.igumbi.net/api/v1/reservations"

[
  {
    "status": "angefragt",
    "updated_at": "2017/01/23 16:47:31 +0100",
    "sections": [
      "201745",
      "201746"
    ],
    "table_x": 292,
    "nrrooms": 2,
    "departure_date": "2017/11/17",
    "gbsheetids": [],
    "person_id": 301727,
    "created_at": "2017/01/23 16:43:21 +0100",
    "roomnumbers": "3 4",
    "invoiceids": [],
    "table_y": [
      2,
      3
    ],
    "person_name": "Steiner ",
    "nights": 7,
    "state_pos": 2,
    "total": 42,
    "id": 298105,
    "arrival_date": "2017/11/10",
    "arr_dep_string": "10.11-17.11.2017",
    "state_id": 21452,
    "persons": 4,
    "hotel_id": 2378
  },
  {
    "status": "angefragt",
    "updated_at": "2017/01/23 16:47:48 +0100",
    "sections": [
      "201748"
    ],
    "table_x": 310,
    "nrrooms": 1,
    "departure_date": "2017/11/30",
    "gbsheetids": [],
    "person_id": 901726,
    "created_at": "2017/01/23 16:19:38 +0100",
    "roomnumbers": "5",
    "invoiceids": [],
    "table_y": [
      4
    ],
    "person_name": "Huber ",
    "nights": 2,
    "state_pos": 2,
    "total": 6,
    "id": 298104,
    "arrival_date": "2017/11/28",
    "arr_dep_string": "28.11-30.11.2017",
    "state_id": 21452,
    "persons": 2,
    "hotel_id": 2378
  }
]

Create a Reservation

Creates a new Reservation.

The mandatory field are for the reservation: arrival_date, departure_date, hotel_id, nrrooms, persons,status For the person: hotel_id and lastname.

The status needs to be one of the strings defined as a possible status. You will get the possible status values when you retrieve the hotel.

    curl -X POST
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
     -d '{
        "reservation": {
          "arrival_date": "2017/11/28",
          "departure_date": "2017/11/30",
          "hotel_id": 2378,
          "nrrooms": 1,
          "persons": 2,
          "status": "angefragt",
          "person_attributes": {
            "hotel_id": 2378,
            "lastname": "Huber"
          }
        }
      }'
    "https://api.igumbi.net/api/v1/reservations"

This returns a Reservation object. See details below in the Section “Retrieve a Reservation”.

As Hotel Spider/Seekda does not provide the finalcleaning product we create it on channel import Non Ref Reservation handling for Stripe (not for Airbnb & Verwoehnwochenende)

Retrieve a Reservation

Retrieves a Reservation by ID or by Booking Source ID.

    curl
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
    "https://api.igumbi.net/api/v1/reservations/901726.json"

A newly created Reservation or a reservation retrieve returns a complex JSON object. The Reservation object has relations to these objects:

Free rooms and assigning rooms

The field free_rooms shows which rooms are currently available in the time span of the reservation. A room can be chosen by sending an update with the parameter “roomnumbers”. The roomnumbers are separated by spaces.

  {
  "free_rooms": "1 2 3 4 5 6",
  "status": "angefragt",
  "updated_at": "2017/01/23 16:19:39 +0100",
  "status2": "angefragt",
  "rescode": null,
  "doubleoccupancy": null,
  "banktransfer": null,
  "state": {
    "updated_at": "2017/01/23 16:19:18 +0100",
    "errors": [],
    "created_at": "2017/01/23 16:19:18 +0100",
    "position": 2,
    "name": "angefragt",
    "id": 21452,
    "hotel_id": 2378
  },
  "errors": [],
  "sections": [
    "201748"
  ],
  "table_x": 310,
  "res_product_id": null,
  "nrrooms": 1,
  "internal_notes": null,
  "departure_date": "2017/11/30",
  "cancellation_date": null,
  "gbsheetids": [],
  "transferred_at": null,
  "person_id": 901726,
  "invoice_company_id": null,
  "created_at": "2017/01/23 16:19:38 +0100",
  "lineitems": [
    {
      "status": null,
      "updated_at": "2017/01/23 16:19:38 +0100",
      "errors": [],
      "invoice_id": null,
      "dateto": null,
      "billflag": 1,
      "tourops_invoicing_reservation_id": null,
      "price": 6,
      "netto": 6,
      "created_at": "2017/01/23 16:19:38 +0100",
      "description": null,
      "unit": null,
      "taxrate": 0,
      "nights": 2,
      "from_channel": null,
      "datefrom": null,
      "billed": null,
      "reservation_id": 298104,
      "parent_id": null,
      "product_id": 29936,
      "id": 466071,
      "unitprice": 1.5,
      "tax": 0,
      "quantity": 2
    }
  ],
  "roomnumbers": "",
  "parent_reservation_id": null,
  "open_for_tourops_invoicing": null,
  "bookingsource_id": 21259,
  "board": null,
  "deposits": [],
  "invoiceids": [],
  "travelmode": null,
  "comments": null,
  "channel_comments": null,
  "agb_confirmed": null,
  "person": {
    "website": null,
    "updated_at": "2017/01/23 16:19:39 +0100",
    "nologo": null,
    "initial_token": "2c82966c2a5394457dfe1b3739701cf0",
    "errors": [],
    "occupation": null,
    "uid": null,
    "street": null,
    "language": null,
    "created_at": "2017/01/23 16:19:38 +0100",
    "country": null,
    "company": null,
    "zip": null,
    "note": null,
    "abuid": null,
    "reservations_count": 1,
    "notes": null,
    "traveldocument": null,
    "telephone": null,
    "mailchimp_id": null,
    "gbpermission_updated_at": null,
    "dupe": false,
    "salutation": null,
    "mailchimp": null,
    "lastname": "Huber",
    "lang": null,
    "gender": null,
    "dob": null,
    "city": null,
    "netbilling": null,
    "formal": null,
    "firstname": null,
    "dont_email": null,
    "id": 901726,
    "nonameoninvoice": null,
    "mailchimp_info_changed": null,
    "gbpermission": null,
    "email": null,
    "hotel_id": 2378,
    "company2": null
  },
  "source": "mail",
  "table_y": [],
  "person_name": "Huber ",
  "payment_id": null,
  "deposit": null,
  "children5": 0,
  "children4": 0,
  "children3": 0,
  "children2": 0,
  "children1": 0,
  "total": 6,
  "roomcategory": "DBL",
  "id": 298104,
  "housekeeping_notes": null,
  "dayrate": null,
  "bookingsource": {
    "updated_at": "2017/01/23 16:19:09 +0100",
    "default": true,
    "errors": [],
    "source": "mail",
    "direct": true,
    "created_at": "2017/01/23 16:19:09 +0100",
    "commission": null,
    "active": true,
    "id": 21259,
    "hotel_id": 2378
  },
  "open": 6,
  "groupname": null,
  "channel_modified_at": null,
  "arrival_time": null,
  "arrival_date": "2017/11/28",
  "state_id": 21452,
  "persons": 2,
  "motivation": null,
  "hotel_id": 2378,
  "departure_time": null,
  "comission": null,
  "cm_rescode": null
}

Invoices

Invoices have a number, unique to each hotel. The number is incremented by one for each new invoice.

There is a total and an open amount. The total is the sum of all the lineitems on the invoice. The open amount is the total minus the amount that has already been paid.

If there is a reference to orig_invoice_id we are dealing with a creditnote / cancellation. (In German: Gutschrift/ Stornierung )

Get a List of Invoices

Retrieves a list of Invoices ordered by number descending.

    curl
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
    "https://api.igumbi.net/api/v1/invoices"
  [
    {
        "orig_invoice_id": 184649,
        "total": -150,
        "number": 230,
        "date": "2017-09-04",
        "created_at": "2017-09-04T11:18:37+02:00",
        "hotel_id": 2535,
        "updated_at": "2017-09-04T11:18:38+02:00",
        "open_amount": -150,
        "id": 185244,
        "person_id": 363447
    },
    {
        "orig_invoice_id": 184891,
        "total": -249,
        "number": 229,
        "date": "2017-09-04",
        "created_at": "2017-09-04T11:16:02+02:00",
        "hotel_id": 2535,
        "updated_at": "2017-09-04T11:16:02+02:00",
        "open_amount": -249,
        "id": 185243,
        "person_id": 364375
    },
    {
        "orig_invoice_id": null,
        "total": 150,
        "number": 228,
        "date": "2017-09-04",
        "created_at": "2017-09-04T11:10:09+02:00",
        "hotel_id": 2535,
        "updated_at": "2017-09-04T11:14:48+02:00",
        "open_amount": 0,
        "id": 185240,
        "person_id": 364824
    },
    {
        "orig_invoice_id": null,
        "total": 150,
        "number": 227,
        "date": "2017-09-04",
        "created_at": "2017-09-04T11:02:57+02:00",
        "hotel_id": 2535,
        "updated_at": "2017-09-04T11:03:32+02:00",
        "open_amount": 0,
        "id": 185238,
        "person_id": 364819
    },
    {
        "orig_invoice_id": null,
        "total": 150,
        "number": 226,
        "date": "2017-09-04",
        "created_at": "2017-09-04T10:45:49+02:00",
        "hotel_id": 2535,
        "updated_at": "2017-09-04T10:46:32+02:00",
        "open_amount": 0,
        "id": 185234,
        "person_id": 364805
    }
]

Shorter Listing & Pagination

If the parameter ?limit=10 and offset=80 is added to the api call, only the requested numbers of records are returned.

The highest value of limit is 100. If you need more records you need to make multiple calls with adjusted offset values.

    curl
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
    "https://api.igumbi.net/api/v1/invoices?limit=2&offset=80
[
    {
        "orig_invoice_id": null,
        "total": 45,
        "number": 150,
        "date": "2017-08-17",
        "created_at": "2017-08-17T09:53:04+02:00",
        "hotel_id": 2535,
        "updated_at": "2017-08-17T09:53:05+02:00",
        "open_amount": 45,
        "id": 181233,
        "person_id": 359893
    },
    {
        "orig_invoice_id": null,
        "total": 173,
        "number": 149,
        "date": "2017-08-17",
        "created_at": "2017-08-17T09:47:01+02:00",
        "hotel_id": 2535,
        "updated_at": "2017-08-17T09:47:02+02:00",
        "open_amount": 173,
        "id": 181231,
        "person_id": 359886
    }
]

Retrieve an Invoice

Retrieves a Invoice by ID

    curl
     -H "Accept: application/json"
     -H "Content-Type: application/json"
     -H "Authorization: auth_token=isYA67869adflhiuzf"
    "https://api.igumbi.net/api/v1/Invoices/362775.json"

A newly created Person or a Person retrieval returns a complex JSON object. The Person has relations to these objects:

  {
    "lineitems": [
        {
            "product_id": 32426,
            "invoice_id": 185244,
            "product_attributes": {
                "productcategory_name": "Doppel",
                "price": 57.8,
                "productcategory_id": 6476,
                "name": "Doppelzimmer",
                "tax": 13,
                "id": 32426
            },
            "taxrate": 13,
            "nights": 2,
            "quantity": 1,
            "price": -115.6,
            "reservation_id": 366295,
            "unitprice": -57.8,
            "updated_at": "2017-09-04T11:18:37+02:00",
            "netto": -102.3,
            "tax": -13.3,
            "billed": 1,
            "id": 640710
        },
        {
            "product_id": 32080,
            "invoice_id": 185244,
            "product_attributes": {
                "productcategory_name": null,
                "price": 7,
                "productcategory_id": 0,
                "name": "Frühstück",
                "tax": 10,
                "id": 32080
            },
            "taxrate": 10,
            "nights": 2,
            "quantity": 2,
            "price": -28,
            "reservation_id": 366295,
            "unitprice": -7,
            "updated_at": "2017-09-04T11:18:37+02:00",
            "netto": -25.45,
            "tax": -2.55,
            "billed": 1,
            "id": 640711
        },
        {
            "product_id": 32081,
            "invoice_id": 185244,
            "product_attributes": {
                "productcategory_name": null,
                "price": 1.6,
                "productcategory_id": 0,
                "name": "Ortstaxe",
                "tax": 0,
                "id": 32081
            },
            "taxrate": 0,
            "nights": 2,
            "quantity": 2,
            "price": -6.4,
            "reservation_id": 366295,
            "unitprice": -1.6,
            "updated_at": "2017-09-04T11:18:37+02:00",
            "netto": -6.4,
            "tax": 0,
            "billed": 1,
            "id": 640712
        }
    ],
    "orig_invoice_id": 184649,
    "total": -150,
    "number": 230,
    "date": "2017-09-04",
    "created_at": "2017-09-04T11:18:37+02:00",
    "hotel_id": 2535,
    "updated_at": "2017-09-04T11:18:38+02:00",
    "open_amount": -150,
    "person_id": 363447,
    "id": 185244
}

POS System Integration

To integrate a POS system with the igumbi Hotelsoftware API, to enable writing the consumation in a hotel restaurant, cafe or bar to the guestroom.

The following steps are common in building such an integration:

During the stay and when there are consumations

At checkout & payment time:

The API calls described here are tuned so that they can be used efficiently when integrating a POS system.

Get Reservation and Guestcard List of Guests in House

GET /api/v1/pos/reservations.json

This happens at the time when the table should pay and the guests want to charge the consumation to their room.

This retrieves a list of current Reservations in house and and it shows the Guestcards assigned to the reservations and room assignments.

This list is used to display the possible rooms that guests in the house are assigned to with their guestcards issued at checkin.

The lineitems from the POS system are afterwareds sent to the Reservation “id” with the PUT method.

    curl 
     --request GET \
     --url 'https://api.igumbi.net/api/v1/pos/reservations.json?api_key=isYA67869adflhiuzf'
[
  {
    "id": 942234,
    "guestcard_number": "1010204",
    "person_name": "Greiner Gustav",
    "roomnumber": 113,
    "arrival_date": "2023-06-05",
    "departure_date": "2023-06-10"
  },
  {
    "id": 942232,
    "guestcard_number": "00101014",
    "person_name": "Siegmund Susanne",
    "roomnumber": 110,
    "arrival_date": "2023-06-03",
    "departure_date": "2023-06-11"
  },
  {
    "id": 942231,
    "guestcard_number": "00101015",
    "person_name": "Aigner Anna",
    "roomnumber": 108,
    "arrival_date": "2023-06-02",
    "departure_date": "2023-06-07"
  },
  {
    "id": 942230,
    "guestcard_number": "00101005",
    "person_name": "Precht Peter",
    "roomnumber": 106,
    "arrival_date": "2023-06-01",
    "departure_date": "2023-06-06"
  },
  {
    "id": 942230,
    "guestcard_number": "00101012",
    "person_name": "Precht Peter",
    "roomnumber": 106,
    "arrival_date": "2023-06-01",
    "departure_date": "2023-06-06"
  }
]

Get Reservation Details with Open Lineitems

GET /api/v1/pos/reservations/:id.json

The initial state of a Reservation with the open lineitems will show a total but no open lineitems. The poslog entry will be created and the response will be logged and referenced.

curl 
 --request GET \
 --url 'https://api.igumbi.net/api/v1/pos/reservations/929442.json?api_key=isYA67869adflhiuzf' 

The initial response of the Reservation without open lineitems, if the logis has been invoiced already: There is a field for ‘total’, for the logis lines and a 'total_dl’ for those lineitems marked with the transitory flag.

{
  "openlineitems": [],
  "created_at": "2023-06-06T11:21:01+02:00",
  "total": 565.0,
  "updated_at": "2023-06-06T11:22:34+02:00",
  "arrival_date": "2023-06-06",
  "assignments": [
    {
      "guestcard_number": "00101008",
      "guestcard_name": "Huber Hannah",
      "roomnumber": 114
    }
  ],
  "total_dl": 0.0,
  "poslog_id": 807,
  "id": 942235,
  "res_person_name": "Huber Hannah",
  "departure_date": "2023-06-11"
}

Response after adding lineitems via the PUT method from the POS system: The open lineitems are shown. The content of the last poscharge (the payload sent from the POS system to the API and the resulting lineitems) are shown.

Some of the openlineitems and the lineitems under the lastposcharge will be the same. Refer to the ID of these lineitems.

The total will be updated to reflect the new lineitems.

{
  "openlineitems": [
    {
      "created_at": "2023-06-06T11:25:28+02:00",
      "taxrate": 10.0,
      "billflag": 1,
      "id": 1909355,
      "netto": 12.0,
      "productcategory_id": 0,
      "product_id": 180567,
      "product_name": "Küche",
      "poscharge_id": 39,
      "tax": 1.2,
      "transitory": true,
      "billed": null,
      "pos_name": "Apfelstrudel",
      "nights": null,
      "unitprice": 6.6,
      "price": 13.2,
      "quantity": 2.0
    },
    {
      "created_at": "2023-06-06T11:25:28+02:00",
      "taxrate": 20.0,
      "billflag": 1,
      "id": 1909356,
      "netto": 12.0,
      "productcategory_id": 0,
      "product_id": 192978,
      "product_name": "Kaffee & Tee",
      "poscharge_id": 39,
      "tax": 2.4,
      "transitory": true,
      "billed": null,
      "pos_name": "Kaffee",
      "nights": null,
      "unitprice": 4.8,
      "price": 14.4,
      "quantity": 3.0
    }
  ],
  "created_at": "2023-06-06T11:21:01+02:00",
  "total": 565.0,
  "updated_at": "2023-06-06T11:25:28+02:00",
  "arrival_date": "2023-06-06",
  "lastposcharge": {
    "lineitems": [
      {
        "created_at": "2023-05-04T15:42:07+02:00",
        "taxrate": 20.0,
        "billflag": 1,
        "id": 1884269,
        "netto": 2.75,
        "product_id": 190185,
        "poscharge_id": 39,
        "tax": 0.55,
        "transitory": null,
        "billed": null,
        "pos_name": "Otzi spec.",
        "nights": null,
        "unitprice": 3.3,
        "price": 3.3,
        "quantity": 1.0
      },
      {
        "created_at": "2023-06-06T11:25:28+02:00",
        "taxrate": 10.0,
        "billflag": 1,
        "id": 1909355,
        "netto": 12.0,
        "product_id": 180567,
        "poscharge_id": 39,
        "tax": 1.2,
        "transitory": true,
        "billed": null,
        "pos_name": "Apfelstrudel",
        "nights": null,
        "unitprice": 6.6,
        "price": 13.2,
        "quantity": 2.0
      },
      {
        "created_at": "2023-06-06T11:25:28+02:00",
        "taxrate": 20.0,
        "billflag": 1,
        "id": 1909356,
        "netto": 12.0,
        "product_id": 192978,
        "poscharge_id": 39,
        "tax": 2.4,
        "transitory": true,
        "billed": null,
        "pos_name": "Kaffee",
        "nights": null,
        "unitprice": 4.8,
        "price": 14.4,
        "quantity": 3.0
      }
    ],
    "id": 39,
    "created_at": "2023-06-06T11:25:28+02:00",
    "hotel_id": 5302,
    "updated_at": "2023-06-06T11:25:28+02:00",
    "waiter_name": "Christoph",
    "table_nr": 1.5,
    "gross": 27.6,
    "check_timestamp": 1658150072286,
    "tax": 3.6,
    "waiter_nr": 1,
    "guestcard_id": 30,
    "net": 24.0,
    "check_nr": 23,
    "reservation_id": 942235
  },
  "assignments": [
    {
      "guestcard_number": "00101008",
      "guestcard_name": "Huber Hannah",
      "roomnumber": 114
    }
  ],
  "total_dl": 27.6,
  "poslog_id": 810,
  "id": 942235,
  "res_person_name": "Huber Hannah",
  "departure_date": "2023-06-11"
}

Update Reservation to add Poscharge Items

PUT /api/v1/reservations/:id.json

To add items from the POS System that should be written to the room a PUT request to update the Reservation is used. The Guestcard, that is handed out to the guest, serves as to reference the guste, to the room assignment and the Reservation

The request body must contain a JSON object with the following poscharge_attributes and the lineitems detailing the poscharge items.

The lineitems, that are created in igumbi from the POS system, are marked as transitory. In German this is called “Durchlaufposten”. This is done to facilitate a possible pulling back the lineitems into the POS system.
This is the case when the Payment and the invoice is made through the POS system. In case the invoice and the Payment is done via the igumbi PMS, the transitory flag will removed from the POS supplied lineitems. This is done to ensure the vat on the invoice is not calculated and shown twice: onec on a slip issued by the POS system / invoice and once on the PMS invoice.

The sum of the 'transitory’ lineitems is presented in the field 'total_dl’.
The field 'total’ will only hold the logis items.

curl --request PUT \
  --url 'https://api.igumbi.net/api/v1/pos/reservations/929442.json?api_key=isYA67869adflhiuzf' \
  --header 'Content-Type: application/json' \
  --data '{
  "reservation": {
    "guestcard_number": "00101008",
    "guest_name": "Huber Hannah",
    "poscharge_attributes": {
      "check_nr": 23,
      "check_timestamp": 1658150072286,
      "table_nr": "1.5",
      "waiter_nr": 1,
      "waiter_name": "Christoph",
      "gross": 27.60,
      "tax": 3.60,
      "net": 24.00,
      "lineitems": [
        {
          "plu_nr": 5,
          "pos_name": "Apfelstrudel",
          "pos_category_id": 10,
          "pos_category_name": "Küche",
          "unitprice": 6.60000,
          "quantity": 2,
          "taxrate": 10.0,
          "price": 13.20,
          "netto": 12.00,
          "tax": 1.20
        },
        {
          "plu_nr": 6,
          "pos_name": "Kaffee",
          "pos_category_id": 14,
          "pos_category_name": "Kaffee & Tee",
          "unitprice": 4.80000,
          "quantity": 3,
          "taxrate": 20.0,
          "price": 14.40,
          "netto": 12.00,
          "tax": 2.40
        }
      ]
    }
  }
}' 

Update: Response to the request

Response with the updated openlineitems and the total: The response is the Reservation detailing the newly added poscharge_attributes, the adjusted total and the open lineitems.

JSON Response for the PUT/Update request to add lineitems from the POS system.

{
    "openlineitems": [
        {
            "created_at": "2023-06-06T11:25:28+02:00",
            "taxrate": 10.0,
            "billflag": 1,
            "id": 1909355,
            "netto": 12.0,
            "productcategory_id": 0,
            "product_id": 180567,
            "product_name": "Küche",
            "poscharge_id": 39,
            "tax": 1.2,
            "transitory": true,
            "billed": null,
            "pos_name": "Apfelstrudel",
            "nights": null,
            "unitprice": 6.6,
            "price": 13.2,
            "quantity": 2.0
        },
        {
            "created_at": "2023-06-06T11:25:28+02:00",
            "taxrate": 20.0,
            "billflag": 1,
            "id": 1909356,
            "netto": 12.0,
            "productcategory_id": 0,
            "product_id": 192978,
            "product_name": "Kaffee & Tee",
            "poscharge_id": 39,
            "tax": 2.4,
            "transitory": true,
            "billed": null,
            "pos_name": "Kaffee",
            "nights": null,
            "unitprice": 4.8,
            "price": 14.4,
            "quantity": 3.0
        }
    ],
    "created_at": "2023-06-06T11:21:01+02:00",
    "total": 565.0,
    "updated_at": "2023-06-06T11:25:28+02:00",
    "arrival_date": "2023-06-06",
    "lastposcharge": {
        "lineitems": [
            {
                "created_at": "2023-05-04T15:42:07+02:00",
                "taxrate": 20.0,
                "billflag": 1,
                "id": 1884269,
                "netto": 2.75,
                "product_id": 190185,
                "poscharge_id": 39,
                "tax": 0.55,
                "transitory": null,
                "billed": null,
                "pos_name": "Otzi spec.",
                "nights": null,
                "unitprice": 3.3,
                "price": 3.3,
                "quantity": 1.0
            },
            {
                "created_at": "2023-06-06T11:25:28+02:00",
                "taxrate": 10.0,
                "billflag": 1,
                "id": 1909355,
                "netto": 12.0,
                "product_id": 180567,
                "poscharge_id": 39,
                "tax": 1.2,
                "transitory": true,
                "billed": null,
                "pos_name": "Apfelstrudel",
                "nights": null,
                "unitprice": 6.6,
                "price": 13.2,
                "quantity": 2.0
            },
            {
                "created_at": "2023-06-06T11:25:28+02:00",
                "taxrate": 20.0,
                "billflag": 1,
                "id": 1909356,
                "netto": 12.0,
                "product_id": 192978,
                "poscharge_id": 39,
                "tax": 2.4,
                "transitory": true,
                "billed": null,
                "pos_name": "Kaffee",
                "nights": null,
                "unitprice": 4.8,
                "price": 14.4,
                "quantity": 3.0
            }
        ],
        "id": 39,
        "created_at": "2023-06-06T11:25:28+02:00",
        "hotel_id": 5302,
        "updated_at": "2023-06-06T11:25:28+02:00",
        "waiter_name": "Christoph",
        "table_nr": 1.5,
        "gross": 27.6,
        "check_timestamp": 1658150072286,
        "tax": 3.6,
        "waiter_nr": 1,
        "guestcard_id": 30,
        "net": 24.0,
        "check_nr": 23,
        "reservation_id": 942235
    },
    "assignments": [
        {
            "guestcard_number": "00101008",
            "guestcard_name": "Huber Hannah",
            "roomnumber": 114
        }
    ],
    "total_dl": 27.6,
    "poslog_id": 810,
    "id": 942235,
    "res_person_name": "Huber Hannah",
    "departure_date": "2023-06-11"
}

Update: Reduction of items/ cancellation of items

PUT /api/v1/reservations/:id.json

To send a reduction of items/ cancellation of items from the POS system, send a PUT request to /api/v1/reservations/:id with the following parameters:

There is no reference to previously sent items from the POS system in the PUT request.

curl --request PUT \
  --url 'https://api.igumbi.net/api/v1/pos/reservations/929442.json?api_key=isYA67869adflhiuzf' \
  --header 'Content-Type: application/json' \
  --data '{
  "reservation": {
    "guestcard_number": "1010204",
    "guest_name": "Greiner Gustav",
    "poscharge_attributes": {
      "check_nr": 24,
      "check_timestamp": 1658150075286,
      "table_nr": "1.5",
      "waiter_nr": 1,
      "waiter_name": "Christoph",
      "gross": -6.60,
      "tax": -0.60,
      "net": -6.00,
      "lineitems": [
        {
          "plu_nr": 5,
          "pos_name": "Apfelstrudel",
          "pos_category_id": 10,
          "pos_category_name": "Küche",
          "unitprice": 6.60000,
          "quantity": -1,
          "taxrate": 10.0,
          "price": -6.60,
          "netto": -6.00,
          "tax": -0.60
        }
      ]
    }
  }
}' 

Errors that can occur when sending the update

Register a Payment and get an Invoice for the lineitems.

PUT /api/v1/reservations/register/:id.json

After the retrieval of billable and open lineitems the POS system can create a payment and trigger the creation of an invoice from the igumbi PMS. A payment is registered for the invoice with the formofpayment 'POS’.

Note that we switched from poscharge_attributes to lineitems. The lineitems are nested below the reservation.

You should only be referencing existing lineitems by id. We expect the product_id, quantity, unitprice, tax, taxrate, price to be the same value as retrieved before with the show action (GET Reservation details).

 curl --request PUT \
  --url 'https://api.igumbi.net/api/v1/pos/reservations/register/944948.json?api_key=isYA67869adflhiuzf' \
  --header 'Content-Type: application/json' \
  --data '{
    "reservation": {
        "guestcard_number": "00101008",
        "guest_name": "Wagner Walter",
        "payment": {
            "check_nr": 50,
            "check_timestamp": 1658150072286,
            "table_nr": "1.5",
            "waiter_nr": 1,
            "waiter_name": "Christoph",
            "gross": 122.40,
            "tax": 10.73,
            "net": 111.67
        },
        "lineitems": [
                {
                    "id": 1919821,
                    "product_name": "Einzelzimmer",
                    "product_id": 179536,
                    "unitprice": 59.0000,
                    "quantity": 1,
                    "nights":2,
                    "taxrate": 10.0,
                    "price": 118.00,
                    "netto": 107.27,
                    "tax": 10.73
                },
                {
                    "id": 1919822,
                    "product_name": "Ortstaxe",
                    "product_id": 192977,
                    "unitprice": 1.10,
                    "quantity": 2,
                    "nights": 2,
                    "taxrate": 0,
                    "price": 4.40,
                    "netto": 4.40,
                    "tax": 0
                }
            ]
    }
}'

JSON Response to the request to register the payment

Response to the request to register the payment shows the updated Reservation with the newly created Invoice and Payment.

The billed lineitems are now shown nested under the issued_invoice object.

JSON Response to the request to register the payment

{
  "status": "bezahlt",
  "total": 122.4,
  "issued_invoice": {
    "id": 556421,
    "total": 122.4,
    "created_at": "2023-06-19T16:42:40+02:00",
    "open_amount": 0.0,
    "number": 4,
    "payments": [
      {
        "id": 391290,
        "created_at": "2023-06-19T16:42:42+02:00",
        "number": 6,
        "payment_date": "2023-06-19",
        "amount": 122.4,
        "fop": "POS"
      }
    ],
    "lineitems": [
      {
        "billed": 1,
        "unitprice": 59.0,
        "id": 1919821,
        "created_at": "2023-06-19T16:34:17+02:00",
        "netto": 107.27,
        "transitory": null,
        "tax": 10.73,
        "taxrate": 10.0,
        "quantity": 1.0,
        "billflag": 1,
        "pos_name": null,
        "price": 118.0,
        "poscharge_id": null,
        "product_id": 179536,
        "nights": 2
      },
      {
        "billed": 1,
        "unitprice": 1.1,
        "id": 1919822,
        "created_at": "2023-06-19T16:34:17+02:00",
        "netto": 4.4,
        "transitory": null,
        "tax": 0.0,
        "taxrate": 0.0,
        "quantity": 2.0,
        "billflag": 1,
        "pos_name": null,
        "price": 4.4,
        "poscharge_id": null,
        "product_id": 192977,
        "nights": 2
      }
    ],
    "date": "2023/06/19"
  },
  "openlineitems": [],
  "departure_date": "2023-06-21",
  "poslog_id": 1002,
  "created_at": "2023-06-19T16:34:16+02:00",
  "open": 0.0,
  "total_dl": 0.0,
  "assignments": [
    {
      "roomnumber": 102,
      "guestcard_name": "Wagner Walter",
      "guestcard_number": "00101008"
    }
  ],
  "arrival_date": "2023-06-19",
  "updated_at": "2023-06-19T16:42:45+02:00",
  "id": 946935,
  "res_person_name": "Wagner Walter"
}

We verify if lineitems gross/net and tax match up with the payment gross/net/tax values. Finally we update the Reservation state to 'bezahlt’ if the open amount is 0.

Handle the returning JSON in the POS System

Check for the existence of the invoice number and a payment associated with the invoice. The POS system will likely want to reference the invoice number and the payment number on a paper receipt.

We might need to include this if the POS system wants to query unattended

invoice = reservation.invoices.last if invoice.nil?