VacAgent. Agents API.

Size: px

Start display at page:

Download "VacAgent. Agents API."

Claire Gray
5 years ago
Views:

1 VacAgent Agents API

2 Revision sheet Version Rev. No Date Description /09/18 Improvements in document

3 1 Overview This document describes the REST APIs and resources provided by VacAgent s Agents API. The REST APIs are for developers who want to integrate VacAgent s inventory into their systems. VacAgent's REST APIs provide access to resources via URI paths. To use a REST API, your application will make an HTTP request and parse the response. The response format is JSON. Your methods will be the standard HTTP methods like GET, PUT, POST and DELETE. Because the REST API is based on open standards, you can use any web development language to access the API. 2 API version This is the documentation for Agents API REST API version 1, revision API version number Backward compatibility from the technical point of view is guaranteed for all API revisions within the same API version number. A change in the API version number implies that the new version is no longer backward compatible with the previous versions. While we do our best to continue supporting old versions of API, it may be sometimes necessary, due to constant evolution of the application, to end the support for those versions, and ask our customers to upgrade their applications to use the latest version of the API. 2.2 API revision number The API revision number changes each time the API is updated in such a way that the backward Compatibility with previous revisions of the same API version is usually maintained. New API methods may be added, and existing methods may become deprecated but still supported. 3 Implementation details 3.1 Communication protocol The Agents API REST API is a REST-like implementation based on the HTTP protocol, JSON data encoding and Unicode character encoding, over the secure HTTPS transport. 3.2 Authentication When invoking API methods, clients must authenticate using VacAgent s Agent account username and an API specific password, which may differ from the account password. The Agents REST API implements HTTP Basic Authentication (RFC 2617). You can find how to perform request to our API in Appendix Character encoding The API uses UTF-8 character encoding, the most widely used multi-byte character encoding for Unicode. 3.4 Data encoding All exchanges are encoded in the JSON (JavaScript Object Notation) format (RFC 4627). JSON is a simple machinereadable data-interchange format that provides light-weight serialization for structured data. Despite the acronym, JSON is language independent, and is widely implemented in modern programming languages.

4 JSON is able to directly represent the most general computer science data structures (see JSON native data types). Compared to XML, JSON has a significantly lower footprint, is more readable and more easily parsed. For more information about JSON, please refer to Data types In this API, we benefit from all native data types defined by the JSON format, and we also define other commonly used data types. Here's the exhaustive list of data types referenced in this documentation JSON native data types Type string number array bool null Description A sequence of zero or more UTF-8 characters An integer or floating point number An ordered and zero-based indexed sequence of values of any JSON type Boolean, may be either true or false The null value is a primitive value that represents the empty, null reference Extended data types Other non-primitive data types are used throughout this documentation. These are data abstractions with more specific, predefined characteristics. Type Description int Positive integer value represented as number. Range: string(x) string(x, Y) date string(10) string having exactly X characters String having X up to Y characters (both inclusive). Containing date representation in "YYYY-MM-DD" format. The default range " " " " may be further restricted by individual methods enum(x) object(x) Enum of type X Object of type X

5 3.6 Invoking API methods API methods are invoked by making an HTTPS GET/POST request on the VacAgent s Agents REST API servers HTTP request In order to invoke an API method, the client makes an HTTPS GET/POST request on where method is a unique case-sensitive string that identifies the desired API method. Basic HTTP authentication must be used in every request. The request Content-Type header must be set to application/json. Get data should be sent over the query string. Post data (HTTP request body) must hold a JSON representation of input data. Example of a valid HTTP request: GET /VacAgent/api/location HTTP/1.1 Content-Type: application/json Accept: application/json HTTP reply Each request results in an HTTP reply being returned to the client. The HTTP reply contains regular HTTP reply headers, an HTTP status code, and an optional HTTP content body. The HTTP status code must be examined in order to determine whether the API method was successfully invoked, or if a problem occurred (such as failed authentication, malformed message, ) Status code Code Description 200 Service was successfully invoked, process content body for further information (success/failure, ). 301 The URL of the service has changed permanently. The client should transparently follow the redirection. Note that VacAgent will inform all API users whenever the API method URL changes (by providing latest revision of this document), along with setting up this redirection. 400 Bad (malformed) HTTP request (according to HTTP and/or these API specifications). 401 Bad credentials (i.e. missing or invalid username and/or password). 403 Access refused (i.e. access from unauthorized IP address or network). 404 Unknown API method. 405 Method not allowed (POST method expected). 410 The requested version of the API is no longer available.

