Archive

Posts Tagged ‘reservation’

SWS GetSiteUnitData Method

April 20, 2011 2 comments

Retrieves a list of available rental items. Based on the parameters, it will retrieve the first unit available for the parameters requested. This will also return promotions for the items, if requested.

Parameters

Name DataType Is Required
Depth Decimal Optional
Description The depth of the rental item.
GetPromoData Boolean Required
Description Indicates you want to retrieve promotions with the unit data (“True”) or not (“False”).
HardReservable String Optional
Description Limits the return to only those units flagged as available for a hard reservation.
MaxRentRate Decimal Optional
Description Limits the results to only those units below the maxiumum rent rate in this parameter.
MinAvailable Integer Optional
Description Limits the return to only those unit types that have more than this number available.
MinRentRate Decimal Optional
Description Limits the results to only those units above the minimum rent rate in this parameter.
PromoDataType PCDTypeOptions Optional
Description The type of promotions you want returned.
Available values:

  • None
  • HighestPriorityPromotion
  • AllPromotions
  • HighestPriorityDiscount
  • AllDiscounts
  • HighestPriorityRateMod
  • AllRateMods
  • All
  • HighestPriorityDiscountandPromo
  • HighestPriorityPCDAndRateMod
SiteID Long Required
Description The site’s ID number. This can be found using the GetSiteList method.
SoftReservable String Optional
Description Limits the return to only those units flagged as available for a soft reservation.
Width Decimal Optional
Description The width of the rental item.

Returned Parameters

Name DataType
AVAILABLE Decimal
Description The total number of rental items available at the site.
CLASS_DESC String
Description The description of the site’s revenue class.
CURRENT_RATE Long
Description The current rent rate.
DEPTH Decimal
Description The depth of the rental item.
FEATURES_VAL String
Description The “Features” custom lookup value as defined by the site.
HARD_RESERVATION String
Description Indicates that the rental is available to be place on a hard reservation (“Yes”) or that it is not available for a hard reservation (“No”).
MAX_RENT_RATE Decimal
Description The maximum rent rate that can be charged for the rental item, determined by the admin.
MIN_RENT_RATE Decimal
Description The minimum rent rate that can be charged for the rental item, determined by the admin.
OBJ_PERIOD_UOM_VAL String
Description The description for the “Unit of Measure” (UOM) for the rental cycle. Currently the only option is “Month”.
PROMO_DESC String
Description The promotion, discount or rate modification’s description, if GetPromoData was set to “True”.
PROMO_DET String
Description The details of the current available promotion for the rental item, if GetPromoData was set to “True”.
PROMO_ID Decimal
Description The promotion’s ID number.
PROMO_NAME String
Description The promotion, discount or rate modification’s name.
PromoCollection PCDItem
Description The object containing all the information about the promotion/s.
QUANTITY Decimal
Description The total number of the specific rental items at the site.
RES_AMOUNT Decimal
Description The hard reservation deposit amount.
SITE_CLASS_ID Long
Description The site’s revenue class ID number.
SITE_ID Long
Description The site’s ID number.
SOFT_RESERVATION String
Description Indicates that the rental is available to be place on a soft reservation (“Yes”) or that it is not available for a soft reservation (“No”).
UNIT_ID Decimal
Description The unit’s ID number. This is maintained through rentals.
UNIT_NUMBER String
Description The unit’s number as assigned by the organization. This is not the UnitID.
VERSION Decimal
Description The unit’s version number which serves to prevent duplicate use of the unit. This is returned when you use any version of GetSiteUnitData or the GetUnitData method.
WIDTH Decimal
Description The width of the rental item.

Example

As with every method we need to pass in credentials. We do this with the LookupUser request object.

We’ll assume you’ve got a web reference, let’s name it SWS, in your Visual Studio project.  At this point we need to our objects.  We’ll need the standard service object, a GetSiteUnitData request object and a GetSiteUnitData response object. We can define and create those like this:

   ' Create a request and response objects
 Dim objService As New SWS.WSSoapClient
 Dim objReq As New SWS.GetSiteUnitData_Request
 Dim objRes As New SWS.GetSiteUnitData_Response

Here’s my sample code of the Request object.

 ' GetSiteUnitData Request
 With objReq
 .SiteID = 1000000001
 .GetPromoData = N
 .HardReservable = Y
 End With

Finally we can call the method and pass across the login object and the request object to get our site unit data. It’s a good idea to do this in a Try Catch block.

Try
    ' Call the method that will load the response object
 objRes = objService.GetSiteUnitData(objLogin, objReq)
 Catch ex As Exception
    MessageBox.Show(ex.Message)
 End Try

Note that if something goes wrong the service will respond with an exception. You’ll want to take a look at that message returned in that exception so it can be debugged.

Each organization has the ability to limit when a reservation can be made.
These limiting factors can be found at GetSiteRules.

For a full list of methods see SWS Methods.

SWS MakeReservation Method

Creates a rental, reservation or quote. Also converts a quote or reservation into a rental using the quote ID from the initial MakeReservation call.

A rental item can be put on hold by calling the UpdateUnitStatus SWS method, before calling this method, to ensure nobody else takes the rental item while setting up the reservation. If the customer declines the reservation/rental, you will need to call UpdateUnitStatus again, to make the unit available.

The progression of reservations to rental is Quote > SoftReservation > HardReservation > Rental. If you set up a quote, it can be updated to any of the following types of reservations. If you set up a hard reservation it can only be cancelled or set to a rental, it cannot go back in the progression.

