SimplyBook.me

Company public service methods: Difference between revisions

← Older editNewer edit →
VisualWikitext
No edit summary
Line 14: Line 14:
* <code>id</code> - The id of the request it is responding to.
* <code>id</code> - The id of the request it is responding to.


Example:
Example


<pre>
<pre>
Line 33: Line 33:
             "duration": "60",
             "duration": "60",
             "hide_duration": "0",
             "hide_duration": "0",
             "description": "<p>Sample service description</p>",
             "description": "<p>Если Вы хотите попробовать себя в роли модели, но не определились с образом. <br /> 5-7 отретушированных и готовых к печати фотографий + отснятый материал на диске</p>",
             "picture": "a200edab10b669225e22d2b3803a38b5.jpg",
             "picture": "a200edab10b669225e22d2b3803a38b5.jpg",
             "is_public": "1",
             "is_public": "1",
Line 84: Line 84:
===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#getToken|getToken]]</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#getToken|getToken]]</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 ==
Line 126: Line 126:


* [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 219: Line 202:
----
----


=== confirmBookingPayment ===
=== confirmBookingCart ===


<code>confirmBookingPayment($id, $paymentProcessor, $sign)</code>
<code>confirmBookingCart($cartId, $paymentProcessor, $sign)</code>


Parameters:
Parameters:


* '''$id''' Integer  
* '''$cartId''' Integer - cart id
* '''$paymentProcessor''' String  
* '''$paymentProcessor''' String - payment processor name
* '''$sign''' String  
* '''$sign''' String - signature. (md5($cartId . $cartHash . $secretKey))


Returns Boolean.
Returns Boolean.


Confirm booking payment. Signature is required.$sign = md5($bookingId . $bookingHash . $secretKey);
Confirm booking cart. Use it to confirm payment. Signature is required.
Call this method from server side only




----
----


=== createBatch ===
=== confirmBookingPayment ===


<code>createBatch()</code>
<code>confirmBookingPayment($id, $paymentProcessor, $sign)</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.
 
 
----
 
=== getAdditionalFields ===
 
<code>getAdditionalFields($eventId)</code>


Parameters:
Parameters:


* '''$eventId''' Integer  
* '''$id''' Integer  
* '''$paymentProcessor''' String
* '''$sign''' String


Returns Array.
Returns Boolean.


Return additional fields for certain event if [[Plugins#Additional_fields|Additional fields plugin]] is
Confirm booking payment. Signature is required.$sign = md5($bookingId . $bookingHash . $secretKey);
activated. Returns empty array otherwise. Call <code>[[#isPluginActivated|isPluginActivated('event_field')]]</code>
Call this method from server side only
API method to check if 'event_field' plugin activated.




----
----


=== getAnyUnitData ===
=== getBooking ===


<code>getAnyUnitData()</code>
<code>getBooking($id, $sign)</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
  }
 
 
----
 
=== getAvailableUnits ===
 
<code>getAvailableUnits($eventId, $dateTime, $count)</code>


Parameters:
Parameters:


* '''$eventId''' Integer  
* '''$id''' Integer  
* '''$dateTime''' String a date and time string in format 'Y-m-d H:i:s'
* '''$sign''' String  
* '''$count''' Integer


Returns Array.
Returns Object.


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 an object with details information about booking. <code>$sign</code> parameter must be a string created
with formula: <code>md5($bookingId . $bookingHash . $secretKey)</code>. You can get <code>$bookingHash</code>
value as result of <code>[[#book|book]]</code> API method call. Method return an error with code -32080
(Appointment couldn't be found) if record with specified id not exists. Methods returns an error with code -32085
(Signature error) if <code>$sign</code> parameter is wrong.




----
----


=== getBooking ===
=== getBookingCart ===


<code>getBooking($id, $sign)</code>
<code>getBookingCart($bookingIds)</code>


Parameters:
Parameters:


* '''$id''' Integer
* '''$bookingIds''' Array
* '''$sign''' String


Returns Object.
Returns Object.


Returns an object with details information about booking. <code>$sign</code> parameter must be a string created
Returns cart information by bookings ids.<code>cart_id</code> and <code>cart_hash</code> is used to create secure signature to confirm cart payment.
with formula: <code>md5($bookingId . $bookingHash . $secretKey)</code>. You can get <code>$bookingHash</code>
<code>amount</code> - is total amount to payment
value as result of <code>[[#book|book]]</code> API method call. Method return an error with code -32080
<code>currency</code> - cart currency
(Appointment couldn't be found) if record with specified id not exists. Methods returns an error with code -32085
<code>cart</code> - contains cart items. You can use them to provide information for payment system. Each item is object with following fields:
(Signature error) if <code>$sign</code> parameter is wrong.
<code>id</code> - booking id
<code>event_id</code> - service id
<code>name</code> - event name + start date time (use it to provide cart information for payment system)
<code>price</code> - booking price
<code>qty</code> - qty of bookings




Line 355: Line 310:
Returns Array.
Returns Array.


Returns company categories list if [[Plugins#Service categories|Service categories plugin]] is activated. Returns
{@inheritdoc}
an error with code -32001 if plugin is not activated. Use <code>[[#isPluginActivated|isPluginActivated('event_category')]]</code>
API method to check if plugin activated.
 
 
----
 
=== 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]].
 
 
----
 
=== getCountryPhoneCodes ===
 
<code>getCountryPhoneCodes()</code>
 
No arguments.
Returns Array.
 
Returns country phone code list




Line 414: Line 326:
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
{@inheritdoc}
and details object as value. If parameter set to true then method returns a list sorted by 'position' property of
event's details object.
 
 
----
 
=== getFirstWorkingDay ===
 
<code>getFirstWorkingDay($unitId)</code>
 
Parameters:
 
* '''$unitId''' Integer
 
Returns String.
 
Returns first working date for unit




Line 438: Line 333:
=== getLocationsList ===
=== getLocationsList ===


<code>getLocationsList($isPublic)</code>
<code>getLocationsList($isPublic, $asArray)</code>


Parameters:
Parameters:


* '''$isPublic''' Boolean  
* '''$isPublic''' Boolean  
* '''$asArray''' 


Returns Array.
Returns Array.


Returns available locations for company if plugin [[Plugins#Unit location|Unit location plugin]] is activated. Return
{@inheritdoc}
an error with code -32001 if plugin is not activated. Use <code>[[#isPluginActivated|isPluginActivated('location')]]</code>
API method to check if plugin activated.




Line 464: Line 358:


Returns payment processor config
Returns payment processor config
----
=== 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 519: Line 378:
----
----


=== getReservedTime ===
=== getPromotionRewardInfo ===


<code>getReservedTime($from, $to, $eventId, $unitId, $count)</code>
<code>getPromotionRewardInfo($commonPromotionId, $clientId, $hash)</code>


Parameters:
Parameters:


* '''$from''' String
* '''$commonPromotionId''' Integer  
* '''$to''' String
* '''$clientId''' Integer  
* '''$eventId''' Integer  
* '''$hash''' String
* '''$unitId''' Integer  
* '''$count''' Integer


Returns Object.
Returns Array|null.


Returns not available time
Returns promotion reward by common promotion id, client id and hash.
Eg.: <code>{'2014-05-14': [{'events': [{'from': '14:00', 'to': '14:30'}], 'type': "reserved_time"}, ...], ...}</code>




----
----


=== getStartTimeMatrix ===
=== getRecurringDatetimes ===


<code>getStartTimeMatrix($from, $to, $eventId, $unitId, $count)</code>
<code>getRecurringDatetimes($eventId, $unitId, $date, $time, $recurringData)</code>


Parameters:
Parameters:


* '''$from''' String
* '''$to''' String
* '''$eventId''' Integer  
* '''$eventId''' Integer  
* '''$unitId''' Mixed can be Integer or Array of Integers
* '''$unitId''' Integer  
* '''$count''' Integer
* '''$date''' String
* '''$time''' String
* '''$recurringData''' Array


Returns Object.
Returns Array.


Returns available start time, taking into account breaktimes, start and end working time
Get list of dates for recurring booking
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.
 
 
----
 
=== 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]].




Line 586: Line 425:
Returns Array.
Returns Array.


Returns list of service performers. If <code>$asArray</code> is false then method returns a map with event id as
{@inheritdoc}
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.




----
----


=== getWorkCalendar ===
=== getUserLicenseText ===


<code>getWorkCalendar($year, $month, $unitId)</code>
<code>getUserLicenseText()</code>


Parameters:
No arguments.
 
Returns String.
* '''$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)</code>
 
Parameters:
 
* '''$from''' String  
* '''$to''' String
* '''$unitId''' Integer (optional)
* '''$eventId''' Integer (optional)
 
Returns Object.


Returns working time for date period, taking into account breaktimes
Returns user license text if user license plugin is turned on,
Eg.: <code>{'2014-05-14': [{'from': '09:00:00', 'to': '10:00:00'}, ...], ...}</code>
otherwise throws exception




Line 654: Line 467:
Return true if event payments plugin is turned on and prices were set,
Return true if event payments plugin is turned on and prices were set,
else return false.
else return false.
----
=== 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]].




Line 718: Line 516:
* -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
Line 762: Line 561:
* allow_event_day_break
* allow_event_day_break
*: <code>true</code> if service can extend over closing hours
*: <code>true</code> if service can extend over closing hours
* changable_prefix_by_client
* company_timezone
* company_timezone
* date_format
* date_format
Line 791: Line 591:
** classic
** classic
*: Please note that <code>classic</code> timeline type is deprecated and not supported anymore.
*: Please note that <code>classic</code> timeline type is deprecated and not supported anymore.
----
----


Line 960: Line 761:
* 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]].
----
----


Line 996: Line 799:


<code>service_ids</code> contains a list of services for wich promotion discount can be applied.
<code>service_ids</code> contains a list of services for wich promotion discount can be applied.
----
====getLocationsList response====
  {
    "1": {
        "id": "1",
        "title": "location 1",
        "description": null,
        "picture": "e1e9409fe9682c78b2f8f294dc151af0.jpg",
        "address1": null,
        "address2": "Saint Margaret Street",
        "city": "London",
        "zip": null,
        "country_id": "GB",
        "lat": "51.50013000000000000000",
        "lng": "-0.12630500000000000000",
        "phone": "",
        "position": "1",
        "is_default": "1",
        "file_id": "4",
        "picture_sub_path": "\/image_files",
        "picture_path": "\/uploads\/mycompany\/image_files\/small\/e1e9409fe9682c78b2f8f294dc151af0.jpg",
        "units": ["1", "3", "4", "5"]
    },
    ...
  }
<code>position</code> property of location object used for order list. <code>units</code> array contains list of performers ids associated with location.
Retrieved from "https://help.simplybook.me/index.php?title=Company_public_service_methods"