Web Services - Reservation Calendar

Version history

Version	Date	Update / Definition
16.4.2	28.10.2021	Added the part about error handling.

1 Module Overview

General information about the NetBaron-Web Services interface is provided in a separate document, available from NetBaron support upon request. This document describes only the Sales Order Web Services module, which enables the use of NetBaron® Reservation Calendar from external services.

Error handling must be integrated into the interfaces in case of connection interruptions.

1.1 Usage Examples

Import into NetBaron the reservations within the desired time range from the booking calendar.

2 Technical Information

2.1 Service Information

Address:	https://server/ws/reservationcalendar If an additional parallel interface has been enabled, the interface number must be specified along with the address to ensure the interface is called from the correct address. Otherwise, authentication will fail. For example: https://server/ws/reservationcalendar2
Authentication:	Organization and the organization-specific Web Services password
The character set used:	UTF-8
Available methods:	GET
Type of request:	Object
Type of response:	Object

2.2 Request Content (GET)

Element	Type	Use	Default	Definition
ShowWait	boolean	Control message	FALSE	true = retrieve unprocessed reservations
ShowAccepted	boolean	Control message	TRUE	true = retrieve accepted reservations
ShowRejected	boolean	Control message	FALSE	true = retrieve rejected reservations
Calendar	string(250)	Search criteria		Calendar
DateStart	date(YYYY-mm-dd)	Search criteria		Start date of search
DateEnd	date(YYYY-mm-dd)	Search criteria		End date of search

2.3 Reservation Content

Element	Type	Definition
ResponseStatus	int (0/1)	0=Error 1= OK, Operation completed successfully
ResponseMessage	string	Additional description of events, errors, etc.
TimeInterval	string	Query time interval: DateStart – DateEnd
Events	array	Retrieved reservations

2.4 Events-table (reservations)

Element	Type	Definition
DateStart	date(YYYY-mm-dd)	Start date of entry
TimeStart	time(HH:ii:ss)	Start time of entry
DateEnd	date(YYYY-mm-dd)	End date of entry
TimeEnd	time(HH:ii:ss)	End time of entry
ReservationStatus	int(1)	Reservation status: 1 = Unprocessed 2 = Rejected 3 = Approved

3 Code samples

It should be noted that the code samples presented in the documents are examples of how the interface can be used. Implementation of the codes requires PHP knowledge from the www-service provider. NetBaron Solutions Oy is not responsible for any direct or indirect damage and costs related to the sample codes when a third party does the implementation and further development.

Please note: The code created by your software developer must not cause server overload situations. We reserve the right to bill the creator of the software code or the end customer for system failure in the server environment. If necessary, please get the software code checked by sending it to tuki@netbaron.fi and adding the mention: "WS-Sales Reservation Calendar interface software code to product development for review and possible feedback".

3.1 PHP

PHP

<?php
$ns = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd';
$token = new stdClass;
// Depending on the client-side encoding, utf_encode may be required.
$token->Username = new SOAPVar("username", XSD_STRING, null, null, null, $ns);
$token->Password = new SOAPVar("password", XSD_STRING, null, null, null, $ns);

$wsec = new stdClass;
$wsec->UsernameToken = new SoapVar($token, SOAP_ENC_OBJECT, null, null, null, $ns);
$soapHeaders[] = new SOAPHeader($ns, 'Security', $wsec->UsernameToken, true);
/**
 * Client
 */
$client = new SoapClient(null, array(
	"location" => "https://<serverurl>/ws/reservationcalendar",
	"uri" => "urn:NBWS",
	'style' => SOAP_RPC,
	'use' => SOAP_LITERAL,
	"soap_version" => SOAP_1_2,
	"compression" => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 5,
	"trace" => 1)
);
/**
 * Set headers
 */
$client->__setSoapHeaders( $soapHeaders );

/**
 * Call PHP soap
 */
try{

	$Request = new stdClass();
	$Request->ShowWait = false;
	$Request->ShowAccepted = true;
	$Request->ShowRejected = false;
	$Request->Calendar = utf8_encode("mycalendar");
	$Request->DateStart = utf8_encode("2010-04-01");
	$Request->DateEnd = utf8_encode("2010-04-30");

	$response  = $client->get( new SoapVar($Request, SOAP_ENC_OBJECT,"","","Request") );

	$responserows = "";
	$responserows .= "ResponseStatus => ".$response->ResponseStatus."<br>";
	$responserows .= "ResponseMessage => ".$response->ResponseMessage."<br>";
	$responserows .= "TimeInterval => ".$response->TimeInterval."<br>";
	$stat=array(1 => "Wait", 2 => "Rejected", 3 => "Accepted");
	if(is_array($response->Events)){
		foreach($response->Events as $k => $r){
			$responserows.="Event: ".$r["DateStart"]." ".$r["TimeStart"]." - ".$r["DateEnd"]." ".$r["TimeEnd"]." -> ".$stat[$r["ReservationStatus"]]."<br>";
		}
	}
	
	$response = "<b>RESPONSE</b><pre>".utf8_decode($responserows)."</b></pre>";
}
catch(SoapFault $fault){
	$response .= "<b>SOAP Fault:</b><pre>faultcode: {$fault->faultcode}, faultstring: {$fault->faultstring}</pre>";
}
?>