Settings for the different types of quotes:

  • Quote – QuoteType = QuoteOnly, RentNow = False
    • Does not reserve a unit at all. If a customer wants to rent and no units are available, they will have to wait for a unit. No reservation fee can be applied as no rental is reserved.
  • Soft Reservation – QuoteType = SoftReservation, RentNow = False
    • Reserves a unit of the type requested. This does not guarantee a specific unit. A reservation fee cannot be applied as there is not a specific unit being held.
  • Hard Reservation – QuoteType=HardReservation, RentNow = False
    • Reserves a specific unit. A reservation fee may be applicable based on the site rules. If they have assigned a reservation fee, the total to hold the reservation can be found using the GetTotalDue method.
  • Rental – QuoteType = QuoteOnly, RentNow = True
    • The first payment of a rental is always required in full or, if the site allows it, can be deferred at the site. A deferral cannot be done through the API. If a move in payment is not taken, nightly processing will set the rental to abandoned and remove the rental from the customer’s account.

To convert a quote or reservation to a rental, use the quote ID from the initial call. Run the quote ID through MakeReservations again, choosing “True” for RentNow. This will put the unit into the “In-Process” status. Once a payment is completed, the quote will become a rental.

To prevent duplicate use of a unit, we use the version number.

For a work flow of what is required for a new reservation/rental, see the Workflow for Creating a Reservation or Rental. (Note: A move-in will always require a payment even if it’s a $0 cash payment, otherwise, the rental is cancelled by the system during our nightly processing.)

Parameters

Name DataType Is Required
AcctID Long Required
Description The account’s ID number. This is returned when you use the CreateNewAccount method or can be retrieved with the SearchBy method.
Contacts RentalContact Required
Description A collection of contact data to tie to the reservation/quote. Two contacts may be required if the site rules require it.
InquirySource Integer Optional
Description The available inquiry source for how customers heard about the site. This takes advantage of the Store Lookups feature in Org Admin. This can be found using the eInquirySource method.
Pcds TRAN_QUOTE_PCD_DETAIL Optional
Description A collection of promotions and discounts (PCD) to tie to the reservation. This is returned, if requested, in any of the GetSiteUnitData methods or can be retrieved with the GetAvailableDiscounts method.
Price Decimal Optional
Description Overrides the current rent rate of the unit. This will use the existing rent rate if left undefined.
QuoteExpiration DateTime Optional
Description The date the quote/reservation is no longer available. If passed in, it will override the rules in Store.
QuoteID Long Optional
Description The quote’s ID number. If this is left blank, then it will create a new quote with the information passed in. If this is entered it will update an existing quote/reservation.
QuoteStartDate DateTime Optional
Description The date that the quote record was created.
QuoteType Quote_Types Required
Description The quote’s type.
Available values:

  • QuoteOnly
  • SoftReservation
  • HardReservation
RentNow Boolean Required
Description Indicates that you want to set the unit as a rental (“True”) or as a quote or reservation (“False”).
SiteID Long Required
Description The site’s ID number. This can be found using the GetSiteList method.
UnitID Long Required
Description The unit’s ID number. This is returned when you use any of the GetSiteUnitData
calls and is maintained through rentals.
Version Decimal Optional
Description The unit’s version number which serves to prevent duplicate use of the unit.

Returned Parameters

Name DataType
QuoteID Long
Description The quote’s ID number.
RentalID Long
Description The rental item’s ID number. No rental ID is returned when a quote is created, this is only returned with reservations and rentals.

Example

As with every method we need to pass in credentials. We do this with the LookupUser request object.

We’ll assume you’ve got a web reference, let’s name it SWS, in your Visual Studio project.  At this point we need to our objects.  We’ll need the standard service object, a MakeReservation request object and a MakeReservation response object.  As part of the request object we also one or more RentalContact objects. We can define and create those like this:

// Create a request and response objects
SWS.WSSoapClient service = new SWS.WSSoapClient();
SWS.MakeReservation_Request request = new SWS.MakeReservation_Request();
SWS.MakeReservation_Response response;

SWS.RentalContact conRequest = new SWS.RentalContact();

Prior to setting the data in the MakeReservation Request object we’ll need to define our rental contact. It can take in an array of contacts but only one is required, unless specified otherwise by the site rules.  To establish a contact we need to define the ContactId, AddressId and PhoneID. These are created using the AddNewContact, AddNewAddress, and AddNewPhone methods. Please see the workflow mentioned above for additional information on account and contact creation.

// RentalContact object
conRequest.ContactId = 123456;
conRequest.AddressId = 123456;
conRequest.PhoneId = 123456;
conRequest.PrimaryFlag = true;

Here’s my sample code of the Request object.

// MakeReservation Request
request.SiteID = 123456;
request.AcctID = 123456;
request.UnitID = 123456;
request.Version = 5;
request.QuoteType = SWS.Quote_Types.QuoteOnly;
request.RentNow = false;
request.Price = 50m;
request.Contacts = new SWS.RentalContact[] { conRequest };

Finally we can call the method and pass across the login object and the request object to perform our reservation. It’s a good
idea to do this in a Try Catch block.

// Call the method that will load the response object
 try
{
  response = service.MakeReservation(user_request, request);
}
catch (Exception ex)
{
  MessageBox.Show(ex.Message);
}

Note that if something goes wrong the service will respond with an exception. You’ll want to take a look at that message returned in that exception so it can be debugged.

Each organization has the ability to limit when a reservation can be made.
These limiting factors can be found at GetSiteRules Info.

For a full list of methods see SWS Methods.