6 413 Request entity too large (i.e. raw post data size exceeds the maximum allowed size). 415 Unsupported media type (i.e. the received Content-Type is not application/json, or the content itself is not a valid JSON string). 500 The server encountered an unexpected condition which prevented it from fulfilling the request. Client should wait and resubmit the request. 503 The server is currently unable to handle the request due to temporary overloading or maintenance of the server. Client should wait and resubmit the request. Note that other RFC 2616 compliant HTTP status codes may be returned by the API server or HTTP proxies. Those codes must be interpreted as specified by RFC Content body The HTTP reply content body is status dependent. On successful API method invocation (status: 200), the server replies with the Standard method reply object. Otherwise, the Content-Type header is set to text/plain, and the content body may contain a human readable message explaining the reason of the failure. The message is a hint for developers, and is not intended to be parsed and understood by software. Developers should however consider logging these messages for further review Standard method reply object On successful API method invocation, the server returns 200 HTTP status code and fills the HTTP reply content body with a standard method reply object. The reply Content-Type is set to application/json. 4 Testing & Production 4.1 Sandbox VacAgent s sandbox provides a testing environment for your code integration. All REST APIs are available on the sandbox via Contact us to receive credentials for the sandbox. 4.2 Production Once you are ready to move your code into production, let us know so we can assign you with production credentials. Production APIs are available via 5 API methods reference This section contains a short reference of the API methods provided by this API version. A fully interactive documentation and testing environment is available at for all methods.

7 5.1 Location Usage This method returns a list of all system supported locations. Use this method to build a local cache of all VacAgent s locations mapping location name and ID Input This method can accept a parameter term to return all matching locations. Currency Output This method returns a key-value array. [{"key":690,"value":"akaroa, New Zealand"},{"key":840,"value":"Alta Gracia, Argentina"}, {"key":722,"value":"ankara, Turkey"}] 5.2 Currency Usage This method returns a list of all system supported currencies. Use this method to build a local cache of all currencies mapping currency symbol, rate, code and ID Input This method does not accept any input Output This method returns a currency rates array. All rates are specified vs the USD. [{"id":1,"code":"usd","symbol":"$","rate":1},{"id":2,"code":"ils","symbol":" ","rate": },{"id":3,"code":"gbp","symbol":" ","rate": },{"id":4,"code":"eur","symbol" :" ","rate": }] 5.3 Enum Usage This method returns a list of values for different enum types in VacAgent used in this API. Use this method to translate enum values Input This method accepts a parameter type which should be one of the following: Type amenity bed building apartment Description List of amenities List of bed types List of building types List of apartment types

8 5.3.3 Output This method outputs an array of key-values. Example for api/enum?type=amenity: [{"key":1,"value":"cable TV"},{"key":2,"value":"Wireless Internet"},{"key":3,"value":"Air Conditioning"},{"key":4,"val ue":"elevator in Building"},{"key":5,"value":"Wheelchair Accessible"},{"key":6,"value":"Pool"},{"key":7,"value":"Kitch en"},{"key":8,"value":"free Parking on Premises"},{"key":9,"value":"Doorman"},{"key":10,"value":"Gym"},{"key":11," value":"hot Tub"},{"key":12,"value":"Indoor Fireplace"},{"key":13,"value":"Buzzer/Wireless Intercom"},{"key":14,"val ue":"breakfast"},{"key":15,"value":"washer"},{"key":16,"value":"dryer"},{"key":17,"value":"coffee Machine"},{"key": 18,"value":"Private Roof"},{"key":19,"value":"Garden"},{"key":20,"value":"Heating"},{"key":21,"value":"TV"},{"key":2 2,"value":"Internet"},{"key":23,"value":"Family/Kid Friendly"}] 5.4 Search Usage This method searches for available properties in the system according to the search criteria passed to it Input This method accepts multiple parameters via URL: Parameter Required Default Description destination.id No - Id of location to search in destination.city No - Exact name of location to search in destination.wildcard No - Wildcard name of location to search in checkin Yes - Arrival date YYYY-MM-DD checkout Yes - Departure date YYYY-MM-DD guests No 2 Number of guests currencyid Yes - Currency in which we would like to receive our results instantbooking No true If true, search will be done only on instant bookable properties. filter.amenities No - Array of required amenity IDs (api/enum?type=amenity) filter.bedrooms No - Type of apartment (api/enum?type=apartment) filter.bathrooms No 0 Number of bathrooms filter.beds No 0 Number of beds