3.2 XML Content

3.2.1 Request

XML

<?xml version="1.0" encoding="UTF-8"?>
    <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" xmlns:ns1="urn:NBWS" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
        <env:Header>
            <wsse:Security env:mustUnderstand="true">
		<wsse:UsernameToken>
                     <wsse:Username>username</wsse:Username>
                     <wsse:Password>password</wsse:Password>
		</wsse:UsernameToken>
            </wsse:Security>
        </env:Header>
        <env:Body>
            <ns1:get>
                <Request>
                    <ShowWait>false</ShowWait>
                    <ShowAccepted>true</ShowAccepted>
                    <ShowRejected>false</ShowRejected>
                    <Calendar>mycalendar</Calendar>
                    <DateStart>2010-04-01</DateStart>
                    <DateEnd>2010-04-30</DateEnd>
                </Request>
            </ns1:get>
        </env:Body>
    </env:Envelope>

3.2.2 Response

XML

<?xml version="1.0" encoding="UTF-8"?>
    <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" xmlns:ns1="urn:NBWS" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns2="http://xml.apache.org/xml-soap" xmlns:enc="http://www.w3.org/2003/05/soap-encoding">
        <env:Body xmlns:rpc="http://www.w3.org/2003/05/soap-rpc">
            <ns1:getResponse env:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
                <rpc:result>Response</rpc:result>
                <Response xsi:type="enc:Struct">
                    <ResponseStatus xsi:type="xsd:int">1</ResponseStatus>
                    <ResponseMessage xsi:type="xsd:string">
                    </ResponseMessage>
                    <TimeInterval xsi:type="xsd:string">2010-04-01 - 2010-04-30</TimeInterval>
                    <Events enc:itemType="ns2:Map" enc:arraySize="4" xsi:type="enc:Array">
                        <item xsi:type="ns2:Map">
                            <item>
                                <key xsi:type="xsd:string">DateStart</key>
                                <value xsi:type="xsd:string">2010-04-29</value>
                            </item>
                            <item>
                                <key xsi:type="xsd:string">TimeStart</key>
                                <value xsi:type="xsd:string">14:30:00</value>
                            </item>
                            <item>
                                <key xsi:type="xsd:string">DateEnd</key>
                                <value xsi:type="xsd:string">2010-04-29</value>
                            </item>
                            <item>
                                <key xsi:type="xsd:string">TimeEnd</key>
                                <value xsi:type="xsd:string">15:30:00</value>
                            </item>
                            <item>
                                <key xsi:type="xsd:string">ReservationStatus</key>
                                <value xsi:type="xsd:string">3</value>
                            </item>
                        </item>
                        <item xsi:type="ns2:Map">
                            <item>
                                <key xsi:type="xsd:string">DateStart</key>
                                <value xsi:type="xsd:string">2010-04-06</value>
                            </item>
                            <item>
                                <key xsi:type="xsd:string">TimeStart</key>
                                <value xsi:type="xsd:string">12:00:00</value>
                            </item>
                            <item>
                                <key xsi:type="xsd:string">DateEnd</key>
                                <value xsi:type="xsd:string">2010-04-06</value>
                            </item>
                            <item>
                                <key xsi:type="xsd:string">TimeEnd</key>
                                <value xsi:type="xsd:string">13:00:00</value>
                            </item>
                            <item>
                                <key xsi:type="xsd:string">ReservationStatus</key>
                                <value xsi:type="xsd:string">3</value>
                            </item>
                        </item>
                        <item xsi:type="ns2:Map">
                            <item>
                                <key xsi:type="xsd:string">DateStart</key>
                                <value xsi:type="xsd:string">2010-04-13</value>
                            </item>
                            <item>
                                <key xsi:type="xsd:string">TimeStart</key>
                                <value xsi:type="xsd:string">12:00:00</value>
                            </item>
                            <item>
                                <key xsi:type="xsd:string">DateEnd</key>
                                <value xsi:type="xsd:string">2010-04-13</value>
                            </item>
                            <item>
                                <key xsi:type="xsd:string">TimeEnd</key>
                                <value xsi:type="xsd:string">13:00:00</value>
                            </item>
                            <item>
                                <key xsi:type="xsd:string">ReservationStatus</key>
                                <value xsi:type="xsd:string">3</value>
                            </item>
                        </item>
                        <item xsi:type="ns2:Map">
                            <item>
                                <key xsi:type="xsd:string">DateStart</key>
                                <value xsi:type="xsd:string">2010-04-20</value>
                            </item>
                            <item>
                                <key xsi:type="xsd:string">TimeStart</key>
                                <value xsi:type="xsd:string">12:00:00</value>
                            </item>
                            <item>
                                <key xsi:type="xsd:string">DateEnd</key>
                                <value xsi:type="xsd:string">2010-04-20</value>
                            </item>
                            <item>
                                <key xsi:type="xsd:string">TimeEnd</key>
                                <value xsi:type="xsd:string">13:00:00</value>
                            </item>
                            <item>
                                <key xsi:type="xsd:string">ReservationStatus</key>
                                <value xsi:type="xsd:string">3</value>
                            </item>
                        </item>
                    </Events>
                </Response>
            </ns1:getResponse>
        </env:Body>
    </env:Envelope>