webBooks APIs

From Cliquesoft
Revision as of 08:57, 24 March 2015 by Digitalpipe (Talk | contribs)

Jump to: navigation, search

Below you will see a list of each official module produced by Cliquesoft. Clicking on a module name from the list will take you to the appropriate section that outlines the various API's used by the modules' graphical frontend. It is important to note that the 'username' and 'SID' (security identifier provided after a successful login) values should be passed for every communication with the server, even if they are null values (which will default to the 'guest' account and may prevent access). Any questions, comments, or concerns should be directed to our staff. For any modifications to the API's, please use the 'Issues' link on our website so that our users can participate in that process.

The below key elaborates on the requested values:

  • {...|...|...} - specifies that the value can be one of the items in the list
  • (...........) - specifies a description for the what the value needs to be
  • [...........] - specifies that the value is optional
  • /.........../ - specifies the use of a variable value



Login and Logout

To login and out of the software, the below two calls can be made.


Logging into the software

To log into the software, the below parameters will need to be passed via a GET request to the 'modules/webbooks/_login.php' file. It is important to note that there is not a request to load the screen content so you must create it.

action=login
target=username
username=(the username for the account)
password=(the password for the account)
txtCaptcha=[the captcha if they are enabled]

This will return all the information in the following XML:

   <s><msg>...</msg><data SID="STRING" username="STRING" decrypt="STRING" name="STRING"></data></s>

   OR

   <f><msg>...</msg></f>


Logging out of the software

To log out of the software, the below parameters will need to be passed via a GET request to the 'modules/webbooks/_logout.php' file:

action=logout
target=username
username=(the username for the account)
SID=(the security identifier for the account)

This will return all the information in the following XML:

   <s></s>

   OR

   <f><msg>...</msg></f>



Dashboard

In order to process any of these API's, all requests should be directed to the 'modules/webbooks/webbooks.php' file. The type of request will be specified per section below.


Load the interface

Since the default themed dashboard is hard coded within the 'themes/default/webbooks.html' file, there isn't a request to load the interface. This will also be the case if any other theme is used.


Populate the form

To populate all the various values of the interface form objects, the below parameters will need to be passed via a GET request:

action=init
target=values
username=(the username for the account)
SID=(the security identifier for the account)

This will return all the information in the following XML layout:

   <system socialURI="STRING" />
   <user id="INTEGER" name="STRING" />
   <employees>
      <employee id="INTEGER" name="STRING" status="{in|out|delayed}" avail="{yes|no|break|meeting}" />

      ...repeated for each employee in the company...
   </employees>
   <jobs>
      <job id="INTEGER" module="STRING" customerID="INTEGER" customerName="STRING" required="DATE" />

      ...repeated for each job associated with the employee...
   </jobs>
   <groups>
      <group id="INTEGER" name="STRING" icon="STRING">
         <module id="INTEGER" name="STRING" icon="STRING" />

         ...repeated for each module within the group...
      </group>

      ...repeated for each defined group on the dashboard...
   </groups>


Change the interface

To change between the dashboard and the social interface, the below parameters will need to be passed via a GET request:

action=check
target=provider
username=(the username for the account)
SID=(the security identifier for the account)
uri=(the URI of the email provider such as 'http://www.gmail.com')

When changing to the social interface, the server-side script will perform a quick test to see if the provider allows for an embedded version of their service and returns the following XML:

   <s></s>

   OR

   <f><msg>The service provider for your social interaction does not allow embedding in an iframe.</msg></f>


Update 'Employee' tab data

To update the data on the 'Employees' tab, the below parameters will need to be passed via a GET request:

action=update
target=employees
username=(the username for the account)
SID=(the security identifier for the account)

This will return all the information in the following XML layout:

   <employees>
      <employee id="INTEGER" name="STRING" status="{in|out|delayed}" avail="{yes|no|break|meeting}" />

      ...repeated for each employee of the company...
   </employees>
   <jobs>
      <job id="INTEGER" module="STRING" customerID="INTEGER" customerName="STRING" required="DATE" />

      ...repeated for each job assigned to the employee...
   </jobs>


Update user status

To update the users working status, the below parameters will need to be passed via a GET request:

action=update
target=status
username=(the username for the account)
SID=(the security identifier for the account)
status={in|out|pto|sick|delayed}