9 page No 1 Page number resultsperpage No 15 Number of results to return per page. sort No Price Results sort method. Price or PriceDescending Output This method outputs a SearchResult object: request Object(SearchRequest) Your search request properties Array[Object(PropertySearchResult)] Array of matching properties paging Object(ApiPaging) Paging object PropertySearchResult object: id Int Property ID name String Property name imageurl String Property main image url address String Property address locationid Int Property location id Latitude Float Property latitude coordinate Longitude Float Property longitude coordinate locationname String Property location name type Enum(ApartmentType) Type of the apartment (api/enum?type=apartment) defaultrate Object(PropertyDefaultRateInfo) Default rate information PropertyDefaultRateInfo object: currencyid Int Currency id

10 currencycode String Currency code pricepernight Int Property default price per night minstay Int Default minimum stay originalcurrencyid Int Property s original currency id originalcurrencycode String Property s original currency code originalpricepernight Int Property s original default price per night ApiPaging object: currentpage Int Current returned page totalpages Int Total available pages 5.5 Property Usage This method returns information about a specific property Input This method accepts the following: Parameter Required Default Description id Yes - Id of property currencyid Yes - Currency id Output This method outputs a PropertyInformation object: address String Property address apartmenttype Enum(ApartmentType) Number of bedrooms in the apartment (api/enum?type=apartment) Bathrooms Int Number of bathrooms

11 Beds Int Number of bedrooms buildingtype Enum(BuildingType) Property building type (api/enum?type=building) bedtype Enum(BedType) Property bed type (api/enum?type=bed) checkintime Int Checkin hour of the day. From 7 to 20. checkouttime Int Checkout hour of the day. From 7 to 20. cleaningfee Int Cleaning fee that is added for each booking request. currencyid Int Currency for all prices currencycode String Currency code Id Int Property ID locationid Int Property s location id locationname String Property s location name Logo String Main property image amenities Array(int) Array of amenity ids (api/enum?type=amenity) extraguestfeefrom Int Number of guests from which any additional guests is charged for an extra guest fee extraguestfee Int Extra guest fee / night name String Property s name size Int Size of the apartment in sqft accommodates Int Max number of guests the property can accommodate zipcode String Property s zipcode floor String(0,4) Property s floor latitude Float Property s latitude coordinate longitude Float Property s latitude coordinate description String Property s description

12 services String Property s services description instantbooking Bool Is property available for instant booking area Array(int) Array of sub location ids images Array(string Array of image urls of the property unavailable Array(date) Array of dates in which the property is unavailable cancellationpolicy Enum(CancellationPolicy) Fixed cancellation policy cancellationpolicies Array(Object(PropertyCancellationPolicyModel)) List of cancellation policy conditions PropertyCancellationPolicyModel object: id Int Policy condition ID propertyid Int Property ID validfrom Int Number of days before checkin when this policy becomes valid validto Int Number of days before checkin when this policy becomes invalid percentageoftotal Int Percentage of full price to pay in case of cancellation includefees Bit Does cancellation includes fees {"address":"king George 78","apartmentType":1,"bathrooms":1,"beds":1,"buildingType":1,"b edtype":0,"checkintime":8,"checkouttime":9,"cleaningfee":30,"currencyid":1,"currencycode ":"USD","id":3920,"locationID":22,"locationName":"Tel Aviv","logo":" 1.cloudfront.net/PropertyLogos/20/image jpg","amenities":[8,16,10,23,4,19],"extraGuestFeeFrom":2,"extraGuestFee":20,"name":"Sp acious SoHo Loft Apartment in New York","size":900,"accommodates":6,"zipcode":"12345"," floor":"3","description":"lorem Ipsum is simply dummy text of the printing and typesetti ng industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500 s, when an unknown printer took a galley of type and scrambled it to make a type specime n book. It has survived not only five centuries, but also the leap into electronic types etting, remaining essentially unchanged. It was popularised in the 1960s with the releas e of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop pub lishing software like Aldus PageMaker including versions of Lorem Ipsum.","services":"Lo rem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer t

13 ook a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentiall y unchanged. It was popularised in the 1960s with the release of Letraset sheets contain ing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.","instantBooking":true,"areas":[1031,1076,1 078,1035,1034],"images":[" jpg"," jpg"," jpg"," jpg"," jpg"," jpg"," jpg"," 5.6 Availability Usage This method returns information about a specific property s availability and pricing Input This method accepts an AvailabilityRequest object: Parameter Required Default Description id Yes - Id of property From Yes - Arrival date YYYY-MM-DD To Yes - Departure date YYYY-MM-DD Guests Yes - Number of guests currencyid Yes - Currency id

14 GET api/availability/3920/ / /2/ Output This method outputs an AvailabilityResult object: propertyid Int Property id isavailable Bool Is property available for these dates Error String If isavailable=false, Error will contain reason (unavailable dates, min stay not reached, etc) Checkin Date string(10) Date of arrival Checkout Date string(10) Date of departure Guests Int Number of guests Price Int Avg. Price per night for the entire stay Cleaningfee Int Cleaning fee per booking extrapersonfee Int Extra person fee extrapersons Int Number of extra persons Total Int Total price = ((extrapersons * extrapersonfee) + Price) * Nights) + CleaningFee. currencyid Int Currency id of all prices originalcurrencyid Int Property s original currency id originalcleaningfee Int Property s cleaning fee in original currency originalextrapersonfee Int Property s extra person fee in original currency originalprice Int Property s avg.price / night in original currency {"propertyid":3920,"isavailable":true,"error":null,"checkin":" t00:00:00","checkout":" T00:00:00","guests":2,"price":100,"cleaningFee":30,"extraPersonFee":20,"extraPersons":0,"total":930,"currencyI D":1}

15 5.7 Book Usage This method lets you book a property after receiving availability information for via api/availability Input This method accepts a PropertyBooking request: propertyid Int Property id checkin Date string(10) Date of arrival checkout Date string(10) Date of departure guests Int Number of guests guest String The guest s address guestname1 Object(GuestName) Primary guest name guestname2 Object(GuestName) Optional guest name guestname3 Object(GuestName) Optional guest name pricepernight Int Avg. Price per night for the entire stay cleaningfee Int Cleaning fee per booking extrapersonfee Int Extra person fee extrapersons Int Number of extra persons total Int Total price = ((extrapersons * extrapersonfee) + Price) * Nights) + CleaningFee. currencyid Int Currency id of all prices payment Object(PaymentCard) Payment details object guestinformation Object(PersonalDetails) Personal details of booker PaymentCard object: Type String Credit card type (VISA, Mastercard or AMEX) Number String(8,16) Credit card number

