9,514
edits
Changes
From SimplyBook.me
Company administration service methods (view source)
Revision as of 14:22, 29 April 2016
, 8 years agono edit summary
}
}
</pre>
</pre>
Example of request with error response:
Example of request with error response:
===Authentication===
===Authentication===
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 ==
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.Also email, phone number or both of them can be mandatory fields. You should call
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
<code>getCompanyParam('require_fields')</code> method to check which fields are required.
<code>getCompanyParam('require_fields')</code> method to check which fields are required.
specify either <code>count</code> more then 1 or valid <code>batchId</code> (only one parameter can be
specify either <code>count</code> more then 1 or valid <code>batchId</code> (only one parameter can be
specified). You should specify an <code>$additionalFields</code> parameter if service requires some additional
specified). You should specify an <code>$additionalFields</code> parameter if service requires some additional
fields (see [[Plugins#Additional fields|Additional fields plugin]]). To create a booking with promo code you
fields (see [[Plugins#Additional fields|Additional fields plugin]]).To create a booking with promo code you should pass it as additional field. For example: <code>{"promocode": "some code"}</code>
should pass it as additional field. For example: <code>{"name": "promocode", "value": "some code", "type": "text"}</code>See [[#book response|example]] of <code>book</code> API method response.
If [[Plugins#Unit location|Unit location]] enabled you need to pass locations ID parameter as additional field
<code>location_id</code>. For example: <code>{"location_id": "1"}</code>. Use <code>[[#isPluginActivated|isPluginActivated('location')]]</code>
to check if plugin active and <code>[[#getLocationsList|getLocationsList()]]</code> method to get list of
available locations.
See [[#book response|example]] of <code>book</code> API method response.
See also:
See also:
* [http://wiki.simplybook.me/index.php/Settings#Timeframe Timeframe information]
* [http://wiki.simplybook.me/index.php/Settings#Timeframe Timeframe information]
----
----
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.
----
----
=== getAdditionalFields ===
=== getBookingCancellationsInfo ===
<code>getAdditionalFields($eventId)</code>
<code>getBookingCancellationsInfo($dateStart, $dateEnd)</code>
Parameters:
Parameters:
* '''$eventId''' Integer
* '''$dateStart''' String a date string in format 'Y-m-d'. Pass null to get data from first day of current week.
* '''$dateEnd''' String a date string in format 'Y-m-d'. Pass null to get data filtered to last day of current week.
Returns Array.
Returns Array.
Returns statistics about created bookings and cancellations for a time period. Data presented as array of hashes for
each type of operation (created or cancelled booking) groped by clients. <code>"type"</code> field can be either
"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
automatically by system.
Example:
3 bookings where created by admin or employee and 2 bookings where automatically cancelled by system.
[{
"cnt" : 3,
"firstname" : null,
"lastname" : null,
"login" : null,
"type" : "create",
"user_id"" : null
}, {
"cnt" : 2,
"firstname" : null,
"lastname" : null,
"login" : null,
"type" : "nopayment_cancel",
"user_id"" : null
}]
----
----
=== getAnyUnitData ===
=== getBookingComment ===
<code>getBookingComment($id)</code>
Parameters:
* '''$id''' Integer
Returns Object|null.
Returns String.
Returns information about [[Plugins#Any_Employee_selector|Any Employee selector plugin]] configuration. Returns
Returns booking comment
----
----
=== getAvailableUnits ===
=== getBookingDetails ===
<code>getAvailableUnits($eventId, $dateTime, $count)</code>
<code>getBookingDetails($id)</code>
Parameters:
Parameters:
* '''$eventId''' Integer
* '''$id''' integer booking id
Returns Array.
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>
Returns detailed bookings object by booking id. See [[#getBookingDetails_response|response example]].
----
----
=== getBookingCancellationsInfo ===
=== getBookingLimitUnavailableTimeInterval ===
<code>getBookingCancellationsInfo($dateStart, $dateEnd)</code>
<code>getBookingLimitUnavailableTimeInterval($startDateTime, $endDateTime, $eventId)</code>
Parameters:
Parameters:
* '''$dateStart''' String a date string in format 'Y-m-d'. Pass null to get data from first day of current week.
* '''$startDateTime''' string a date and time string in format 'Y-m-d H:i:s'
* '''$dateEnd''' String a date string in format 'Y-m-d'. Pass null to get data filtered to last day of current week.
* '''$endDateTime''' string a date and time string in format 'Y-m-d H:i:s'
* '''$eventId''' integer
Returns Array.
Returns Array.
Returns statistics about created bookings and cancellations for a time period. Data presented as array of hashes for
Returns time intervals not available for bookings because of configuration of [[Plugins#Limit bookings|Limit bookings]]
plugin for period of time. Returns empty array if plugin not available.
----
----
=== getBookingComment ===
=== getBookingRevenue ===
<code>getBookingComment($id)</code>
<code>getBookingRevenue($dateStart, $dateEnd, $unitGroupId, $serviceId)</code>
Parameters:
Parameters:
* '''$id''' Integer
* '''$dateStart''' string a date string in format 'Y-m-d'.
* '''$dateEnd''' string a date string in format 'Y-m-d'
* '''$unitGroupId''' integer
* '''$serviceId''' integer
Returns Array.
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
by unit or by service. Set <code>$dateStart</code> and <code>$dateEnd</code> to null to get data for current week.
Example:
['2015-11-12' : {
3 : [
11, // bookings count
128.53 // revenue
]}
----
----
=== getBookingDetails ===
=== getBookingStats ===
<code>getBookingDetails($id)</code>
<code>getBookingStats($groupBy)</code>
Parameters:
Parameters:
* '''$id''' integer booking id
* '''$groupBy''' String either 'day', 'week' or 'month'
Returns Array.
Returns Array.
Returns detailed bookings object by booking id. See [[#getBookingDetails_response|response example]].
Returns statistic about bookings count grouped by 'day', 'week' or 'month'. A time period depends on selected
grouping parameter:
* for 'day' methods returns statistics for last 31 days
* for 'week' methods returns data last 10 weeks period
* for 'month' time period is last 12 months
----
----
=== getBookingLimitUnavailableTimeInterval ===
=== getBookings ===
<code>getBookingLimitUnavailableTimeInterval($startDateTime, $endDateTime, $eventId)</code>
<code>getBookings($params)</code>
Parameters:
Parameters:
* '''$startDateTime''' string a date and time string in format 'Y-m-d H:i:s'
* '''$params'''
Returns Array.
Returns Array.
Returns time intervals not available for bookings because of configuration of [[Plugins#Limit bookings|Limit bookings]]
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'
* '''time_from''' a time string in format 'H:i:s'
* '''date_to''' a date string in format 'Y-m-d'
* '''time_to''' a time string in format 'H:i:s'
* '''created_date_from''' a date string in format 'Y-m-d'
* '''created_date_to''' a date string in format 'Y-m-d'
* '''unit_group_id''' an integer. Use it to get bookings assigned for certain service provider.
* '''event_id''' an integer. Use it to get bookings only for certain service.
* '''is_confirmed''' 1 or 0. If [[Plugins#Approve booking|Approve booking]] plugin enabled then method will return confirmed bookings with approve status 'new'.
* '''client_id''' an integer. Use it to get bookings only for certain client.
* '''order''' string either 'record_date', 'date_start' or 'date_start_asc'. By default used 'date_start' value.
* '''booking_type''' a string. Value of this field depends on Approve booking plugin status.
*: If plugin not active:
** '''all''' for all bookings (default value)
** '''cancelled''' alias to 'is_confirmed' equal to 0
** '''non_cancelled''' alias to 'is_confirmed' equal to 1
*: If plugin active:
** '''all''' for all bookings (default value)
** '''cancelled''' returns bookings with 'is_confirmed' field equals to 0 and approve booking status equals to 'cancelled' (or booking does not have any approve status)
** '''non_cancelled''' returns bookings with either 'is_confirmed' field equals to 1 or approve booking status equals to 'new'
** '''cancelled_by_client''' returns bookings approved by admin but cancelled by client
** '''cancelled_by_admin''' returns bookings cancelled by admin
** '''non_approved_yet''' returns bookings with approve status 'new'
** '''approved''' returns bookings with either 'is_confirmed' field equals to 1 and approve booking status equals to 'approved' (or booking does not have any approve status)
----
Example:
{
=== getBookingRevenue ===
"date_from":"2015-12-29",
"date_to":"2015-12-29",
<code>getBookingRevenue($dateStart, $dateEnd, $unitGroupId, $serviceId)</code>
"booking_type":"cancelled",
"event_id":"5",
"order":"start_date"
}
----
=== getBookingsZapier ===
<code>getBookingsZapier()</code>
No arguments.
Returns Array.
Returns Array.
Returns list of bookings filtered by given params
----
----
=== getBookingStats ===
=== getClient ===
<code>getBookingStats($groupBy)</code>
<code>getClient($clientId)</code>
Parameters:
Parameters:
* '''$groupBy''' String either 'day', 'week' or 'month'
* '''$clientId'''
Returns Array.
Returns Array.
Returns statistic about bookings count grouped by 'day', 'week' or 'month'. A time period depends on selected
Returns client's data object. See <code>[[#addClient|addClient]]</code> API method for list of available fields
of client data object.
----
----
=== getBookings ===
=== getClientComments ===
<code>getBookings($params)</code>
<code>getClientComments($clientId, $shedulerId)</code>
Parameters:
Parameters:
* '''$params'''
* '''$clientId''' Integer
* '''$shedulerId''' Integer
Returns Array.
Returns Array.
Returns list of bookings filtered by given params. Filter params represented as object with following fields:
Returns list of all comments for given client
----
=== getClientList ===
<code>getClientList($searchString, $limit)</code>
Parameters:
* '''$searchString''' String
* '''$limit''' Integer
Returns Array.
Returns list of clients associated with company. You can use either phone number, email address or name as value
for <code>$searchString</code>. Pass an empty string for <code>$searchString</code> and null for <code>$limit</code>
parameters to get all records. See <code>[[#addClient|addClient]]</code> API method for list of available fields
of client data object.
----
----
=== getBookingsZapier ===
=== getCompanyCurrency ===
<code>getBookingsZapier()</code>
<code>getCompanyCurrency()</code>
No arguments.
No arguments.
Returns Array.
Returns String.
Returns list of bookings filtered by given params
Returns company's currency as three chars code (ISO 4217).
----
----
=== getCategoriesList ===
=== getCountryList ===
<code>getCategoriesList($isPublic)</code>
<code>getCountryList()</code>
No arguments.
Returns Array.
Returns Array.
Get list of all countries
----
----
=== getClient ===
=== getCurrentTariffInfo ===
<code>getClient($clientId)</code>
<code>getCurrentTariffInfo()</code>
No arguments.
Returns Array.
Returns Array.
Returns all information about current tariff (subscription). For example:
{
"name" : "gold",
"expire_date" : "2016-02-11 12:32:00",
"rest" : 41, // number of days until subscription expiration
"color" : "#fcb322"
}
----
----
=== getClientComments ===
=== getCurrentUserDetails ===
<code>getClientComments($clientId, $shedulerId)</code>
<code>getCurrentUserDetails()</code>
No arguments.
Returns Array.
Returns Array.
Returns list of all comments for given client
Returns current logged user info
----
----
=== getClientList ===
=== getFeedbacks ===
<code>getClientList($searchString, $limit)</code>
<code>getFeedbacks($approvedOnly, $reviewsOnly, $lastOnly, $limit)</code>
Parameters:
Parameters:
* '''$searchString''' String
* '''$approvedOnly''' Boolean
* '''$reviewsOnly''' Boolean
* '''$lastOnly''' Boolean
* '''$limit''' Integer
* '''$limit''' Integer
Returns Array.
Returns Array.
Get list of feedbacks
----
----
=== getCompanyCurrency ===
=== getGoogleCalendarBusyTime ===
<code>getCompanyCurrency()</code>
<code>getGoogleCalendarBusyTime($startDateTime, $endDateTime, $unitId)</code>
Parameters:
Returns String.
* '''$startDateTime''' string a date and time string in format 'Y-m-d H:i:s'
* '''$endDateTime''' string a date and time string in format 'Y-m-d H:i:s'. You can date string avoiding time in
this parameter. In this case method will use time value '23:59:59'.
* '''$unitId''' integer
Returns Array.
Returns a list of objects represented a time intervals marked as busy in Google Calendar. Each object of result
contains <code>from</code> and <code>to</code> properties with datetime string as value. This method only actual if
[Plugins#Google calendar sync plugin|Google calendar sync plugin] enabled. If plugin not enabled an empty list will
be returned. You should call <code>[[#isPluginActivated|isPluginActivated('google_calendar_export')]]</code> to
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
between server and Google Calendar may take some time and synchronized data are cached for 15 minutes.
Example:
[
{"from" : "2016-02-16 13:30:00",
"to" : "2016-02-16 16:00:00"},
...
]
----
----
=== getCompanyInfo ===
=== getGoogleCalendarBusyTimeAvailableUnits ===
<code>getCompanyInfo()</code>
<code>getGoogleCalendarBusyTimeAvailableUnits()</code>
No arguments.
No arguments.
Returns Object.
Returns Array.
Returns an object with detailed information about company. See [[#getCompanyInfo response|example of response]].
Returns configured unit ids, allowed to sync busy time
----
----
=== getCompanyParam ===
=== getLastNotificationUpdate ===
<code>getCompanyParam($key)</code>
<code>getLastNotificationUpdate($type)</code>
Parameters:
Parameters:
* '''$key''' String
* '''$type''' String
Returns mixed.
Returns String.
Returns company config value for key. A different set of keys available for public API and for company
Returns last update datetime
----
----
=== getCountryList ===
=== getPluginList ===
<code>getCountryList()</code>
<code>getPluginList()</code>
No arguments.
No arguments.
Returns Array.
Returns Array.
Returns a list of all plugins associated with company with status.
----
----
=== getCountryPhoneCodes ===
=== getRecentActions ===
<code>getCountryPhoneCodes()</code>
<code>getRecentActions($lastOnly, $limit)</code>
Parameters:
* '''$lastOnly''' Boolean
* '''$limit''' Integer
Returns Array.
Returns Array.
Returns country phone code list
Returns latest actions
----
----
=== getCurrentTariffInfo ===
=== getRecurringDatetimes ===
<code>getRecurringDatetimes($eventId, $unitId, $date, $time, $recurringData, $endDateTime)</code>
Parameters:
* '''$eventId''' Integer
* '''$unitId''' Integer
* '''$date''' String
* '''$time''' String
* '''$recurringData''' Array
* '''$endDateTime''' String (optional)
Returns Array.
Returns Array.
Get list of dates for recurring booking
----
----
=== getCurrentUserDetails ===
=== getRecurringSettings ===
<code>getRecurringSettings($eventId)</code>
Parameters:
* '''$eventId''' Integer
Returns Array.
Returns Array.
Returns current logged user info
Returns an object with recurring settings for an event. Returns false if specified event does not configured as
recurring.
See also:
* [http://blog.simplybook.me/recurring-and-periodic-bookings/ Recurring services desription]
----
----
=== getEventList ===
=== getRegistrations ===
<code>getEventList($isVisibleOnly, $asArray)</code>
<code>getRegistrations($groupBy)</code>
Parameters:
Parameters:
* '''$isVisibleOnly''' Boolean
* '''$groupBy''' String either 'day', 'week' or 'month'
Returns Array.
Returns Array.
Returns company's events list. If <code>$asArray</code> is false then method returns a map with event id as key
Returns number of clients registrations by 'day', 'week' or 'month'. A time period depends on selected
grouping parameter:
* for 'day' methods returns statistics for last 31 days
* for 'week' methods returns data last 10 weeks period
* for 'month' time period is last 12 months
----
----
=== getFeedbacks ===
=== getSocialCounterStats ===
<code>getFeedbacks($approvedOnly, $reviewsOnly, $lastOnly, $limit)</code>
<code>getSocialCounterStats($provider)</code>
Parameters:
Parameters:
* '''$approvedOnly''' Boolean
* '''$provider''' String
Returns Array.
Returns Integer.
Returns social counters value for your domain
----
----
=== getFirstWorkingDay ===
=== getStatuses ===
<code>getFirstWorkingDay($unitId)</code>
<code>getStatuses()</code>
No arguments.
Returns Array.
Returns list of available statuses or an empty list if [[Plugins#Status|Status plugin]] not enabled.
----
=== getTopPerformers ===
<code>getTopPerformers()</code>
No arguments.
Returns Array.
Returns a list with statistics for performers. This data contains number of bookings and revenues value for each performer.
----
=== getTopServices ===
<code>getTopServices($dateStart, $dateEnd)</code>
Parameters:
* '''$dateStart''' String
* '''$dateEnd''' String
Returns Array.
Returns Array.
Returns configured unit ids, allowed to sync busy time
Returns a list with statistics for services for a period of time. This data contains number of bookings and
revenues value for each service.
----
----
=== getLastNotificationUpdate ===
=== getUnitWorkdayInfo ===
<code>getLastNotificationUpdate($type)</code>
<code>getUnitWorkdayInfo($dateStart, $dateEnd, $unitGroupId)</code>
Parameters:
Parameters:
* '''$type''' String
* '''$dateStart''' string
* '''$dateEnd''' string
* '''$unitGroupId''' integer
Returns String.
Returns Array.
Return workday info (date_start and date_end)
----
----
=== getLocationsList ===
=== getUnitWorkingDurations ===
<code>getLocationsList($isPublic)</code>
<code>getUnitWorkingDurations($dateStart, $dateEnd, $unitGroupId)</code>
Parameters:
Parameters:
* '''$isPublic''' Boolean
* '''$dateStart''' string
* '''$dateEnd''' string
* '''$unitGroupId''' integer
Returns Array.
Returns Array.
Return working durations
----
----
=== getPluginList ===
=== getVisitorStats ===
<code>getPluginList()</code>
<code>getVisitorStats($groupBy)</code>
Parameters:
Returns a list of all plugins associated with company with status.
* '''$groupBy''' String
Returns Array.
Returns statistics about page visits if plugin [[Plugins#Visitor Counter|Visitor Counter plugin]] enabled. Returns
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
selected grouping parameter:
* for 'day' methods returns statistics for last 31 days
* for 'week' methods returns data last 10 weeks period
* for 'month' time period is last 12 months
----
----
=== getPluginPromoInfoByCode ===
=== getWarnings ===
<code>getPluginPromoInfoByCode($code)</code>
<code>getWarnings($lastOnly)</code>
Parameters:
Parameters:
* '''$code'''
* '''$lastOnly'''
Returns Array.
Returns Array.
Returns an object with detailed information about promotion by promotion code. You can get promotion code
Returns warnings for admin
(sms limit, bookings limit, etc)
----
----
=== getPluginStatuses ===
=== getWorkDaysTimes ===
<code>getPluginStatuses($pluginNames)</code>
<code>getWorkDaysTimes($startDateTime, $endDateTime)</code>
Parameters:
Parameters:
* '''$pluginNames''' Array
* '''$startDateTime''' string
* '''$endDateTime''' string
Returns Array.
Returns Array.
Return plugin status true if status active, else false. See [[#Plugin's identifiers|list of available plugin's names]].
Return busy time by unit id by GoogleCalendar plugin if enabled.If cache is not expired will return from cache, else load from google and save to cache
----
----
=== getRecentActions ===
=== getWorkload ===
<code>getRecentActions($lastOnly, $limit)</code>
<code>getWorkload($dateStart, $dateEnd, $unitGroupId)</code>
Parameters:
Parameters:
* '''$lastOnly''' Boolean
* '''$dateStart''' string
* '''$limit''' Integer
* '''$dateEnd''' string
* '''$unitGroupId''' integer
Returns Array.
Returns Array.
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.
Example:
['2015-10-21' : {
['2015-10-21' : {
5 : [
5 : [
0 // cancelled bookings hours
0 // cancelled bookings hours
] }]
] }]
* -32011 Params is not array
* -32011 Params is not array
* -32012 Sheduler id not found
* -32012 Sheduler id not found
* -32015 Passed event id is not reccuren
* -32020 Sorry, you have no permissions to perform this action
* -32020 Sorry, you have no permissions to perform this action
* -32030 Invalid promotion code
* -32030 Invalid promotion code
* borgun_payment_gateway_id
* borgun_payment_gateway_id
* borgun_secret_code
* borgun_secret_code
* client_batch_cancel_template
* client_batch_cancel_template
* client_batch_cancel_template_email
* client_batch_cancel_template_email
* modern_week
* modern_week
* classic
* classic
* classes
<code>timeframe</code> field can be 5, 10, 15, 20, 30 or 60 minutes. More information about timeframe you can read [[Settings#Timeframe|here]].
Please note that <code>classic</code> timeline type is deprecated and not supported anymore.
<code>description</code> field contains raw data of company's description which can include HTML tags. <code>description_text</code> field contains only text information without HTML tags.
<code>description</code> field contains raw data of company's description which can include HTML tags. <code>description_text</code> field contains only text information without HTML tags.
For information about <code> timeframe</code>, <code>timezone</code>, <code>allow_event_day_break</code> and <code>allow_event_breaktime_break</code> see [[#Company params|Company params section]].
----
----
