This document provides detailed information about the available endpoints of Previo Channel manager API standard.
\nThis CHM Standard is designed for partners who want to connect their properties into Previo PMS via Previo CHM. Receive availability and pricing for their accomodations and send reservations and modifications to Previo PMS.
\nContact Previo CHM support team on chm@previo.cz and express your interest in connecting to Previo PMS
\nProvide your company informations. (Additional data can be requested)
\nIntro call is initialized with our support team (Strongly recommended)
\nYou will receive onboarding document, which will include your own URL for gitlab library. This library is designed to help you with implementation of Reservation sending to Previo. Its PHP library for version 8.1. You will also receive public key and prpID which is necessary for requesting and sending data.
\nYou will be requested to send us URL for your 3 endpoints developed in Previo CHM standard.
\nAfter implementation of all 4 topics (POST reservations, Get Rooms, Get Rate Plans, POST Data) certification call with CHM support will be initialized.
\nMapping
\nGet room types - Send a post request using previo/rooms?hotelId=123
\nGet rate plans - Send a post request using previo/ratePlans?hotelId=123&roomId=456
\nData updates
\nInventory updates
\nSend 0 availability for 1 day - 1 room
\nUpdate positive availability after received previous 0
\nUpdate positive availability 1 day - all room types
\nUpdate positive availability different dates - different rooms
\nPrice and restrictions updates
\nUpdate a room/rate price for 1 day
\nUpdate several room/rate prices - multiple dates
\nUpdate a room/rate/ per occupancy price
\nClose a room/rate for 1 day (Stop Sell)
\nSend CTA/CTD, min.stay, min.advance
\nReservations
\nSend new reservation for 2 guests
\nSend term modification
\nSend room type modification
\nSend cancellation
\nEndpoint created by Previo which will be used by partner (you) in order to send reservations (New or modified) into Previo.
\nBelow you can find more detailed explanation of each element and its usage, but also general informations. The table shows which elements are mandatory, their data type, and occurrence.
\nYou can mark each service within the reservation as prepaid, which is shown in Previo, so receptionist or Alfred (Previo app) will not demand additional payment for marked services.
\nWhen reservation is fully prepaid, you can set paid (room and addon) and taxPaid to true. In case of part payment, you can set paid to true only for some services, but only in case when specific service is fully prepaid.
\nFor example guest paid 50% of total price. In this case do not mark any service as prepaid, because currently there is no way how to transform this kind part payment.
\nFor these cases we recommend to use array payment, where you can send amount which was prepaid and it will be showed as reservation note in Previo.
\nSince totalPrice on reservation level is mandatory, it has to always contain sum of all items within the reservation (dailyPrices, addons and taxPrice). Discrepency might be caused by recurring decimals (0,333333) in dailyPrices, which result in incorrect totalPrice. We recommend to apply rounding to 2 decimal places, which is the same way how Previo works.
\nReservation ID (voucher) on partners side. Number has to be unique across all hotels. If reservations number are not unique, you can send reservationId as combination of hotel ID and reservation ID (4545455_123).
\nThe reservation Id value must contain a maximum of 25 characters otherwise reservation is not processed.
\nHotel ID on partner side.
\nStatus of reservation
\nPossible values:
\nnew
\nmodified
\ncancelled
\nReservation currency. Located on reservation and room level, both values has to be the same.
\nTime and date when new reservation was created. This value always determines the time of creation of a new reservation, if a modification or cancellation is sent, the value has to be the same as for a new reservation.
\nTime and date when reservation was modified/cancelled. When modification or cancellation is sent, the date and time must be different (in the future) than the time the new reservation was created.
\nIf not send, Channel manager will automatically set up the date and time based on when the message was recieved.
\nTotal price of the reservation/room.
\nThe value must contain the sum of all items sent at room level, such as dailyPrices, addons and taxPrice.
\nIf not sent, Channel manager will automatically calculate the value based on the items you sent in the message.
\nThe value must contain the sum of all items sent within the whole reservation, such as dailyPrices, addons and taxPrice.
\nCommission amount calculated by the partner.
\nCommission amount for a single room within the reservation
\nCommission amount for the whole reservation.
\nIf the reservation is not yet confirmed (e.g. due to non-payment or inquiry), it is sent as an option, where the option expires based on the \"optionExpiration\" element, which has a time and date value. When reservation is not confirmed (option expired), partner has to send reservation cancelation. In case of confirmation, send reservation modification without element \"optionExpiration\" and Previo will switch the reservation to state confirmed.
\nUsed for sending stay packages. Value determines specific package in Previo, value has to match package ID in Previo. Do not use if Hotel.getStayPackages API is not implemented.
\nPerson who made a reservation (Contact person). Usually the first guest in the reservation. Customer firstName and lastName is mandatory, when guests does not contain firstName and lastName, Channel manager will put the customer as the first guest in the reservation.
\nFor the \"guests\" element, it is not necessary to know the names of all guests. The most important is to send the correct number of guest and their ages. You can send customer firstName and lastName as the first guest in the reservation or leave it empty and Channel manager will do it automatically (see customer).
\nGuest type determinates the guest category to which the guest is saved when reservation is saved to Previo. There are several guest types you can send us, but the most important is to send correct age for each guests. Age has always the higher priroty when Previo determinates to which category guest should be saved to.
\nDetermines whether accommodation service is prepaid
\nPayment is used to specify payment type and additional information about how money should be charged. Mainly used when reservation is prepaid by online payment or bank transfer.
\nReservation can be paid by several methods, below is the list of each method and value which should by send as type.
\nPossible values:
\nCredit card - cc
\nBank transfer - transfer
\nCash - cash
\nPaid on partner side - ota
\nnot avaiable - na
\nAmount which was prepaid
\nCurrency of the payment. Currency should be always the same as the currency of the reservation.
\nAdditional information about payment. For example Paid deposit 200 EUR.
\nEach room within the reservation needs to be specified in this array
\nArrival and departure
\nRoom type ID on partner side.
\nRoom type name on partner side
\nRate plan ID on partner side
\nRate plan name on partner side
\nroomReservationId is used for to specify room within the room type, if your system is not saving such information, you do not need to send us real roomReservationId, but it is enought to differentiate roomReservationId for each room type, keep in mind that roomReservationId has to be different for each room withnih the group reservation.
\nFor example if group reservation contains of two room types, roomReservationId for the first room type would be 1 and second 2.
\nWhen guest modifes the reservation, send us the same roomReservationId as you sent in new reservation. roomReservationId should be changed only when guest modifies the room type, for example change from Double to Triple room.
\nOrdered meal type
\nPossible values:
\nWithout meal - none
\nBreakfast - breakfast
\nLunch - lunch
\nDinner - dinner
\nHalf board - half-board
\nFull board - full-board
\nAll inclusive - all-inclusive
\nCity tax amount. If not sent, Previo will calculate the tax price based on the client's settings.
\nDetermines whether city tax is prepaid. Set it to true only if city tax has been prepaid, otherwise do not specify it or send false, so Previo will determine the payment based on accomodation setting.
\nThis array is used to send price for each night. Most importat is to send element date and price.
\nExtra service for specific room type (reservation), for example cleaing fee, bottle of wine, pet fee.
\nName of extra service
\nPrice of extra service
\nSpecifies if extra service is prepaid
\nSpecifies how many extra services guest ordered
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"PMAK-67b358f9c44b57000165b501-c975452fec5b884d381896d67ed1555d4f"}]},"isInherited":true,"source":{"_postman_id":"488b7ae6-3cc5-4f2d-bd97-a848cd0fc73d","id":"488b7ae6-3cc5-4f2d-bd97-a848cd0fc73d","name":"Previo Channel manager Standard","type":"collection"}},"urlObject":{"protocol":"https","path":["api","reservation"],"host":["chmproxy","previo","app"],"query":[],"variable":[]}},"response":[],"_postman_id":"44777b67-50a4-4293-bdeb-de2c6b9c7854"},{"name":"Mapping - rooms","id":"9ab1b92a-6be7-4a96-a335-33342c49497c","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{"accept":true}},"request":{"auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"Endpoint which must be created by partner (you) in order to create mapping of room types from Previo with room types in your system.
\n","urlObject":{"path":["previo","rooms"],"host":["https://4abf2754-c507-4934-a463-e7156ee3469f.mock.pstmn.io"],"query":[{"key":"hotelId","value":"123"}],"variable":[]}},"response":[{"id":"e31af994-576c-49bb-a358-1e580c74a1ed","name":"Mapping - rooms","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"https://4abf2754-c507-4934-a463-e7156ee3469f.mock.pstmn.io/previo/rooms?hotelId=123","host":["https://4abf2754-c507-4934-a463-e7156ee3469f.mock.pstmn.io"],"path":["previo","rooms"],"query":[{"key":"hotelId","value":"123"}]}},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\r\n \"hotelId\" : 123,\r\n \"rooms\": [\r\n {\r\n \"id\": \"456\",\r\n \"name\": \"name\",\r\n \"active\": true,\r\n \"defaultAllotment\": 2,\r\n \"maxAllotment\": 3,\r\n \"minNumAdults\": 1,\r\n \"maxNumAdults\": 2,\r\n \"numChildren\": 2,\r\n \"numOfRooms\": 10\r\n },\r\n {\r\n \"id\": \"789\"\r\n }\r\n ]\r\n}"}],"_postman_id":"9ab1b92a-6be7-4a96-a335-33342c49497c"},{"name":"Mapping - rate plans","id":"bdedf63c-21c7-487e-b365-ebc2dad51cfd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"Endpoint which must be created by partner (you) in order to create mapping of rateplans from Previo with rateplans in your system.
\nMeal types:
\nbreakfast
\nhalfboard
\nfullboard
\nallinclusive
\nnone
\nPricing models:
\n1 - occupancy based
\n2 - per day
\nEndpoint which must be created by partner (you) in order to receive rates, availability and restrictions from Previo CHM.
\nSee the full structure of the request in the right column.
\nWithin a single HTTP request, multiple change requests may be included (see the \"requests\" key in the right column), each with a unique value in the requestId attribute. This requestId is important for the Response in the case of the error (see the section Respose below)
hotelId - Property ID on partner side
\nrequests - an array of requested changes
\nrequestId - Automatically generated, unique ID for each change.
\nroomTypeId - Room type ID on partner side
\nratePlanId - Rate plan ID on partner side
\ncreated - Time and date when request was generated
\nfrom/to - Period of the update (inclusive date in element to)
\nstopSale - Closure of rate plan. Values: true/false
\nprices - Informations about pricing type, currency and rates.
\npriceType - Specifies whether prices are sent per person or per room. Possible values are \"per-room\" or \"per-occupancy\"
\ncurrency - Currency of rates and mealPrice. Example: CZK, EUR,...
\nrates - Price for specific number of person or multiple persons
\nmealPrice - Meal price for single person
_Price for 1 person is sent - the total price is calculated by multiplying the number of persons (e.g. price for breakfast is 10 EUR, the price for double room for 1 person is 100 EUR, for 2 persons 120 EUR - the price for accommodation with breakfast is 110 EUR for 1 person. and 140 EUR for 2 persons).__The mealPrice value can be negative._If mealPrice is null, the specific combination of room type and rate plan (within the request) must be closed (the same behavior as if a stop sale has been sent).
availability
\nrestrictions - Restriction types
\nminimumStay - Restricts minimum number of nights
\nmaximumStay - Restricts maximum number of nights
\nclosedToArrival - Determines whether arrival is available. Values: true/false
\nclosedToDeparture - Determines whether departure is available. Valules: true/false
\nminAdvanceOfReservation - Minimal (time) advance for creating a reservation for particular day. Number in hours.
Relative to midnight of the day for which it is set - the resulting time of possible reservation is equal to midnight minus the set restriction value in hours (e.g. midnight minus 7H restriction = reservation only until 17:00 on a given day)
dataChanges - Data which needs to be processed (were changed)
\nrates - Price change (including mealPrice). Values: true/false
\nallotment - Availability change. Values: true/false
\nrestrictions - Restrictions change. Values: true/false
\nstopSale - Stop Sell change. Values: true/false
\nSee the structures of different responses in the right column.
\nThe response contains a list of errors and warnings (under separate keys).
Individual errors are linked to a specific change request via the requestId. Each error must contain its type (see the list below).
Warnings are simply a list of strings.
If all change requests are processed successfully, the return value is therefore an empty JSON object {}.
The response structure is strict
\nAUTHORIZATION
\nINVALID_REQUEST - issue in format, for example missing roomTypeId element
\nINVALID_DATA - use in case when some values sent within the request does not match with values set up on our side. For example invalid ID of roomTypeId, ratePlanId or invalid currency.
\nPERMANENT
\nTEMPORARY
\n