Service Provider Basic Operation

API 1.2+

Logging In

Logging in to ClickBook requires a JSON call with BASIC authentication set in the http header. A failed login will return a HTTP 401 response. In the jQuery example below, the variables emailaddress and password are separated by a colon and are base64 encoded (the base64 plugin is required):

$.ajax({
	async: true,
	url : 'https://www.clickbook.net/auth/auth.nsf/LoginOK?Open&cacheHack=' + Math.random(),
	dataType : 'json',
	beforeSend : function(xhr) {
	xhr.setRequestHeader("Authorization", "Basic " + $.base64.encode (emailaddress + ":" + password));
},
error: function(xmlHttpResponse, ajaxOptions, thrownError) {
	if (xmlHttpResponse.responseText.indexOf ("You are locked out") > -1) {
		alert (xmlHttpResponse.responseText);
	} else {
		//most likely a 401 error (not authorized).  We could test for this condition if we wish.
		alert("Sign-In failed.  Please try again.");	
	}
	return false;
},
success: function(model) {
	//gmodel.user contains the full canonical name of the user
	//model.usercn contains the Full common name of the user (Firstname[space]Lastname)
}
});

Logging out

//Simple signout using http redirection to new url
function signout(nextUrl) {
 window.location = "http://www.clickbook.net/names.nsf?Logout&RedirectTo=" + nextUrl
}

Registering Client Files (end-customer records)

Submitting form information to ClickBook is specified and regulated by Group Schemas. See the Group Schema documentation for more information. The example below uses the Group Schema "NewClientFile".

To register new clients as Client Files within the context of a Service Provider Account, the user needs to be logged in. Creating a Client File returns a ClientFileID in the INFO item, which can be used later as context when submitting a booking request. For a new client, the GroupName item is set to NewClientFile.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope>
  <soapenv:Header/>
  <soapenv:Body>
    <urn:SETUSERFIELDS>
      <APIKEY>?</APIKEY>
      <GROUPNAME>NewClientFile</GROUPNAME>
      <CONTEXTFORM></CONTEXTFORM>
      <CONTEXTID></CONTEXTID>
      <VALIDATIONMODE></VALIDATIONMODE>
      <FIELDINFO>
        <ITEM>
          <FIELDNAME>inp-firstname</FIELDNAME>
          <FIELDVALUE>Tester</FIELDVALUE>
        </ITEM>
        <ITEM>
          <FIELDNAME>inp-lastname</FIELDNAME>
          <FIELDVALUE>User1</FIELDVALUE>
        </ITEM>
        <ITEM>
          <FIELDNAME>inp-telfixed</FIELDNAME>
          <FIELDVALUE>55555555</FIELDVALUE>
        </ITEM>
        <ITEM>
          <FIELDNAME>inp-telmobile</FIELDNAME>
          <FIELDVALUE>0403392220</FIELDVALUE>
        </ITEM>
        <ITEM>
          <FIELDNAME>inp-newemailaddress1</FIELDNAME>
          <FIELDVALUE></FIELDVALUE>
        </ITEM>
        <ITEM>
          <FIELDNAME>inp-newemailaddress2</FIELDNAME>
          <FIELDVALUE></FIELDVALUE>
        </ITEM>
      </FIELDINFO>
    </urn:SETUSERFIELDS>
  </soapenv:Body>
</soapenv:Envelope>

Response:

The new ClientFileID is returned in "INFO" if there were no validation errors.

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope>
  <soapenv:Body>
    <ns1:SETUSERFIELDSResponse xmlns:ns1="urn:DefaultNamespace">
      <SETUSERFIELDSReturn>
        <ERRORCOUNT>0</ERRORCOUNT>
        <INFO>E42CE640CA1FA88CCA257CAC0035E44D</INFO>
        <UIMESSAGE></UIMESSAGE>
        <FORCESIGNOUT></FORCESIGNOUT>
      </SETUSERFIELDSReturn>
    </ns1:SETUSERFIELDSResponse>
  </soapenv:Body>
</soapenv:Envelope>

Submitting a booking request

To submit a booking request with a Client File ID as context, the CONTEXTFORM parameter is set to "ClientFile", and the CONTEXTID is set to the ClientFileID.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope>
  <soapenv:Header/>
  <soapenv:Body>
    <urn:SETAPPTREQUEST>
      <APIKEY>?</APIKEY>
      <COMPANYID>7D9A05514936638BCA2578DF00269293</COMPANYID>
      <SERVICEID>PPPP-9DVF42</SERVICEID>
      <RESOURCEID>F6C9F456BF13790CCA257B940021ADDD</RESOURCEID>
      <CONTEXTFORM>ClientFile</CONTEXTFORM>
      <CONTEXTID>424F2FEEB1D348B1CA257C7500728683</CONTEXTID>
      <YEARNUMBER>2014</YEARNUMBER>
      <MONTHNUMBER>3</MONTHNUMBER>
      <DAYNUMBER>31</DAYNUMBER>
      <TIMEAMPM>1:30 PM</TIMEAMPM>
      <USERCOMMENT>
        <![CDATA[This is a test comment.]]>
      </USERCOMMENT>
        <INTERNALNOTE>
          <![CDATA[This is an internal note - visible to staff only.]]>
        </INTERNALNOTE>
          <NOTESTORE>true</NOTESTORE>
          <NOTEIMPORTANT>true</NOTEIMPORTANT>
        </urn:SETAPPTREQUEST>
      </soapenv:Body>
    </soapenv:Envelope>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope>
  <soapenv:Body>
    <ns1:SETAPPTREQUESTResponse xmlns:ns1="urn:DefaultNamespace">
      <SETAPPTREQUESTReturn>
        <STATUSCODE>3</STATUSCODE>
        <STATUSDESC>Booking confirmation Is pending receipt of payment</STATUSDESC>
        <USERCALLBACKURL></USERCALLBACKURL>
        <CALLBACKDATA></CALLBACKDATA>
        <REDIRECTURL></REDIRECTURL>
        <REDIRECTTITLE></REDIRECTTITLE>
        <SPAMWARN></SPAMWARN>
        <BOOKINGID>6DAC529FCEB456ADCA257CAC0036AB93</BOOKINGID>
      </SETAPPTREQUESTReturn>
    </ns1:SETAPPTREQUESTResponse>
  </soapenv:Body>
</soapenv:Envelope>

Notes

Where no API Key is specified in the examples, this means that Login is required for these operations.
Prior to submitting a booking request, a user interface must be implemented for the selection of location, service, service provider and date/time.
For status codes and full example of a typical booking workflow, please see the API Guide.