16 Series String(3,4) Credit card cvv code Month Int Expiry month (1-12) Year Int Expiry year YYYY CardHolderName String Credit card holder name PersonalDetails object: Firstname String First name Lastname String Last name String Valid address Phone String Valid phone number (including +country code) GuestName object: Degree String Mr/Mrs Name String Guest full name POST /api/book HTTP/1.1 Host: sandbox.vacagent.net Content-Type: application/json { "propertyid": 3920, "checkin": " ", "checkout": " ", "guests": 2, "price": 100, "cleaningfee": 30, "extrapersonfee": 20, "extrapersons": 0, "total": 930, "currencyid": 1, "guestinformation": { "firstname": "John", "lastname": "Doe", " ": "john.doe@gmail.com", "phone": " " }, "payment": { "type": "Mastercard", "number": " ", "month": 12, "year": 2016, "series": 123, "cardholdername": "John Doe" } } Output This method outputs a BookingResult object Status String Booking result: 'Success' or SuccessWaitingForApproval or 'PricesMismatch' or 'NotAvailable' or 'InvalidGuestInfo' or

17 FinalPriceLowerThanNet or 'CCError' or 'InternalError' CCResult Object(CCChargeResult) Credit card charge result BookingID Int Newly created booking ID. -1 on error CCChargeResult object: Status String Charge status: 'Valid' or 'Denied' or 'Expired' or 'Invalid' or 'InternalError' AuthorizationCode String Credit company authorization code. ChargeAmount Number Amount charged ChargeCurrencyID Int The charge currency id Appendix 1. var requestpromise = require('request-promise'); // Change credentials here!!!! var user = 'user@user.com'; var password = 'your_password'; var base64encodeddata = new Buffer(user + ':' + password).tostring('base64'); // Get locations requestpromise.get({ uri: ' headers: { 'Authorization': 'Basic ' + base64encodeddata }, json: true }).then(function ok(jsondata) { console.dir(jsondata); }).catch(function fail(error) { console.log(error); });

Kigo RENTAL AGENCY REST API - V1. API revision 12 Document revision 18. Contact Vedad KAJTAZ Kigo, Inc.

Kigo RENTAL AGENCY REST API - V1 API revision 12 Document revision 18 Contact Vedad KAJTAZ vedad@kigo.net Page 1 / 70 1 Revision history API Rev Document Date Changes Rev Status 1 1 DRAFT 04 May 2011 First