Government Invoicing and Fiscalization

Property can manage transactions, from within MFD or through partner app. Payment allocation, currently, can only be done in MFD.

Property Setup

To see the tax ID of the hotel, currency, and time zone use getHotelDetails (*)
To see which payment methods are allowed for the property account use getPaymentMethods.
To see which taxes and fees are set up and what is the value use getTaxesAndFees.
To see which items (product and services) property is selling aside from reservations and understand inventory structure in Cloudbeds use getItems and getItemCategories.

(*) Certification Mandatory Requirements

We offer two main flows for Government Invoicing and Fiscalization integrations:

Option 1 - Manage external invoices with Cloudbeds Invoicing API (recommended)

This is the preferred integration flow for Invoicing and Fiscalization integration. The Invoices API requires activation. You can email [email protected] to request the activation.
The Invoices API is available exclusively to technology partners that use API v. 1.2

Requirements

Subscribe to the following webhooks:
- reservation/invoice_requested
- reservation/invoice_void_requested
You will need to utilize the following APIs:

Workflow for External Invoices

Below you will find a diagram showing the flow for external invoices and a supporting explanation of what is expected in these use cases:

Issuing invoices

Subscribe to the reservation/invoice_requested Webhook . (*)
When the user issues an invoice in Cloudbeds, the reservation/invoice_requested webhook is triggered and the invoiceID will be included in the payload received. The user has the ability to select what transactions will be included on the invoice. (*)
After the invoice is requested, it will display as "Processing" on the Cloudbeds reservation page.

Once you receive the invoiceID in the webhook notification, call the getInvoice endpoint to retrieve the data required to generate an invoice (transactions, property name etc.). (*)
To update the status of the invoice in Cloudbeds, use patchInvoice with the correct status: "open" or "paid", as well as the invoice file to attach the Invoice to the reservation. (*)
This will replace the original Invoice issued in Cloudbeds.
If you wish to keep the Cloudbeds invoice and add the Invoice generated by your app as an additional file in the Goverment Receipts submenu, use postGovernmentReceipt to send the URL for the invoice file (PDF/XML) to be saved (and viewed by the property) in Cloudbeds PMS.
If an error occurs when trying to generate an invoice, information about the error needs to be uploaded to Cloudbeds so that the user has visibility into it. (*)
When an error occurs:
- Upload the error details to Cloudbeds via the postAppError API
- Set the status of the invoice in Cloudbeds to “failed” via the patchtInvoice API
- To add a QR code to the Cloudbeds invoice, upload a file to the reservation with the postReservationDocument endpoint. The file format should be "qr_.png".
  For example, if the invoiceID received in the webhook notification is 5846563, the file should be "qr_5846563.png".
It is recommended to use postReservationNote to store the relationship between the Cloudbeds invoice ID and the 3rd party invoice ID.

(*) Certification Mandatory Requirements

Issuing credit notes / voiding invoices

There are business reasons that make it necessary to void an invoice so that a new invoice can be generated. The workflow for that is the following:

Property user selects to Void Invoice in Cloudbeds
Invoice status is set to “Void Processing”
Subscribe to the reservation/invoice_void_requested Webhook. (*)
When the user voids an invoice in Cloudbeds, the reservation/invoice_void_requested webhook is triggered and the invoiceID will be included in the payload received. (*)
After the credit note is requested, it will display as "Void Processing" on the Cloudbeds reservation page.
Once you receive the webhook notification and process the credit note, update the status in Cloudbeds with patchInvoice with the voided status, as well as the invoice file to attach the Credit Note to the reservation. (*)
This will replace the original Credit Note issued in Cloudbeds.
If you need to keep the Cloudbeds credit note and add the Credit Note generated by your app as an additional file in the Goverment Receipts submenu, use postGovernmentReceipt to send the URL for the invoice file (PDF/XML) to be saved (and viewed by the property) in Cloudbeds PMS.
If an error occurs when trying to void an invoice, information about the error needs to be uploaded to Cloudbeds so that the user has visibility into it. When an error occurs:
- Partner will upload details via the postAppError API
- Partner updates status
- If there was an actionable error that can be resolved with changes to data in Cloudbeds (like a 300) , then the partner will set the status of the invoice back to either “Open” or “Paid”, whichever status it was when the user requested to void the invoice.
- If there was a client or server error (like a 400 or 500) in the government institution or the partner application, then the partner will set the status of the invoice to “Failed”
- It is recommended to use postReservationNote to store the relationship between the Cloudbeds invoice ID and the 3rd party invoice ID.

(*) Certification Mandatory Requirements

Additional scenarios

Invoice canceled (*)

When an invoice is in a status of “Requested” or “Failed” the user may wish to cancel the invoice so that they can try generating an invoice again. The workflow for that is the following:

User selects to Cancel Invoice in Cloudbeds
1. Invoice status is set to “Canceled”
2. reservation/invoice_void_requested webhook is triggered
Partner consumes webhook
If no external invoice exists related to this invoice, the process ends
If an external invoice exists related to this invoice, partner submits invoice to be voided to obtain official void invoice
1. Partner may also need to make a request to generate a Credit Note for the voided invoice
If a Credit Note was generated, partner uploads Credit Note via postGovernmentReceipt API
If an invoice was generated, partner sets status of invoice to “Voided”

(*) Certification Mandatory Requirements

Invoice manually reconciled

When an invoice is in a status of “Void Requested” or “Failed” the user may wish to resolve the issue directly within the partner or government web portal, and mark the invoice as being resolved outside of Cloudbeds. The workflow for that is the following:

User selects to reconcile the invoice
1. Invoice status is set to “Manually Reconciled”

Option 2 - Pulling transaction data (additional option)

As a second option to the preferred integration flow via the external invoices API, it is possible to generate invoices by pulling transaction or reservation data as described below:

One-Way Synchronization

Transactions and Reservations Data

To see the bill to data use getReservation.
To see all credits and debits posted into Cloudbeds folio use getTransactions. (* Option 1)
To see outstanding balances and create an invoice use getReservationInvoiceInformation (* Option 2)
You may also subscribe to the transaction/created Webhook to be notified when a new transaction is created in Cloudbeds.

(*) Certification Mandatory Requirements

Two-Way Synchronization

To upload the tax invoice back into Cloudbeds, use postGovernmentReceipt to send the URL for the invoice file (PDF/XML) to be saved (and viewed by the property) in Cloudbeds PMS. *
A PDF is mandatory and XML or other data file is optional (even when the tax invoice is in XML format).*
Any credit notes related to a Cloudbeds reservation (even if issued within your system) should be posted to Cloudbeds with postGovernmentReceipt.
It is recommended to use postReservationNote to add a note with the status of the invoice processing with the Authorities, including any official confirmation IDs (if available).

(*) Certification Mandatory Requirements.