@@ Line 1: / Line 1: @@
-You can find full list of Company public service API methods [https://simplybook.me/api/doc#/ here].
+== Methods ==
+=== book ===
+<code>book($eventId, $unitId, $date, $time, $clientData, $additional, $count, $batchId, $recurringData)</code>
+Parameters:
+* '''$eventId''' Integer
+* '''$unitId''' Integer
+* '''$date''' String - in Y-m-d format
+* '''$time''' String - in H:i:s format
+* '''$clientData''' Object - eg. {name: 'Name', email: 'test@gmail.com', phone: '+38099999999'}
+* '''$additional''' array|Object - additional params and fields.
+* '''$count''' Integer - bookings count, min. 1 (using for group bookings batch). (optional)
+* '''$batchId''' Integer - add booking to multiple bookings batch. (optional)
+* '''$recurringData''' Array - make booking recurrent. (optional)
+Returns Object.
+Creates new booking record. Returns an object with appointment information or throw exception if booking time not
+available or any of required parameters missed. If appointment requires confirmation, in result object will be
+<code>require_confirm = true</code>. <code>$startDate</code> and <code>$startTime</code> specifies a date of
+booking and time slot. Time value should be multiple to 'timeframe' configuration of company (see
+<code>[[#getTimeframe|getTimeframe]]</code> API method). <code>$endDate</code> and <code>$endTime</code> parameters
+should be calculated according to service duration. However you can specify different values to make appointment
+longer or shorter then service configuration. Note that <code>$endDate</code> and <code>$endTime</code> should be
+later in time than <code>$startDate</code> and <code>$startTime</code>. If your clients located in different time
+zone you should specify <code>'client_time_offset'</code> value in <code>$clientData</code> object as difference
+between company's time zone and client's time zone in seconds. For example if company located in city with time
+zone GMT+2 and customer located in city with GMT+3 then <code>$clientTimeOffset</code> will be -3600 seconds. You
+can get information about company's time zone using <code>[[#getCompanyInfo|getCompanyInfo]]</code> API method. To
+create batch booking you can 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 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>{"name": "promocode", "value": "some code", "type": "text"}</code>See [[#book response|example]] of <code>book</code> API method response.
+----
+=== 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
+----
+=== cancelBooking ===
+<code>cancelBooking($id, $sign)</code>
+Parameters:
+* '''$id''' Integer
+* '''$sign''' String
+Returns Boolean.
+Cancel booking. Signature is required
+$sign = md5($bookingId . $bookingHash . $secretKey);
+----
+=== confirmBooking ===
+<code>confirmBooking($id, $sign)</code>
+Parameters:
+* '''$id''' Integer
+* '''$sign''' String
+Returns Boolean.
+Confirm booking. Signature is required.$sign = md5($bookingId . $bookingHash . $secretKey);
+Call this method from server side only
+----
+=== confirmBookingBatch ===
+<code>confirmBookingBatch($batchId, $batchType, $sign)</code>
+Parameters:
+* '''$batchId''' Integer
+* '''$batchType''' String
+* '''$sign''' String
+Returns Boolean.
+Confirms booking batch. Signature is required.$sign = md5($batchId . $batchHash . $secret)
+Call this method from server side only
+----
+=== confirmBookingBatchPayment ===
+<code>confirmBookingBatchPayment($batchId, $batchType, $paymentProcessor, $sign)</code>
+Parameters:
+* '''$batchId''' Integer
+* '''$batchType''' String
+* '''$paymentProcessor'''
+* '''$sign''' String
+Returns Boolean.
+Confirms booking batch payment. Signature is required.$sign = md5($batchId . $batchHash . $secret)
+Call this method from server side only
+----
+=== confirmBookingPayment ===
+<code>confirmBookingPayment($id, $paymentProcessor, $sign)</code>
+Parameters:
+* '''$id''' Integer
+* '''$paymentProcessor''' String
+* '''$sign''' String
+Returns Boolean.
+Confirm booking payment. Signature is required.$sign = md5($bookingId . $bookingHash . $secretKey);
+Call this method from server side only
+----
+=== 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.
+----
+=== 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
+  }
+----
+=== 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>
+----
+=== getBooking ===
+<code>getBooking($id, $sign)</code>
+Parameters:
+* '''$id''' Integer
+* '''$sign''' String
+Returns Object.
+Returns booking info. Signature is required
+$sign = md5($bookingId . $bookingHash . $secretKey);
-==Methods==
 ----
-====getCompanyParam====
-<code>getCompanyParam(key)</code>
+=== getBookingDetails ===
-Params:
+<code>getBookingDetails($id, $sign)</code>
-* '''key''' string
-Returns string.
+Parameters:
+* '''$id''' Integer
+* '''$sign''' String
+Returns Object.
+Returns detailed booking info. Signature is required
+$sign = md5($bookingId . $bookingHash . $secretKey);
-<code>getCompanyParam</code> API method returns configuration value for specified key. Method return invalid params error (code [[Errors handling#Error codes|-32602]]) in case if specified key not allowed. See [[#Company_params|list of available keys]].
 ----
-====getPluginStatuses====
+=== getCategoriesList ===
+<code>getCategoriesList($isPublic)</code>
-<code>getPluginStatuses(pluginNames)</code>
+Parameters:
-Params:
+* '''$isPublic''' boolean
-* '''pluginNames''' an array of strings
+Returns Array.
-Returns an associative array with strings as keys and booleans as values.
+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.
-Returns an associative array (a JSON object) with values from <code>pluginNames</code> parameter as keys and boolean values for each plugin. See [[#Plugin.27s_identifiers|list of available plugin identifiers]].
 ----
-====isPluginActivated====
+=== getCompanyInfo ===
-<code>isPluginActivated(pluginName)</code>
+<code>getCompanyInfo()</code>
-Params:
+No arguments.
-* '''pluginName''' string
+Returns Object.
-Returns boolean (1 or 0).
+Returns company information
+----
+=== 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
+----
+=== getEventList ===
+<code>getEventList($isVisibleOnly, $asArray)</code>
+Parameters:
+* '''$isVisibleOnly''' boolean
+* '''$asArray''' boolean
+Returns Array.
+Returns company active events list
+----
+=== getFirstWorkingDay ===
+<code>getFirstWorkingDay($unitId)</code>
+Parameters:
+* '''$unitId''' Integer
+Returns String.
+Returns first working date for unit
+----
+=== getLocationsList ===
+<code>getLocationsList($isPublic)</code>
+Parameters:
+* '''$isPublic''' Boolean
+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.
+----
+=== getPaymentProcessorConfig ===
+<code>getPaymentProcessorConfig($paymentProcessor)</code>
+Parameters:
+* '''$paymentProcessor''' String
+Returns Array.
+Returns payment processor config
+----
+=== 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]].
+----
+=== getPromocodeInfo ===
+<code>getPromocodeInfo($code)</code>
+Parameters:
+* '''$code''' String
+Returns Array|null.
+Returns promocode information by code
+----
+=== getReservedTime ===
+<code>getReservedTime($from, $to, $eventId, $unitId, $count)</code>
+Parameters:
+* '''$from''' String
+* '''$to''' String
+* '''$eventId''' Integer
+* '''$unitId''' Integer
+* '''$count''' Integer
+Returns Object.
+Returns not available time
+Eg.: <code>{'2014-05-14': [{'events': [{'from': '14:00', 'to': '14:30'}], 'type': "reserved_time"}, ...], ...}</code>
+----
+=== 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.
+----
+=== getTimeframe ===
+<code>getTimeframe()</code>
+No arguments.
+Returns Integer.
+Returns company timeframe
+----
+=== getUnitList ===
+<code>getUnitList($isVisibleOnly, $asArray)</code>
+Parameters:
+* '''$isVisibleOnly''' boolean
+* '''$asArray''' boolean
+Returns Array.
+Returns active service performrs list
+----
+=== 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)</code>
+Parameters:
+* '''$from''' String
+* '''$to''' String
+* '''$unitId''' Integer
+* '''$eventId''' null
+Returns Object.
+Returns working time for date period, taking into account breaktimes
+Eg.: <code>{'2014-05-14': [{'from': '09:00:00', 'to': '10:00:00'}, ...], ...}</code>
+----
+=== hasUpcommingPromotions ===
+<code>hasUpcommingPromotions()</code>
+No arguments.
+Returns Boolean.
+Returns availability of active promotions
+----
+=== isPaymentRequired ===
+<code>isPaymentRequired($eventId)</code>
+Parameters:
+* '''$eventId''' Integer
+Returns Boolean.
+Return true if event payments plugin is turned on and prices were set,
+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]].
+----
+=== validatePayment ===
+<code>validatePayment($paymentInfo, $cartId)</code>
+Parameters:
+* '''$paymentInfo''' mixed
+* '''$cartId''' Integer
+Returns Boolean.
+Validate application payment.
+----
+=== validatePromoCode ===
+<code>validatePromoCode($code, $startDateTime, $eventId, $count, $clientData)</code>
+Parameters:
+* '''$code''' String
+* '''$startDateTime''' String
+* '''$eventId''' Integer
+* '''$count''' Integer
+* '''$clientData''' array|Object
+Returns Boolean.
+Validate promotion code.Returns true in case promocode is valid otherwise throws exception with error.
-Return plugin status true if status active, else false. <code>pluginName</code> parameter should be one of the plugin's identifiers. See [[#Plugin.27s_identifiers|list of available plugin identifiers]].
 ----
 ==Constants==
+=== Error codes ===
+See [[Errors handling]] for details.
+* -32001 Plugin is not activated
+* -32010 Some required params are missed
+* -32011 Params is not array
+* -32012 Sheduler id not found
+* -32020 Sorry, you have no permissions to perform this action
+* -32030 Invalid promotion code
+* -32031 Promotion has expired
+* -32032 Promotion is not active yet
+* -32033 This promocode is not valid for selected service
+* -32034 Exceed max usage limit
+* -32035 Exceed max usage per customer limit'const
+* -32036 This promocode is not available for datetime range
+* -32051 Selected event id is not available
+* -32052 Selected unit id is not available
+* -32053 Selected date start is not available
+* -32054 Selected time start is not available
+* -32055 One or more appointments couldn't be reserved
+* -32056 Booking is not allowed at this time
+* -32061 Client name value is wrong
+* -32062 Client email value is wrong
+* -32063 Client phone value is wrong
+* -32070 Additional field values are wrong
+* -32080 Appointemnt couldn't be found
+* -32085 Signature error
+* -32090 Confirmation with this key type is not available
+* -32095 Batch not found
+* -32097 Unsupported payment system
+* -32099 Payment failed
+* -32600
+*: An error with this code can be thrown with one of the following messages:
+** Access denied
+** Company does not exists
+* -32601 Method not found
+* -32602 Invalid params
+* -32603 Internal error
+* -3264 Client with given id not found
+----
 ====Company params====
@@ Line 140: / Line 725: @@
 See [[Plugins]] page for description for each plugin.
 ----
+== Examples ==
+====book response====
+[[#book|<code>book</code>]] API method returns an object which contains list of objects with short description of newly create bookings. Method returns only one item in 'bookings' array for regular appointment and more than one item for recurring or batch bookings.
+  {
+    "require_confirm":false,
+    "bookings":[
+      {
+        "id":"434",
+        "event_id":"7",
+        "unit_id":"3",
+        "client_id":"34",
+        "start_date_time":"2015-12-30 13:00:00",
+        "end_date_time":"2015-12-30 13:30:00",
+        "is_confirmed":"1",
+        "code":"h8vc14ca",
+        "hash":"785cb8cce316e64765b94c05a635f4be"
+      },
+      {
+        "id":"435",
+        "event_id":"7",
+        "unit_id":"3",
+        "client_id":"34",
+        "start_date_time":"2015-12-31 13:00:00",
+        "end_date_time":"2015-12-31 13:30:00",
+        "is_confirmed":"1",
+        "code":"h8vc2pge",
+        "hash":"8b92d634541bfd93c0830967e56f4653"
+      },
+      {
+        "id":"436",
+        "event_id":"7",
+        "unit_id":"3",
+        "client_id":"34",
+        "start_date_time":"2016-01-04 13:00:00",
+        "end_date_time":"2016-01-04 13:30:00",
+        "is_confirmed":"1",
+        "code":"h8vc3urb",
+        "hash":"cd22a0bf183f7350e595988dd2486e5b"
+      },
+      {
+        "id":"437",
+        "event_id":"7",
+        "unit_id":"3",
+        "client_id":"34",
+        "start_date_time":"2016-01-05 13:00:00",
+        "end_date_time":"2016-01-05 13:30:00",
+        "is_confirmed":"1",
+        "code":"h8vc44d9",
+        "hash":"53f98ff4e4a0323aa907156c59c99362"
+      }
+    ],
+    "batch_type":"batch_recurrent_booking",
+    "recurrent_batch_id":"1",
+    "batch_hash":"357178bce290381bb7235080941ec143"
+  }

Company public service methods: Difference between revisions