This will return all the information in the following XML:

   <s><msg>Your status has been updated successfully!</msg><data status="{in|out|pto|sick|delayed}" /></s>

   OR

   <f><msg>There was an error processing your request and our staff has been notified.  Please try again in a few minutes.</msg><data prior="{yes|no|break|meeting}" /></f>


Update user availability

To update the users working availability, the below parameters will need to be passed via a GET request:

action=update
target=status
username=(the username for the account)
SID=(the security identifier for the account)
avail={yes|no|break|meeting}

This will return all the information in the following XML:

   <s><msg>Your status has been updated successfully!</msg><data status="{yes|no|break|meeting}" /></s>

   OR

   <f><msg>There was an error processing your request and our staff has been notified.  Please try again in a few minutes.</msg><data prior="{yes|no|break|meeting}" /></f>



System Configuration

In order to process any of these API's, all requests should be directed to the 'modules/webbooks/system_configuration.php' file. The type of request will be specified per section below.


Load the interface

To load the modules default HTML interface (themes/default/webbooks.system_configuration.html), the below parameters should be passed to the appropriate php file via a GET request. Loading an alternative screen relies on the symlinks set in the users data directory (e.g. data/_guest/_theme/{images|layout|styles}).

action=init
target=screen
username=(the username for the account)
SID=(the security identifier for the account)

This will return the raw contents as it is found in the file, replacing all occurrences of the variable ${UN} anywhere.


Populate the form

To populate all the various values of the interface form objects, the below parameters will need to be passed via a GET request:

action=init
target=values
username=(the username for the account)
SID=(the security identifier for the account)

This will return all the information in the following XML layout:

   <general>
      <admin id="INTEGER" name="STRING" type="{provider|vendor|employee}" email="STRING" phone="INTEGER" ext="INTEGER" mobile="INTEGER" sms="{0|1}" mail="{0|1}" />
      <system socialURI="STRING" [accessURI="STRING" logins="INTEGER" support="STRING" balance="DECIMAL" prefix="STRING"] />
   </general>

The <system> tag has only one mandatory value (socialURI) when the software is not working in a HOSTED mode, otherwise all the other values will be returned as well.

Business Configuration

Employees

Accounting

Asset Management

Customer Accounts

Inventory

Quotes & Invoices

Work Orders

In order to process any of these API's, all requests should be directed to the 'modules/webbooks/system_configuration.php' file. The type of request will be specified per section below.



Common Calls

The below calls are common in various modules within the program.


Loading a contact

To load a contact within the module, the below parameters will need to be passed via a GET request. It is important to note that the server-side script to call needs to be the one for the module.

action=load
target=contact
username=(the username for the account)
SID=(the security identifier for the account)
acctID=(the integer ID of the contact)

This will return all the information in the following XML:

   <contacts>
      <contact id="INTEGER" type="{vendor|provider|employee}" rowID="INTEGER" OPoID="STRING" name="STRING" email="STRING" phone="INTEGER" ext="INTEGER" mobile="INTEGER" sms="{0|1}" mail="{0|1}" title="STRING" />

      ...repeat for each associated contact...
   </contacts>


Creating a contact

To create a contact within the module, the below parameters will need to be passed via a POST request. It is important to note that the server-side script to call needs to be the one for the module.

action=new
target=contact
username=(the username for the account)
SID=(the security identifier for the account)
type={vendor|provider|employee}
id=(the ID of the contact)
s{Location|Vendor|Provider|Customer}ContactOPoID_/module name/=[for future use, can be null]
s{Location|Vendor|Provider|Customer}Contact_/module name/=(the name of the contact)
s{Location|Vendor|Provider|Customer}ContactEmail_/module name/=[the email address of the contact]
n{Location|Vendor|Provider|Customer}ContactPhone_/module name/=[the work phone number of the contact]
n{Location|Vendor|Provider|Customer}ContactExt_/module name/=[the work phone extension of the contact]
n{Location|Vendor|Provider|Customer}ContactMobile_/module name/=[the mobile phone number of the contact]
b{Location|Vendor|Provider|Customer}ContactMobileSMS_/module name/=(the mobile phone SMS capabilities of the contact)
b{Location|Vendor|Provider|Customer}ContactMobileEmail_/module name/=(the mobile phone email capabilities of the contact)
s{Location|Vendor|Provider|Customer}ContactTitle_/module name/=[the job title of the contact]

