SimplyBook.me

Company administration service methods: Difference between revisions

← Older editNewer edit →
VisualWikitext
No edit summary
No edit summary
Line 84: Line 84:


Using Simplybook API methods require an authentification. To authorize in Simplybook API you need to get an access key — access-token. In order to get this access-token you should call the JSON-RPC method <code>[[Authentication#getUserToken|getUserToken]]</code> API method on https://user-api.simplybook.me/login service passing your personal API-key. You can copy your API-key at admin interface: go to the 'Plugins' link and select [[Plugins#API|API plugin]] 'Settings'.  
Using Simplybook API methods require an authentification. To authorize in Simplybook API you need to get an access key — access-token. In order to get this access-token you should call the JSON-RPC method <code>[[Authentication#getUserToken|getUserToken]]</code> API method on https://user-api.simplybook.me/login service passing your personal API-key. You can copy your API-key at admin interface: go to the 'Plugins' link and select [[Plugins#API|API plugin]] 'Settings'.  
== Methods ==


== Methods ==
== Methods ==
Line 99: Line 101:
Adds new client with specified data. You can specify name, email, phone, address1, address2, city, zip,
Adds new client with specified data. You can specify name, email, phone, address1, address2, city, zip,
country_id. If client record with specified data exists  method will return an id of this record. Otherwise data
country_id. If client record with specified data exists  method will return an id of this record. Otherwise data
will be stored to database and method will return an id of newly created record. NOTE: name is mandatory field.
will be stored to database and method will return an id of newly created record. NOTE: name is mandatory field.Also email, phone number or both of them can be mandatory fields. You should call
 
Also email, phone number or both of them can be mandatory fields. You should call
<code>getCompanyParam('require_fields')</code> method to check which fields are required.
<code>getCompanyParam('require_fields')</code> method to check which fields are required.


Line 190: Line 190:


* [http://wiki.simplybook.me/index.php/Settings#Timeframe Timeframe information]
* [http://wiki.simplybook.me/index.php/Settings#Timeframe Timeframe information]
----
=== calculateEndTime ===
<code>calculateEndTime($startDateTime, $eventId, $unitId)</code>
Parameters:
* '''$startDateTime''' String a date and time string in format 'Y-m-d H:i:s', eg. '2001-10-02 13:30:00'.
* '''$eventId''' Integer
* '''$unitId''' Integer
Returns String|Boolean.
Returns end datetime if booking is available, else return false


----
----
Line 223: Line 240:
Cancels booking. Returns true on success. Returns an error with code -32080 (Appointment couldn't be found) if
Cancels booking. Returns true on success. Returns an error with code -32080 (Appointment couldn't be found) if
no booking with specified id were found.
no booking with specified id were found.
----
=== createBatch ===
<code>createBatch()</code>
No arguments.
Returns Integer.
Creates new booking batch record. Returns newly created batch id. You can use this id in <code>[[#book|book]]</code>
API method.




Line 279: Line 309:


Edits client's record. See <code>[[#addClient|addClient]]</code> method description for list of available fields.Method returns an id of client's record.
Edits client's record. See <code>[[#addClient|addClient]]</code> method description for list of available fields.Method returns an id of client's record.
----
=== filterAvailableUnits ===
<code>filterAvailableUnits($eventId, $dateTime, $unitIds, $count)</code>
Parameters:
* '''$eventId''' Integer
* '''$dateTime''' String a date and time string in format 'Y-m-d H:i:s'
* '''$unitIds''' 
* '''$count''' Integer
Returns Array.
Returns list of available unit ids for specified date and service from provided $unitIds list.You can use this method with location plugin.
Returns empty array if all units are not allowed.
Eg.: <code>[1, 2, 3]</code>
----
=== getAdditionalFields ===
<code>getAdditionalFields($eventId)</code>
Parameters:
* '''$eventId''' Integer
Returns Array.
Return additional fields for certain event if [[Plugins#Additional_fields|Additional fields plugin]] is
activated. Returns empty array otherwise. Call <code>[[#isPluginActivated|isPluginActivated('event_field')]]</code>
API method to check if 'event_field' plugin activated.
----
=== getAnyUnitData ===
<code>getAnyUnitData()</code>
No arguments.
Returns Object|null.
Returns information about [[Plugins#Any_Employee_selector|Any Employee selector plugin]] configuration. Returns
null if plugin not enabled.Example:
  {
    "description" : "Select this option, if you want to find an available time with any of the employees",
    "hide_other_units" : 1, // 1 or 0
    "image" : null,
    "name" : "Any employee",
    "picture_path" : null,
    "random_selection" : 0 // 1 or 0
  }
----
=== getAvailableTimeIntervals ===
<code>getAvailableTimeIntervals($dateFrom, $dateTo, $eventId, $unitId, $count)</code>
Parameters:
* '''$dateFrom''' String
* '''$dateTo''' String
* '''$eventId''' Integer
* '''$unitId''' Mixed can be Integer or Array of Integers
* '''$count''' Integer
Returns Object.
Returns available time intervals for all service providers for given period, taking into account breaktimes, start and end working time
Eg.: <code>{['2016-03-04': ['1': [['09:00:00','09:30:00'], ['11:15:00','14:45:00']] , ...], ...]}</code>
----
=== getAvailableUnits ===
<code>getAvailableUnits($eventId, $dateTime, $count)</code>
Parameters:
* '''$eventId''' Integer
* '''$dateTime''' String a date and time string in format 'Y-m-d H:i:s'
* '''$count''' Integer
Returns Array.
Returns list of available unit ids for specified date and service or empty array if all units are not allowed.Eg.: <code>[1, 2, 3]</code>




Line 298: Line 423:
"create", "cancel" or "nopayment_cancel". If <code>"user_id"</code> not specified then bookings where created or
"create", "cancel" or "nopayment_cancel". If <code>"user_id"</code> not specified then bookings where created or
cancelled by admin or employee. Data with type <code>"nopayment_cancel"</code> represents bookings cancelled
cancelled by admin or employee. Data with type <code>"nopayment_cancel"</code> represents bookings cancelled
automatically by system.
automatically by system.Example:
 
Example:
   3 bookings where created by admin or employee and 2 bookings where automatically cancelled by system.
   3 bookings where created by admin or employee and 2 bookings where automatically cancelled by system.
   [{
   [{
Line 384: Line 507:
Return bookings count and revenue value for each date in specified period. Data grouped by unit id and
Return bookings count and revenue value for each date in specified period. Data grouped by unit id and
represented as array with bookings count at index 0 and revenue amount at index 1. You can filter data either
represented as array with bookings count at index 0 and revenue amount at index 1. You can filter data either
by unit or by service. Set <code>$dateStart</code> and <code>$dateEnd</code> to null to get data for current week.
by unit or by service. Set <code>$dateStart</code> and <code>$dateEnd</code> to null to get data for current week.Example:
 
Example:
   ['2015-11-12' : {
   ['2015-11-12' : {
     3 : [
     3 : [
Line 407: Line 528:


Returns statistic about bookings count grouped by 'day', 'week' or 'month'. A time period depends on selected
Returns statistic about bookings count grouped by 'day', 'week' or 'month'. A time period depends on selected
grouping parameter:
grouping parameter:* for 'day' methods returns statistics for last 31 days
 
* for 'day' methods returns statistics for last 31 days
* for 'week' methods returns data last 10 weeks period
* for 'week' methods returns data last 10 weeks period
* for 'month' time period is last 12 months
* for 'month' time period is last 12 months
Line 426: Line 545:
Returns Array.
Returns Array.


Returns list of bookings filtered by given params. Filter params represented as object with following fields:
Returns list of bookings filtered by given params. Filter params represented as object with following fields:* '''date_from''' a date of booking in string format 'Y-m-d'
 
* '''date_from''' a date of booking in string format 'Y-m-d'
* '''time_from''' a time string in format 'H:i:s'
* '''time_from''' a time string in format 'H:i:s'
* '''date_to''' a date string in format 'Y-m-d'
* '''date_to''' a date string in format 'Y-m-d'
Line 473: Line 590:


Returns list of bookings filtered by given params
Returns list of bookings filtered by given params
----
=== getCategoriesList ===
<code>getCategoriesList($isPublic)</code>
Parameters:
* '''$isPublic''' Boolean
Returns Array.
Returns company categories list if [[Plugins#Service categories|Service categories plugin]] is activated. Returns
an error with code -32001 if plugin is not activated. Use <code>[[#isPluginActivated|isPluginActivated('event_category')]]</code>
API method to check if plugin activated.




Line 536: Line 670:


Returns company's currency as three chars code (ISO 4217).
Returns company's currency as three chars code (ISO 4217).
----
=== getCompanyInfo ===
<code>getCompanyInfo()</code>
No arguments.
Returns Object.
Returns an object with detailed information about company. See [[#getCompanyInfo response|example of response]].
----
=== getCompanyParam ===
<code>getCompanyParam($key)</code>
Parameters:
* '''$key''' String
Returns mixed.
Returns company config value for key. A different set of keys available for public API and for company
administration API. Method return 'invalid params' error (code -32602) in case if access to specified key not
allowed. See [[#Company_params|list of available keys]].
----
=== getCompanyParams ===
<code>getCompanyParams($keys)</code>
Parameters:
* '''$keys''' Array
Returns Array.
Returns company config values for keys. A different set of keys available for public API and for company
administration API. Method return 'invalid params' error (code -32602) in case if access to specified key not
allowed. See [[#Company_params|list of available keys]].For non-existent and not-allowed params it will return false as result
----
=== getCompanyTimezoneOffset ===
<code>getCompanyTimezoneOffset()</code>
No arguments.
Returns array.
Returns company timezone offset and company timezone




Line 548: Line 740:


Get list of all countries
Get list of all countries
----
=== getCountryPhoneCodes ===
<code>getCountryPhoneCodes()</code>
No arguments.
Returns Array.
Returns country phone code list




Line 559: Line 763:
Returns Array.
Returns Array.


Returns all information about current tariff (subscription). For example:
Returns all information about current tariff (subscription). For example:{
 
  {
     "name" : "gold",
     "name" : "gold",
     "expire_date" : "2016-02-11 12:32:00",
     "expire_date" : "2016-02-11 12:32:00",
Line 579: Line 781:


Returns current logged user info
Returns current logged user info
----
=== getEventList ===
<code>getEventList($isVisibleOnly, $asArray)</code>
Parameters:
* '''$isVisibleOnly''' Boolean
* '''$asArray''' Boolean
Returns Array.
Returns company's events list. If <code>$asArray</code> is false then method returns a map with event id as key
and details object as value. If parameter set to true then method returns a list sorted by 'position' property of
event's details object.




Line 597: Line 817:


Get list of feedbacks
Get list of feedbacks
----
=== getFirstWorkingDay ===
<code>getFirstWorkingDay($unitId)</code>
Parameters:
* '''$unitId''' Integer
Returns String.
Returns first working date for unit




Line 620: Line 855:
check status of the plugin. Each object of result contains <code>from</code> and <code>to</code> properties with
check status of the plugin. Each object of result contains <code>from</code> and <code>to</code> properties with
datetime string as value. Please note that this method may return not actual data because data synchronization
datetime string as value. Please note that this method may return not actual data because data synchronization
between server and Google Calendar may take some time and synchronized data are cached for 15 minutes.
between server and Google Calendar may take some time and synchronized data are cached for 15 minutes.Example:
 
<code>
Example:
   [
   [
   {"from" : "2016-02-16 13:30:00",
   {"from" : "2016-02-16 13:30:00",
Line 628: Line 862:
     ...
     ...
   ]
   ]
</code>




Line 655: Line 890:


Returns last update datetime
Returns last update datetime
----
=== getLocationsList ===
<code>getLocationsList($isPublic, $asArray)</code>
Parameters:
* '''$isPublic''' Boolean Optional. Default value is '''false'''.
* '''$asArray''' boolean Optional. Default value is '''false'''.
Returns Array.
Returns available locations for company if plugin [[Plugins#Unit location|Unit location plugin]] is activated. Return
an error with code -32001 if plugin is not activated. Use <code>[[#isPluginActivated|isPluginActivated('location')]]</code>
API method to check if plugin activated.This method accepts two boolean flags as parameters. If '''isPublic''' flag is '''true''' then method returns only
public locations. If '''asArray''' flag is '''true''' method returns list of objects. Otherwise method returns
map of objects with object id as key. You can omit both parameters.




Line 667: Line 922:


Returns a list of all plugins associated with company with status.
Returns a list of all plugins associated with company with status.
----
=== getPluginPromoInfoByCode ===
<code>getPluginPromoInfoByCode($code)</code>
Parameters:
* '''$code''' 
Returns Array.
Returns an object with detailed information about promotion by promotion code. You can get promotion code
using <code>[[Catalogue#getPromotionList|getPromotionList]]</code> API method. If promotion record with specified
code not found then method returns an empty array (an empty object). If [[Plugins#Simply Smart Promotions|Simply Smart Promotions plugin]]
not enabled then method returns an error with code -32001 (Plugin is not activated). Use
<code>[[#isPluginActivated|isPluginActivated('promo')]]</code> API method call to check if plugin enabled.See [[#getPromotionList response|example]] of <code>getPromotionList</code> API method response. Please note that
response contains a list of services for wich promotion discount can be applied (<code>service_ids</code> key).
----
=== getPluginStatuses ===
<code>getPluginStatuses($pluginNames)</code>
Parameters:
* '''$pluginNames''' Array
Returns Array.
Return plugin status true if status active, else false. See [[#Plugin's identifiers|list of available plugin's names]].




Line 737: Line 1,027:


Returns number of clients registrations  by 'day', 'week' or 'month'. A time period depends on selected
Returns number of clients registrations  by 'day', 'week' or 'month'. A time period depends on selected
grouping parameter:
grouping parameter:* for 'day' methods returns statistics for last 31 days
 
* for 'day' methods returns statistics for last 31 days
* for 'week' methods returns data last 10 weeks period
* for 'week' methods returns data last 10 weeks period
* for 'month' time period is last 12 months
* for 'month' time period is last 12 months
----
=== getReservedTime ===
<code>getReservedTime($from, $to, $eventId, $unitId, $count)</code>
Parameters:
* '''$from''' String
* '''$to''' String
* '''$eventId''' Integer
* '''$unitId''' Integer
* '''$count''' Integer
Returns Object.
Returns map of objects for each day in specified date range. The key of the result mps is a date string. The value
is an array of two objects. Both objects contains list of time slots for type <code>reserved_time</code> and type
<code>not_worked_time</code>. <code>reserved_time</code> type represents time slots working time but already booked
by clients. Nobody knows what kind of data represented by <code>not_worked_time</code> type. Please don't use it.If [[Plugins#Google calendar sync plugin|Google calendar sync plugin]] enabled then object with
<code>reserved_time</code> type will contain not empty list of time slots marked as busy in Google calendar. Call
<code>[[#isPluginActivated|isPluginActivated('google_calendar_export')]]</code> API method to check if Google
calendar sync plugin activated.
Example:
<pre>
  {
    "2016-02-05": [
      {
        "dd": [], // time slots from Google calendar
        "events": [ // reserved time slots
          { "from": "16:00", "to": "16:30" },
          { "from": "16:30", "to": "17:00" },
          ... ],
        "type": "reserved_time",
      },
      {
        "events": [
          { "from": "09:00", "to": "09:30" },
          { "from": "09:30", "to": "10:00" },
          ... ],
        "type": "not_worked_time"
    }],
    ...
  }
</pre>
----
=== getReservedTimeIntervals ===
<code>getReservedTimeIntervals($dateFrom, $dateTo, $eventId, $unitId, $count)</code>
Parameters:
* '''$dateFrom''' String
* '''$dateTo''' String
* '''$eventId''' Integer
* '''$unitId''' Integer|Array
* '''$count''' Integer
Returns Object.
Returns not available time
Eg.: <code>{'2014-05-14': [{'reserved_time': [{'from': '14:00', 'to': '16:30'}], 'type': "reserved_time"}, ...], ...}</code>




Line 757: Line 1,114:


Returns social counters value for your domain
Returns social counters value for your domain
----
=== getStartTimeMatrix ===
<code>getStartTimeMatrix($from, $to, $eventId, $unitId, $count)</code>
Parameters:
* '''$from''' String
* '''$to''' String
* '''$eventId''' Integer
* '''$unitId''' Mixed can be Integer or Array of Integers
* '''$count''' Integer
Returns Object.
Returns available start time, taking into account breaktimes, start and end working time
Eg.: <code>{'2014-05-14': ['09:00:00', ...], ...}</code>
If locations plugin activated for company you should pass a list as $unitID parameter for filter results with
units available only for selected location. See [[Plugins#Unit_location|Unit location]] plugin description for
more details.




Line 769: Line 1,150:


Returns list of available statuses or an empty list if [[Plugins#Status|Status plugin]] not enabled.
Returns list of available statuses or an empty list if [[Plugins#Status|Status plugin]] not enabled.
----
=== getTimeframe ===
<code>getTimeframe()</code>
No arguments.
Returns Integer.
Returns company's timeframe configuration (in minutes). Timeframe can be either 5, 10, 15, 20, 30 or 60 minutes.You can find more details about timeframe [[Settings#Timeframe|here]].
----
=== getTimelineType ===
<code>getTimelineType()</code>
No arguments.
Returns String.
Returns company timeline type




Line 798: Line 1,203:
Returns a list with statistics for services for a period of time. This data contains number of bookings and
Returns a list with statistics for services for a period of time. This data contains number of bookings and
revenues value for each service.
revenues value for each service.
----
=== getUnitList ===
<code>getUnitList($isVisibleOnly, $asArray)</code>
Parameters:
* '''$isVisibleOnly''' Boolean
* '''$asArray''' Boolean
Returns Array.
Returns list of service performers. If <code>$asArray</code> is false then method returns a map with event id as
key and details object as value. If parameter set to true then method returns a list sorted by 'position' property
of event's details object.




Line 849: Line 1,272:
an empty list if plugin not enabled. Use <code>[[#isPluginActivated|isPluginActivated('counter')]]</code> API method
an empty list if plugin not enabled. Use <code>[[#isPluginActivated|isPluginActivated('counter')]]</code> API method
call to check if plugin enabled. Results can be grouped by 'day', 'week' or 'month'. A time period depends on
call to check if plugin enabled. Results can be grouped by 'day', 'week' or 'month'. A time period depends on
selected grouping parameter:
selected grouping parameter:* for 'day' methods returns statistics for last 31 days
 
* for 'day' methods returns statistics for last 31 days
* for 'week' methods returns data last 10 weeks period
* for 'week' methods returns data last 10 weeks period
* for 'month' time period is last 12 months
* for 'month' time period is last 12 months
Line 870: Line 1,291:
Returns warnings for admin
Returns warnings for admin
(sms limit, bookings limit, etc)
(sms limit, bookings limit, etc)
----
=== getWorkCalendar ===
<code>getWorkCalendar($year, $month, $unitId)</code>
Parameters:
* '''$year''' Integer
* '''$month''' Integer
* '''$unitId''' Integer
Returns Object.
Returns company work schedule as array
Eg.: <code>{'2014-05-01': {'from': '09:00:00', 'to': '21:00:00', 'is_day_off': '0'}, '2014-05-02': ...}</code>
----
=== getWorkDaysInfo ===
<code>getWorkDaysInfo($from, $to, $unitId, $eventId, $count)</code>
Parameters:
* '''$from''' String
* '''$to''' String
* '''$unitId''' Integer (optional)
* '''$eventId''' Integer (optional)
* '''$count''' Integer (optional)
Returns Object.
Returns an information about working hours and break times for specified service and performer for a period
between two dates. If only service specified then information about performer (or performers) will be taken from
service configuration. Method returns a list of objects for each date in specified period. Count of objects in
list depends on break times. For example if performer works from 9:00 till 19:00 with one hour break at 13:00 method
returns:<pre>
  {'2014-05-14' : [
    {'from': '09:00:00', 'to': '13:00:00'},
    {'from': '14:00:00', 'to': '19:00:00'}
  ] }
</pre>
Warning! Method can return a time string '24:00:00' as right edge of time range. This happens in case if time
range finishes on midnight.




Line 903: Line 1,373:


Return workload data for units in period of time. Workload for each unit represented as array with work hours
Return workload data for units in period of time. Workload for each unit represented as array with work hours
at index 0, confirmed booking hours as load at index 1 and cancelled bookings hours at index 2.
at index 0, confirmed booking hours as load at index 1 and cancelled bookings hours at index 2.Example:
 
Example:
   ['2015-10-21' : {
   ['2015-10-21' : {
     5 : [
     5 : [
Line 912: Line 1,380:
       0  // cancelled bookings hours
       0  // cancelled bookings hours
   ] }]
   ] }]
----
=== isPluginActivated ===
<code>isPluginActivated($pluginName)</code>
Parameters:
* '''$pluginName''' String
Returns Boolean.
Return plugin status true if status active, else false. <var>$pluginName</var> parameter is a plugin identifier.See [[Plugins|plugins]] page for full plugins description. See [[#Plugin's identifiers|list of available plugin's names]].




Retrieved from "https://help.simplybook.me/index.php?title=Company_administration_service_methods"