Loading hotel contracts
For suppliers with direct hotel contracts. Push hotels, rooms, meal plans, seasons, rates, offers and supplements into the platform, which then sells them through the API alongside other providers.
This page is for suppliers, not for agencies that book. If you hold direct hotel contracts (a DMC, for example), you can push hotels, rooms, meal plans, seasons, rates, offers and supplements into the platform. It then sells them through the normal booking API alongside its other providers.
Before you start
- You need a
supplierId(an integer). Ask your Nava account manager, or read it with the supplier endpoints. - Every call takes the
auth-tokenheader, and like every call to the API it sendsAccept-Encoding: gzip. Calls with a body addContent-Type: application/json. providerCodeis your code for the hotel, unique per supplier. It appears in the path of the single-hotel read and of the room, meal plan, rate, offer and supplement calls.
Supplier endpoints
| Method and path | Purpose |
|---|---|
GET /suppliers | List the operator's contract suppliers. Returns ContractSupplierVO[]. |
POST /suppliers | Create a supplier. Body ContractSupplierVO. |
GET /suppliers/{supplierId} | Read one supplier. |
PUT /suppliers/{supplierId} | Update one supplier. |
ContractSupplierVO fields, grouped for reading:
| Group | Fields |
|---|---|
| Identity | id, active, commercialName, legalName, supplierUsername, taxpayerId, commercialNumber, externalCode |
| Contact | contact, lastName, email, fromEmail, replyEmail, phoneNumber, mobile, emergencyNumber, address, country |
| Notes | notes, remarks |
| Flags | hotelExclusive, sendPassengerEmail, sendAccommodationDetails |
| Passenger data switches | mandatoryContactPhone, mandatoryEmergencyContact, mandatoryPassengerDocument, mandatoryPassengerDocumentExpiryDate, mandatoryPassengerBithdate (sic) |
The passenger data switches probably decide which requiredField entries Confirm returns for this supplier's hotels.
Hotel contract endpoints
| Method and path | Purpose | Body and response |
|---|---|---|
GET /hotel/{supplierId} | List the supplier's hotels | Returns GetContractHotelRS, with hotel[] as ContractHotelBasicVO |
GET /hotel/{supplierId}/{providerCode} | One hotel with everything | Returns ContractHotelCompletedVO |
POST /hotel/{supplierId} | Create a hotel contract | ContractHotelDetailedVO, returns ContractHotelCompletedVO |
PUT /hotel/{supplierId} | Update an existing hotel contract | ContractHotelDetailedVO, returns ContractHotelCompletedVO |
POST /hotel/room/{supplierId}/{providerCode} | Add a room type | ContractRoomVO, returns the same |
POST /hotel/mealplan/{supplierId}/{providerCode} | Add a meal plan | ContractMealPlanVO, returns the same |
POST /hotel/rates/{supplierId}/{providerCode} | Add rates | ContractHotelRateVO, returns the same |
PUT /hotel/rates/{supplierId}/{providerCode} | Modify rates | ContractHotelRateVO, returns the same |
POST /hotel/offer/{supplierId}/{providerCode} | Add an offer | ContractHotelOffersVO, returns the same |
POST /hotel/supplement/{supplierId}/{providerCode} | Add a supplement | ContractHotelSupplementVO, returns the same |
The endpoints and schemas are defined in the spec.
A suggested loading order
The spec doesn't prescribe an order. This one follows the dependencies between the objects.
Get your supplierId.
Create the hotel with POST /hotel/{supplierId}, including its rooms and meal plans (both are required in the body).
Add rates with POST /hotel/rates/{supplierId}/{providerCode}, each with its seasons and season prices.
Add offers and supplements.
Verify end to end through the booking API.
Schemas
Required fields are marked. Types are shown where the spec gives them.
Hotel
ContractHotelCompletedVO, returned by the hotel calls, is the same object plus active, contractId, facilities[] (strings), offers[], supplements[] and rates[]. ContractHotelBasicVO, used in the list, is a summary: active, contractId, providerCode, hotelname, latitude and longitude, address, category, chain, currency, releaseDays, minimumStay, maximumStay, and rooms[] and mealPlans[] as strings.
The request below contains the required fields, plus a room name and providerCode. The spec does not document value formats for the address fields, so they are left as placeholders.
curl -s --compressed -X POST "$NAVA_BASE_URL/hotel/$SUPPLIER_ID" \
-H "auth-token: $TOKEN" \
-H "Accept-Encoding: gzip" \
-H "Content-Type: application/json" \
-d @hotel.jsonRooms
Season prices, offers and supplements point at rooms by providerRoomCode, which is probably the room's providerCode.
Meal plans
Rates
Seasons
Season prices
Offers
Offers also take minimum and maximum stay, adults and children. The children fields are spelled minimumChildrens and maximumChildrens (sic). Ask your Nava account manager for the exact names of the others.
Supplements
ContractHotelSupplementVO works like an offer, with three differences: type is PERCENT or ABSOLUTE, there is no stay or pay, and names is optional. The required fields are releaseDays, providerRoomCodes and mealPlans.
Notes
- POST creates, PUT updates. The split is strict for hotels and for rates. Sending a
POSTfor aproviderCodethat already exists will probably fail, so usePUTfor every change after the first load. - Stop sales and quotas are per rate, season and room. Keep your channel manager as the source of truth and push only the deltas.
- Validate in your test account first. With no prose documentation, error behaviour is unknown. Keep every request and response for support, with the trace id (
auditData.traceIdor theTravelc-Trace-Idheader) and thex-request-idheader.
Verify end to end
After loading, check that your hotel sells:
Quote your hotel through the booking API, using the microsite that has your supplier connected.
Walk it through Confirm and Prebook, and check the price, meal plan, cancellation policies and required guest fields.
Book it with fakeBooking. A fake booking is not saved and not sent to suppliers, even in production.
Related
- The booking flow: how agencies quote and book your hotels.
- Hotel catalogue: categories and meal plan types.
- Enums:
MealPlanType,Languageand the other enums. - Environments: the base URL, and test and production credentials.