This will return all the information in the following XML:

   <s><msg>The contact has been created successfully!</msg><data id="INTEGER"></data></s>

   OR

   <f><msg>...</msg></f>


Deleting a contact

To delete a contact within the module, the below parameters will need to be passed via a GET request. It is important to note that the server-side script to call needs to be the one for the module.

action=delete
target=contact
username=(the username for the account)
SID=(the security identifier for the account)
acctID=(the ID of the contact being deleted)

This will return all the information in the following XML:

   <s><msg>The contact has been deleted successfully!</msg></s>

   OR

   <f><msg>...</msg></f>


Updating a contact

To update a contact within the module, the below parameters will need to be passed via a POST request. It is important to note that the server-side script to call needs to be the one for the module.

action=update
target=contact
username=(the username for the account)
SID=(the security identifier for the account)
type={vendor|provider|employee}
n{Location|Vendor|Provider|Customer}ContactList_/module name/=(the ID of the contact)
s{Location|Vendor|Provider|Customer}ContactOPoID_/module name/=[for future use, can be null]
s{Location|Vendor|Provider|Customer}Contact_/module name/=(the name of the contact)
s{Location|Vendor|Provider|Customer}ContactEmail_/module name/=[the email address of the contact]
n{Location|Vendor|Provider|Customer}ContactPhone_/module name/=[the work phone number of the contact]
n{Location|Vendor|Provider|Customer}ContactExt_/module name/=[the work phone extension of the contact]
n{Location|Vendor|Provider|Customer}ContactMobile_/module name/=[the mobile phone number of the contact]
b{Location|Vendor|Provider|Customer}ContactMobileSMS_/module name/=(the mobile phone SMS capabilities of the contact)
b{Location|Vendor|Provider|Customer}ContactMobileEmail_/module name/=(the mobile phone email capabilities of the contact)
s{Location|Vendor|Provider|Customer}ContactTitle_/module name/=[the job title of the contact]

This will return all the information in the following XML:

   <s><msg>The contact has been updated successfully!</msg></s>

   OR

   <f><msg>...</msg></f>


Loading a freight account

To load a freight account within the module, the below parameters will need to be passed via a GET request. It is important to note that the server-side script to call needs to be the one for the module.

action=load
target=freight
username=(the username for the account)
SID=(the security identifier for the account)
decrypt=(the decryption string for the account)
id=(the integer ID of the freight account)

This will return all the information in the following XML:

   <freights>
      <freight id="INTEGER" name="STRING" account="STRING" />

      ...repeat for each freight account...
   </freights>


Creating a freight account

To create a freight account within the module, the below parameters will need to be passed via a POST request. It is important to note that the server-side script to call needs to be the one for the module.

action=new
target=freight
username=(the username for the account)
SID=(the security identifier for the account)
decrypt=(the decryption string for the account)
type={customer|business}
id=(the ID of the freight account)
s{Customer|Business}ShipName_/module name/=(the name of the freight company)
s{Customer|Business}ShipAccount_/module name/=(the account number of the freight company)

This will return all the information in the following XML:

   <s><msg>The freight account has been created successfully!</msg><data id="INTEGER"></data></s>

   OR

   <f><msg>...</msg></f>


Deleting a freight account

To delete a freight account within the module, the below parameters will need to be passed via a GET request. It is important to note that the server-side script to call needs to be the one for the module.

action=delete
target=freight
username=(the username for the account)
SID=(the security identifier for the account)
id=(the ID of the freight account)

This will return all the information in the following XML:

   <s><msg>The freight account has been deleted successfully!</msg></s>

   OR

   <f><msg>...</msg></f>


Updating a freight account

To update a freight account within the module, the below parameters will need to be passed via a POST request. It is important to note that the server-side script to call needs to be the one for the module.

action=update
target=freight
username=(the username for the account)
SID=(the security identifier for the account)
decrypt=(the decryption string for the account)
type={customer|business}
n{Customer|Business}ShipList_/module name/=(the ID of the freight account)
s{Customer|Business}ShipName_/module name/=(the name of the freight company)
s{Customer|Business}ShipAccount_/module name/=(the account number of the freight company)

This will return all the information in the following XML:

   <s><msg>The freight account has been updated successfully!</msg></s>

   OR

   <f><msg>...</msg></f>