Latest

Blog Detail Title

Short Content Here

by Author Name

Date Published

Developer

POS Integration Guide

Andrea Stubbe November 13, 2018

This guide explains how you can connect your point of sales (POS) application to apaleo. If you are new to apaleo APIs, head over to the quick-start guide , and learn how you can implement the apaleo connect flow.

A word on revenue and accounting

If you are developing point of sales applications, you probably are an expert in this, but here's a short introduction to key concepts, and how they are implemented in apaleo.

First of, the key entity to interact with apaleo's financing functionalities is the folio. Each reservation has a main folio, which is where stay-related charges end up by default. It is also possible to add more folios to a reservation. A folio lists all services and goods (the 'charges') which will eventually end up on a guest's invoice, as well as all payments. Charges can be:

  • standard charges, delivered by the hotel, recorded as revenue and VAT. The invoice with VAT breakdown is done by the hotel
  • transitory, which means they are delivered by a third party, and are recorded as transitory items. The receipt/invoice, including a detailed VAT breakdown for these charges is done by the delivering party.

Why should services and good which are not delivered by the hotel go on the folio anyway, you wonder? The answer is a question, one that every guest keeps asking: "Can you put this on my room?" - and they do not care whether the restaurant serving them breakfast, or the in-house spa is a different entity, with a different tax ID.

When building an integration, they key questions to answer are:

  • Is the POS recording revenue for someone else than the hotel, and just adding it to the guest's invoice?
  • If it's for the hotel, should all accounting and receipt creation for POS-business be done by the POS, or in apaleo?

If the answers are 'yes', and 'should be done by the POS', then transitory charges are your friend. Otherwise, standard charges will do.

Point of sales integration APIs

Browse all apaleo APIs on https://api.apaleo.com/.  For most POS integrations, the Core APIs are the only ones needed. Switch between different modules using the dropdown in the top right corner.

 

swagger

To find "the room" where charges should be added to, access the Reservation APIs

GET /booking/v1/reservations

There are a variety of filters, and which ones you use is up to you. Most likely you will want to limit reservations to be in house, and then search for room number or guest name.

The Finance APIs let you access folios, invoices and the hotel's subledger. The first one you'll need is

GET /finance/v1/folios

Add the reservationId as a query parameter, and either get the main folio, or use any custom logic to find the folio you want to add charges or payments to.

One you identified the folio to use, you can perform different actions. The most useful being

POST /finance/v1/folio-actions/{folioId}/charges
POST /finance/v1/folio-actions/{folioId}/transitory-charges
POST /finance/v1/folio-actions/{folioId}/payments

The payment endpoint is neat, if the hotel is using the POS as a cash register.

POS for Pros

As explained above, the API you need to call depends very much on the hotel's setup and wishes. We recommend to build an integration for the two main cases, and let the hotel configure in your application, how things should work. Transitory or not, is the big question.
You can also use the API to add new folios to a reservation - if you want to have a dedicated POS-charge folio. Or, implement routing rules, by having smart logic to determine the folio to use.
If accounting is your strength, you can even access all apaleo accounting transactions, and store them in your system.

Whatever ideas you have - we're pretty sure, apaleo has an API for that. And if not, let us know on https://apaleo.github.com/apis.

Andrea Stubbe

Posted by

Andrea Stubbe
Andrea started coding as a kid, paused that for some years trying to find more interesting things, but then ended up doing that for a living. After working as a freelancer, researcher, teacher, and a normal employee in small and giant corporations, she fulfilled her childhood dream and co-founded a company a year ago. Being a fan of microservices since before she knew that term, she’s still contemplating how and if to use them in micro-sized companies.
Comments

RECENT ARTICLES

by Benjamin Schmid

01/20/2019

Upsell Integration Guide

This guide explains how you can connect your upselling application, and offer extra services or room upgrades to guests. If you are new to apaleo APIs, head ...

by Andrea Stubbe

01/02/2019

UI Integration Guide

This guide explains how you can include your views into the apaleo user interface. This allows users to see information or even trigger actions in your ...

by Andrea Stubbe

12/03/2018

Revenue Management Integration Guide

This guide explains how you can connect your revenue or rate management application (RMS) to apaleo. If you are new to apaleo APIs, head over to ...

WANT MORE AMAZING THINGS?

Subscribe to our a-list for all the fun:

  • Keep up to date with hotel trends
  • Understand what matters most to hotel clients
  • Sweet gifs and special offers

Get it in your inbox every Monday ;)

By entering your email you expressly consent to receive our newsletter every week and other material related to...