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
isYA67869adflhiuzfwith 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.:
- Name of the Hotel (name)
- City (city)
- The number of rooms (nrrooms)
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:
- States - the states of Reservations
- Bookingsources
- Productcategories - Roomcategories
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
}
]
}
#render :json=> @hotel.to_json(:only=>[:id,:name,:nrrooms,:zip,:city,:street,:tel,:email,:country,:currency_symbol,:source,:direct,:commission,:default,:statepos,:priority_countries,:position,:standard_occupancy,:number,:productcategory_id,:description], #:method=>[:statepos], #:include=>[:bookingsources,:states,:productcategories, :rooms] #)} 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:
- Product {}
- Productcategory {}
{
"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:
- Reservations
- Invoices
- Payments
- E-Mails
- Reminders
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:
- Person {}
- Invoices []
- Invoice {}
- Lineitems []
- Lineitem {}
- Product {}
- Invoice {}
- Reservations []
- Reservation {}
- Invoices []
{
"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) If Ctrip/ Expedia /Airbnb /Verwöhnwochenende: tranferred_at statt RAPID-NRF oder RAPID-STD
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:
- State
- Sections (the weeks of the reservation plan)
- Person (The associated guest)
- Bookingsource (The bookingsource)
- Lineitems (the Items that will later be billed to the Person)
- Deposits (Payments made at the time of booking)
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.
{
"arrival_date": "2023-11-15",
"comments": null,
"gbsheetids": [],
"table_y": [
0
],
"table_x": 10,
"total": 129,
"hotel_id": 4079,
"departure_date": "2023-11-18",
"housekeeping_notes": "",
"channel_comments": null,
"arr_dep_string": "15.11-18.11.2023",
"person": {
"zip": "",
"company2": null,
"company": "",
"firstname": "Peter",
"country": "",
"id": 575712,
"email": "",
"salutation": "",
"updated_at": "2023-11-10T18:50:49+01:00",
"city": "",
"tel": null,
"lastname": "Gruber",
"title": "",
"created_at": "2019-07-22T11:54:34+02:00",
"formal": null
},
"status": "angefragt",
"lineitems": [{
"poscharge_id": null,
"gastropos_id": null,
"dateto": null,
"chargetype": null,
"datefrom": null,
"tourops_invoicing_reservation_id": null,
"tax": 11.73,
"status": null,
"description": "",
"billflag": 1,
"billed": 1,
"gastropos_recalled": null,
"roomstay_index": null,
"product_id": 96302,
"netto": 117.27,
"id": 1132462,
"pos_name": null,
"parent_id": null,
"delete_li": null,
"updated_at": "2019/07/22 11:57:24 +0200",
"price": 129,
"gastropos_nonepaid_items_id": null,
"channelrateplan_id": null,
"unit": null,
"nights": 1,
"invoice_id": 326390,
"unitprice": 129,
"from_channel": null,
"created_at": "2019/07/22 11:54:34 +0200",
"transitory": null,
"taxrate": 10,
"reservation_id": 581820,
"quantity": 1,
"plu_nr": null
}],
"channel_modified_at": null,
"person_name": null,
"transferred_at": null,
"nrrooms": 1,
"rescode": null,
"roomnumbers": "101",
"persons": 2,
"id": 581820,
"deposits": [{
"hotel_id": 4079,
"payment_id": 197936,
"due_date": "2019/07/29",
"id": 28210,
"updated_at": "2019/07/22 11:55:45 +0200",
"open": 0,
"invoice_id": null,
"created_at": "2019/07/22 11:54:44 +0200",
"reservation_id": 581820,
"currency": "EUR",
"amount": 80
}],
"person_id": 575712,
"updated_at": "2023-11-10T18:50:48+01:00",
"errors": null,
"bookingsource": {
"source": "mail",
"id": 36870,
"direct": true
},
"state_pos": 2,
"nights": 3,
"created_at": "2019-07-22T11:54:34+02:00",
"invoiceids": [
326390
],
"internal_notes": "",
"state": {
"name": "angefragt",
"id": 36905,
"position": 2
},
"sections": [
"202346"
],
"free_rooms": "102 103 104 105"
}
res needs to be in the future (mobene HRS case like res 960019) for auto reassign via channelmanager. rateplan indicator ortstaxe indicator endreinigung inidcator
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:
- Invoice {}
- Lineitems []
- Lineitem {}
- Product {}
- Lineitems []
{
"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
- Get a list of current reservations in house with the Guestcards assigned to the rooms and Reservations
- Get the details of a Reservation with the open Lineitems
- Add Lineitems from the POS system to the Reservation to be charged to the room
At checkout & payment time:
- Issue an Invoice with logis and gastro Lineitems to the guest - there nothing more to do for the POS system at that time.
- The Payment should be handled via the POS System. Get the details of a Reservation with the with open lineitems are retrieved and pulled back into the POS system to create an Invoice and a Payment from the POS system
The API calls described here are tuned so that they can be used efficiently when integrating a POS system.
Get Reservations and Guestcard List of Guests in the 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 request retrieves a list of current Reservations in house and and it shows the Guestcards (Name and Number) 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 “reservation_open” field shows the open amount of the reservation.
curl
--request GET \
--url 'https://api.igumbi.net/api/v1/pos/reservations.json?api_key=isYA67869adflhiuzf'
[
{
"reservation_open": 10.7,
"guestcard_number": "102004",
"id": 1062878,
"departure_date": "2024-05-22",
"arrival_date": "2024-05-17",
"roomnumber": 101,
"person_name": "Steiner Peter"
},
{
"reservation_open": 10.7,
"guestcard_number": "102007",
"id": 1062878,
"departure_date": "2024-05-22",
"arrival_date": "2024-05-17",
"roomnumber": 102,
"person_name": "Steiner Susanne"
},
{
"reservation_open": 4.0,
"guestcard_number": "1001111",
"id": 1062879,
"departure_date": "2024-05-22",
"arrival_date": "2024-05-17",
"roomnumber": 106,
"person_name": "Diehner Dieter"
},
{
"reservation_open": 4.0,
"guestcard_number": "1001114",
"id": 1062879,
"departure_date": "2024-05-22",
"arrival_date": "2024-05-17",
"roomnumber": 107,
"person_name": "Diehner Dieter"
},
{
"reservation_open": 0.0,
"guestcard_number": "1001201",
"id": 1062881,
"departure_date": "2024-05-22",
"arrival_date": "2024-05-17",
"roomnumber": 111,
"person_name": "Greiner Gerhard"
},
{
"reservation_open": 0.0,
"guestcard_number": "1001207",
"id": 1062881,
"departure_date": "2024-05-22",
"arrival_date": "2024-05-17",
"roomnumber": 112,
"person_name": "Greiner Doris"
}
]
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/1062887.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.
{
"updated_at": "2024-05-21T12:17:39+02:00",
"total": 0.0,
"total_dl": 0.0,
"open": 0.0,
"id": 1062887,
"departure_date": "2024-05-26",
"issued_invoice": {},
"poslog_id": 1178,
"res_person_name": "Peters Paul",
"created_at": "2024-05-21T12:17:20+02:00",
"status": "angefragt",
"openlineitems": [],
"arrival_date": "2024-05-21",
"assignments": [
{
"guestcard_number": "10151",
"guestcard_name": "Peters Paul",
"roomnumber": 113
},
{
"guestcard_number": "10157",
"guestcard_name": "Peters Petra",
"roomnumber": 114
}
]
}
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.
The response mirror back the submitted data with the element “lastposcharge” The openlineitems show the aggregated quantities and pricees. Products with the same product_id, price and number of nights are aggregated. The Lineitem IDs is shown in the field “ids”
The “total” of the reservation will hold the logis positions (Charges for the room, localtax, finalcleanin. basically the items that originate from the PMS). The field “total_dl” (Total Durchläufer / lineitems föagged transitory) shows the total of the positions received fro the POS system.
Each request to the API is stored with in the poslog entry, the poslog_id is the reference to the lastposcharge element.
{
"lastposcharge": {
"lineitems": [
{
"poscharge_id": 110,
"taxrate": 10.0,
"billed": null,
"quantity": 1.0,
"price": 6.6,
"id": 2183794,
"pos_name": "Apfelstrudel",
"netto": 6.0,
"nights": null,
"created_at": "2024-05-21T12:21:18+02:00",
"tax": 0.6,
"billflag": 1,
"transitory": true,
"product_id": 180567,
"unitprice": 6.6
},
{
"poscharge_id": 110,
"taxrate": 20.0,
"billed": null,
"quantity": 1.0,
"price": 4.8,
"id": 2183795,
"pos_name": "Kaffee",
"netto": 4.0,
"nights": null,
"created_at": "2024-05-21T12:21:18+02:00",
"tax": 0.8,
"billflag": 1,
"transitory": true,
"product_id": 222165,
"unitprice": 4.8
}
],
"updated_at": "2024-05-21T12:21:18+02:00",
"reservation_id": 1062887,
"net": 25.0,
"id": 110,
"gross": 30.0,
"check_nr": 231,
"waiter_name": "Christoph",
"waiter_nr": 1,
"check_timestamp": 171587424234,
"created_at": "2024-05-21T12:21:18+02:00",
"tax": 5.0,
"guestcard_id": 66,
"table_nr": 1.5,
"hotel_id": 5302
},
"updated_at": "2024-05-21T12:22:16+02:00",
"total": 315.0,
"total_dl": 11.4,
"open": 326.4,
"id": 1062887,
"departure_date": "2024-05-26",
"issued_invoice": {},
"poslog_id": 1181,
"res_person_name": "Peters Paul",
"created_at": "2024-05-21T12:17:20+02:00",
"status": "angefragt",
"openlineitems": [
{
"productcategory_id": 0,
"taxrate": 10.0,
"billed": null,
"quantity": 1.0,
"price": 6.6,
"product_name": "Küche",
"plu_nr": null,
"pos_name": "Apfelstrudel",
"ids": [
2183794
],
"netto": 6.0,
"nights": null,
"tax": 0.6,
"billflag": 1,
"transitory": true,
"unitprice": 6.6,
"product_id": 180567
},
{
"productcategory_id": 0,
"taxrate": 20.0,
"billed": null,
"quantity": 1.0,
"price": 4.8,
"product_name": "Kaffee & Tee",
"plu_nr": null,
"pos_name": "Kaffee",
"ids": [
2183795
],
"netto": 4.0,
"nights": null,
"tax": 0.8,
"billflag": 1,
"transitory": true,
"unitprice": 4.8,
"product_id": 222165
},
{
"productcategory_id": 13604,
"taxrate": 10.0,
"billed": null,
"quantity": 2.0,
"price": 290.0,
"product_name": "Einzelzimmer",
"plu_nr": null,
"pos_name": null,
"ids": [
2183796
],
"netto": 263.64,
"nights": 5,
"tax": 26.36,
"billflag": 1,
"transitory": null,
"unitprice": 29.0,
"product_id": 179536
},
{
"productcategory_id": 0,
"taxrate": 0.0,
"billed": null,
"quantity": 2.0,
"price": 25.0,
"product_name": "Ortstaxe",
"plu_nr": null,
"pos_name": null,
"ids": [
2183797
],
"netto": 25.0,
"nights": 5,
"tax": 0.0,
"billflag": 1,
"transitory": null,
"unitprice": 2.5,
"product_id": 192977
}
],
"arrival_date": "2024-05-21",
"assignments": [
{
"guestcard_number": "10151",
"guestcard_name": "Peters Paul",
"roomnumber": 113
},
{
"guestcard_number": "10157",
"guestcard_name": "Peters Petra",
"roomnumber": 114
}
]
}
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 to the guest, the room assignment and the Reservation id (used in the URL) of the request.
The request body must contain a JSON object with the following poscharge_attributes and the lineitems from the POS detailing the items to add from the POS system.
The lineitems, that are stored in igumbi sent 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 at the time of payment.
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 tax (VAT) on the invoice is not calculated and shown twice: once 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 originating from the igumbi PMS.
curl --request PUT \
--url 'https://api.igumbi.net/api/v1/pos/reservations/1062877.json?api_key=isYA67869adflhiuzf' \
--header 'Content-Type: application/json' \
--data '{
"reservation": {
"guest_name": "Peters Paul",
"guestcard_number": "10151",
"poscharge_attributes": {
"check_nr": 231,
"check_timestamp": 171587424234,
"table_nr": "1.5",
"waiter_nr": 1,
"waiter_name": "Christoph",
"gross": 30.00,
"tax": 5.00,
"net": 25.00,
"lineitems": [
{
"pos_category_id": 10,
"pos_category_name": "Küche",
"pos_name": "Apfelstrudel",
"unitprice": 6.60000,
"price": 6.60,
"quantity": 1,
"netto": 6.00,
"taxrate": 10.0,
"tax": 0.60
},
{
"pos_category_id": 14,
"pos_category_name": "Kaffee & Tee",
"pos_name": "Kaffee",
"unitprice": 4.80000,
"price": 4.80,
"quantity": 1,
"netto": 4.00,
"taxrate": 20.0,
"tax": 0.80
}
]
}
}
}'
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.
{
"lastposcharge": {
"lineitems": [
{
"poscharge_id": 110,
"taxrate": 10.0,
"billed": null,
"quantity": 1.0,
"price": 6.6,
"id": 2183794,
"pos_name": "Apfelstrudel",
"netto": 6.0,
"nights": null,
"created_at": "2024-05-21T12:21:18+02:00",
"tax": 0.6,
"billflag": 1,
"transitory": true,
"product_id": 180567,
"unitprice": 6.6
},
{
"poscharge_id": 110,
"taxrate": 20.0,
"billed": null,
"quantity": 1.0,
"price": 4.8,
"id": 2183795,
"pos_name": "Kaffee",
"netto": 4.0,
"nights": null,
"created_at": "2024-05-21T12:21:18+02:00",
"tax": 0.8,
"billflag": 1,
"transitory": true,
"product_id": 222165,
"unitprice": 4.8
}
],
"updated_at": "2024-05-21T12:21:18+02:00",
"reservation_id": 1062887,
"net": 25.0,
"id": 110,
"gross": 30.0,
"check_nr": 231,
"waiter_name": "Christoph",
"waiter_nr": 1,
"check_timestamp": 171587424234,
"created_at": "2024-05-21T12:21:18+02:00",
"tax": 5.0,
"guestcard_id": 66,
"table_nr": 1.5,
"hotel_id": 5302
},
"updated_at": "2024-05-21T12:21:19+02:00",
"total": 0.0,
"total_dl": 11.4,
"open": 11.4,
"id": 1062887,
"departure_date": "2024-05-26",
"issued_invoice": {},
"poslog_id": 1179,
"res_person_name": "Peters Paul",
"created_at": "2024-05-21T12:17:20+02:00",
"status": "angefragt",
"openlineitems": [
{
"productcategory_id": 0,
"taxrate": 10.0,
"billed": null,
"quantity": 1.0,
"price": 6.6,
"product_name": "Küche",
"plu_nr": null,
"pos_name": "Apfelstrudel",
"ids": [
2183794
],
"netto": 6.0,
"nights": null,
"tax": 0.6,
"billflag": 1,
"transitory": true,
"unitprice": 6.6,
"product_id": 180567
},
{
"productcategory_id": 0,
"taxrate": 20.0,
"billed": null,
"quantity": 1.0,
"price": 4.8,
"product_name": "Kaffee & Tee",
"plu_nr": null,
"pos_name": "Kaffee",
"ids": [
2183795
],
"netto": 4.0,
"nights": null,
"tax": 0.8,
"billflag": 1,
"transitory": true,
"unitprice": 4.8,
"product_id": 222165
}
],
"arrival_date": "2024-05-21",
"assignments": [
{
"guestcard_number": "10151",
"guestcard_name": "Peters Paul",
"roomnumber": 113
},
{
"guestcard_number": "10157",
"guestcard_name": "Peters Petra",
"roomnumber": 114
}
]
}
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": {
"guest_name": "Greiner Gerhard",
"guestcard_number": "1001201",
"poscharge_attributes": {
"check_nr": 240,
"check_timestamp": 1715874273123,
"table_nr": "1.5",
"waiter_nr": 1,
"waiter_name": "Christoph",
"gross": -6.60,
"tax": -0.60,
"net": -6.00,
"lineitems": [
{
"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
- 404 Not Found if the Reservation or the Guestcard is not found, or both are not found
- 422 Unprocessable Entity if the Reservation is found but the Guestcard is not assigned to the Reservation in the URL
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 openlineitems are nested below the reservation.
You should be referencing existing openlineitems by product_id (the id supplied by igumbi), unitprice and supply a value for the quantity to be invoiced and paid in the transaction. We also expect tax, taxrate, netto, price (unitprice * quantity) to be supplied. Send product_name for easier human readability.
igumbi will check if we need to split the lineitems stored in igumbi to process this request. If so all open (billable and billed = false/nil) records with quantity greater 1 will be split into into records with quantity 1.
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": "1001207",
"guest_name": "Greiner Doris",
"payment": {
"check_nr": 250,
"check_timestamp": 171587425234,
"table_nr": "1.5",
"waiter_nr": 1,
"waiter_name": "Christoph",
"gross": 176.4,
"tax": 16.33,
"net": 160.07
},
"lineitems": [
{
"product_name": "Bier",
"product_id": 190185,
"unitprice": 2.70000,
"quantity": 7,
"nights": null,
"taxrate": 20.0,
"price": 18.90,
"netto": 15.75,
"tax": 3.15
},
{
"product_name": "Ortstaxe",
"product_id": 192977,
"unitprice": 2.50,
"quantity": 1,
"nights": 5,
"taxrate": 0,
"price": 12.50,
"netto": 12.5,
"tax": 0
},
{
"product_name": "Einzelzimmer",
"product_id": 179536,
"unitprice": 29.00,
"quantity": 1,
"nights": 5,
"taxrate": 10,
"price": 145.0,
"netto": 131.82,
"tax": 13.18
}
]
}
}'
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
{
"poslog_id": 1131,
"open": 273.0,
"id": 1062881,
"updated_at": "2024-05-17T19:36:51+02:00",
"openlineitems": [
{
"transitory": null,
"plu_nr": null,
"quantity": 1.0,
"productcategory_id": 13604,
"nights": 5,
"taxrate": 10.0,
"unitprice": 29.0,
"ids": [
2183738
],
"netto": 131.82,
"billflag": 1,
"pos_name": null,
"tax": 13.18,
"billed": null,
"price": 145.0,
"product_id": 179536,
"product_name": "Einzelzimmer"
},
{
"transitory": null,
"plu_nr": null,
"quantity": 1.0,
"productcategory_id": 0,
"nights": 5,
"taxrate": 0.0,
"unitprice": 2.5,
"ids": [
2183739
],
"netto": 12.5,
"billflag": 1,
"pos_name": null,
"tax": 0.0,
"billed": null,
"price": 12.5,
"product_id": 192977,
"product_name": "Ortstaxe"
},
{
"transitory": true,
"plu_nr": null,
"quantity": 41.0,
"productcategory_id": 0,
"nights": null,
"taxrate": 20.0,
"unitprice": 2.7,
"ids": [
2183740,
2183744,
2183745,
2183746,
2183747,
2183748
],
"netto": 92.25,
"billflag": 1,
"pos_name": "Weizen hell 0,3",
"tax": 18.45,
"billed": null,
"price": 110.7,
"product_id": 190185,
"product_name": "Bier"
},
{
"transitory": true,
"plu_nr": null,
"quantity": 1.0,
"productcategory_id": 0,
"nights": null,
"taxrate": 20.0,
"unitprice": 4.8,
"ids": [
2183742
],
"netto": 4.0,
"billflag": 1,
"pos_name": "Kaffee",
"tax": 0.8,
"billed": null,
"price": 4.8,
"product_id": 222165,
"product_name": "Kaffee & Tee"
}
],
"issued_invoice": {
"payments": [
{
"fop": "POS",
"id": 459654,
"number": 16,
"amount": 176.4,
"created_at": "2024-05-17T19:36:50+02:00",
"payment_date": "2024-05-17"
}
],
"id": 631359,
"lineitems": [
{
"transitory": true,
"poscharge_id": 84,
"quantity": 7.0,
"id": 2183749,
"nights": null,
"taxrate": 20.0,
"unitprice": 2.7,
"created_at": "2024-05-17T19:36:47+02:00",
"netto": 15.75,
"billflag": 1,
"pos_name": "Weizen hell 0,3",
"product_id": 190185,
"tax": 3.15,
"billed": 1,
"price": 18.9
},
{
"transitory": null,
"poscharge_id": null,
"quantity": 1.0,
"id": 2183750,
"nights": 5,
"taxrate": 0.0,
"unitprice": 2.5,
"created_at": "2024-05-17T19:36:48+02:00",
"netto": 12.5,
"billflag": 1,
"pos_name": null,
"product_id": 192977,
"tax": 0.0,
"billed": 1,
"price": 12.5
},
{
"transitory": null,
"poscharge_id": null,
"quantity": 1.0,
"id": 2183751,
"nights": 5,
"taxrate": 10.0,
"unitprice": 29.0,
"created_at": "2024-05-17T19:36:48+02:00",
"netto": 131.82,
"billflag": 1,
"pos_name": null,
"product_id": 179536,
"tax": 13.18,
"billed": 1,
"price": 145.0
}
],
"number": 19,
"total": 157.5,
"total_dl": 18.9,
"created_at": "2024-05-17T19:36:48+02:00",
"date": {
"^O": "Date",
"year": 2024,
"month": 5,
"day": 17,
"start": 2299161
},
"open_amount": 0.0
},
"status": "angezahlt",
"total": 315.0,
"total_dl": 134.4,
"assignments": [
{
"guestcard_name": "Greiner Gerhard",
"roomnumber": 111,
"guestcard_number": "1001201"
},
{
"guestcard_name": "Greiner Doris",
"roomnumber": 112,
"guestcard_number": "1001207"
}
],
"created_at": "2024-05-17T19:22:13+02:00",
"departure_date": "2024-05-22",
"res_person_name": "Greiner Gerhard",
"arrival_date": "2024-05-17",
"lastposcharge": {
"table_nr": 1.0,
"id": 91,
"hotel_id": 5302,
"lineitems": [
{
"transitory": true,
"poscharge_id": 91,
"quantity": 1.0,
"id": 1936734,
"nights": null,
"taxrate": 20.0,
"unitprice": 3.0,
"created_at": "2023-07-04T16:34:44+02:00",
"netto": 2.5,
"billflag": 1,
"pos_name": "Bier 0,3",
"product_id": 190185,
"tax": 0.5,
"billed": null,
"price": 3.0
},
{
"transitory": true,
"poscharge_id": 91,
"quantity": 8.0,
"id": 2183748,
"nights": null,
"taxrate": 20.0,
"unitprice": 2.7,
"created_at": "2024-05-17T19:34:54+02:00",
"netto": 18.0,
"billflag": 1,
"pos_name": "Weizen hell 0,3",
"product_id": 190185,
"tax": 3.6,
"billed": null,
"price": 21.6
}
],
"updated_at": "2024-05-17T19:34:53+02:00",
"net": 18.0,
"waiter_name": "Bedienung 1",
"guestcard_id": 60,
"gross": 21.6,
"created_at": "2024-05-17T19:34:53+02:00",
"check_nr": 238,
"waiter_nr": 1,
"tax": 3.6,
"reservation_id": 1062881,
"check_timestamp": 1715874273234
}
}
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. #end
Method to aggregate the details of the open line items:
Filter out items where quantity and price are both zero Convert the hash values to an array Sort the aggregated line items based on the initial IDs Assign the result to res[:openlineitems]
