Revision as of 16:04, 30 December 2015 by Admin (talk | contribs) (→‎book response)

Company public service methods

From SimplyBook.me

Methods

book

book($eventId, $unitId, $date, $time, $clientData, $additional, $count, $batchId, $recurringData)

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 require_confirm = true. $startDate and $startTime specifies a date of booking and time slot. Time value should be multiple to 'timeframe' configuration of company (see getTimeframe API method). $endDate and $endTime 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 $endDate and $endTime should be later in time than $startDate and $startTime. If your clients located in different time zone you should specify 'client_time_offset' value in $clientData 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 $clientTimeOffset will be -3600 seconds. You can get information about company's time zone using getCompanyInfo API method. To create batch booking you can specify either count more then 1 or valid batchId (only one parameter can be specified). You should specify an $additionalFields parameter if service requires some additional fields (see Additional fields plugin). To create a booking with promo code you should pass it as additional field. For example: {"name": "promocode", "value": "some code", "type": "text"}See example of book API method response.


calculateEndTime

calculateEndTime($startDateTime, $eventId, $unitId)

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

cancelBooking($id, $sign)

Parameters:

  • $id Integer
  • $sign String

Returns Boolean.

Cancels a booking. $sign parameter must be a string created with formula: md5($bookingId . $bookingHash . $secretKey) . You can get $bookingHash value as result of book 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 $sign parameter is wrong.


confirmBooking

confirmBooking($id, $sign)

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

confirmBookingBatch($batchId, $batchType, $sign)

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

confirmBookingBatchPayment($batchId, $batchType, $paymentProcessor, $sign)

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

confirmBookingPayment($id, $paymentProcessor, $sign)

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

createBatch()

No arguments. Returns Integer.

Creates new booking batch record. Returns newly created batch id. You can use this id in book API method.


getAdditionalFields

getAdditionalFields($eventId)

Parameters:

  • $eventId Integer

Returns Array.

Return additional fields for certain event if Additional fields plugin is activated. Returns empty array otherwise. Call isPluginActivated('event_field') API method to check if 'event_field' plugin activated.


getAnyUnitData

getAnyUnitData()

No arguments. Returns Object|null.

Returns information about 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

getAvailableUnits($eventId, $dateTime, $count)

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.: [1, 2, 3]


getBooking

getBooking($id, $sign)

Parameters:

  • $id Integer
  • $sign String

Returns Object.

Returns an object with details information about booking. $sign parameter must be a string created with formula: md5($bookingId . $bookingHash . $secretKey). You can get $bookingHash value as result of book 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 $sign parameter is wrong.


getBookingDetails

getBookingDetails($id, $sign)

Parameters:

  • $id Integer
  • $sign String

Returns Object.

Returns an object with details information about booking. $sign parameter must be a string created with formula: md5($bookingId . $bookingHash . $secretKey). You can get $bookingHash value as result of book 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 $sign parameter is wrong.


getCategoriesList

getCategoriesList($isPublic)

Parameters:

  • $isPublic boolean

Returns Array.

Returns company categories list if Service categories plugin is activated. Returns an error with code -32001 if plugin is not activated. Use isPluginActivated('event_category') API method to check if plugin activated.


getCompanyInfo

getCompanyInfo()

No arguments. Returns Object.

Returns an object with detailed information about company. See example of response.


getCompanyParam

getCompanyParam($key)

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 list of available keys.


getCountryPhoneCodes

getCountryPhoneCodes()

No arguments. Returns Array.

Returns country phone code list


getEventList

getEventList($isVisibleOnly, $asArray)

Parameters:

  • $isVisibleOnly boolean
  • $asArray boolean

Returns Array.

Returns company's events list. If $asArray 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.


getFirstWorkingDay

getFirstWorkingDay($unitId)

Parameters:

  • $unitId Integer

Returns String.

Returns first working date for unit


getLocationsList

getLocationsList($isPublic)

Parameters:

  • $isPublic Boolean

Returns Array.

Returns available locations for company if plugin Unit location plugin is activated. Return an error with code -32001 if plugin is not activated. Use isPluginActivated('location') API method to check if plugin activated.


getPaymentProcessorConfig

getPaymentProcessorConfig($paymentProcessor)

Parameters:

  • $paymentProcessor String

Returns Array.

Returns payment processor config


getPluginPromoInfoByCode

getPluginPromoInfoByCode($code)

Parameters:

  • $code

Returns Array.

Return promotion information by code


getPluginStatuses

getPluginStatuses($pluginNames)

Parameters:

  • $pluginNames Array

Returns Array.

Return plugin status true if status active, else false. See list of available plugin's names.


getPromocodeInfo

getPromocodeInfo($code)

Parameters:

  • $code String

Returns Array|null.

Returns an object with detailed information about promotion by promotion code. Returns null if no promotions with specified code were not found.


getReservedTime

getReservedTime($from, $to, $eventId, $unitId, $count)

Parameters:

  • $from String
  • $to String
  • $eventId Integer
  • $unitId Integer
  • $count Integer

Returns Object.

Returns not available time Eg.: {'2014-05-14': [{'events': [{'from': '14:00', 'to': '14:30'}], 'type': "reserved_time"}, ...], ...}


getStartTimeMatrix

getStartTimeMatrix($from, $to, $eventId, $unitId, $count)

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.: {'2014-05-14': ['09:00:00', ...], ...}

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 Unit location plugin description for more details.


getTimeframe

getTimeframe()

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 here.


getUnitList

getUnitList($isVisibleOnly, $asArray)

Parameters:

  • $isVisibleOnly boolean
  • $asArray boolean

Returns Array.

Returns list of service performers. If $asArray 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.


getWorkCalendar

getWorkCalendar($year, $month, $unitId)

Parameters:

  • $year Integer
  • $month Integer
  • $unitId Integer

Returns Object.

Returns company work schedule as array Eg.: {'2014-05-01': {'from': '09:00:00', 'to': '21:00:00', 'is_day_off': '0'}, '2014-05-02': ...}


getWorkDaysInfo

getWorkDaysInfo($from, $to, $unitId, $eventId)

Parameters:

  • $from String
  • $to String
  • $unitId Integer (optional)
  • $eventId Integer (optional)

Returns Object.

Returns working time for date period, taking into account breaktimes Eg.: {'2014-05-14': [{'from': '09:00:00', 'to': '10:00:00'}, ...], ...}


hasUpcommingPromotions

hasUpcommingPromotions()

No arguments. Returns Boolean.

Returns availability of active promotions


isPaymentRequired

isPaymentRequired($eventId)

Parameters:

  • $eventId Integer

Returns Boolean.

Return true if event payments plugin is turned on and prices were set, else return false.


isPluginActivated

isPluginActivated($pluginName)

Parameters:

  • $pluginName String

Returns Boolean.

Return plugin status true if status active, else false. $pluginName parameter is a plugin identifier.See plugins page for full plugins description. See list of available plugin's names.


validatePayment

validatePayment($paymentInfo, $cartId)

Parameters:

  • $paymentInfo mixed
  • $cartId Integer

Returns Boolean.

Validate application payment.


validatePromoCode

validatePromoCode($code, $startDateTime, $eventId, $count, $clientData)

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.


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

Use these values to get configuration params for company with getCompanyParam API method.

  • allow_delay_payment
  • allow_event_breaktime_break
  • allow_event_day_break
  • company_timezone
  • date_format
  • fixed_country_prefix
  • hide_sale_tax
  • max_group_bookings
  • max_time_till_event
  • min_time_till_event
  • monday_is_first_day
  • payment_timeout
  • require_fields
    String. Client's data fields required for booking. Possible values:
    • phone - phone number is required
    • email - email address is required
    • email_phone - phone number and email address are required
  • sale_tax
  • send_notifications_in_client_timezone
  • show_booking_page_in_client_timezone
  • time_format
  • timeframe
  • user_public_timeline_type

Plugin's identifiers

Plugin identifier is a string constant which represents a plugin in system. These constants used in isPluginActivated and getPluginStatuses API methods.

  • advanced_notification
    Book Soon notification system plugin
  • any_unit
    Any Employee selector plugin
  • api
    API plugin
  • approve_booking
    Approve booking plugin
  • back_to_site
    Take me back home plugin
  • contact_widget
    Contact widget plugin
  • counter
    Visitor Counter plugin
  • custom_css
    Custom CSS plugin
  • data_security
    Clean history plugin
  • description
    HTML description field for events
  • event_category
    Service categories plugin
  • event_field
    Additional fields plugin
  • facebookImage
    Facebook client info plugin
  • financial_dashboard
    Insights plugin
  • google_analytics
    Google Adwords and analytics plugin
  • google_calendar_export
    Google calendar sync plugin
  • group_booking
    Group bookings plugin
  • hipaa
    HIPAA plugin
  • limit_bookings
    Limit bookings plugin
  • location
    Unit location plugin
  • mobile_app_backend
    Mobile application plugin
  • multiple_booking
    Multiple bookings plugin
  • news
    News plugin
  • paid_events
    Accept payments plugin
  • promo
    Simply Smart Promotions plugin
  • recap
    Daily report plugin
  • secure
    SSL plugin
  • status
    Status plugin
  • unit_colors
    Providers color coding plugin
  • user_license
    Terms and conditions plugin

See Plugins page for description for each plugin.

Examples

book response

book 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"
 }

getCompanyInfo response

An example of data returned by getCompanyInfo API method. 

 {
   "login": "pierrecoetzee",
   "name": "Pierre",
   "description": "Write a description about your company or about you as a service provider. You can add other service providers inside the system and each can have his own description.",
   "address1": "",
   "address2": "Storey's Gate, ",
   "city": "London",
   "country_id": "GB",
   "lat": "51.500435",
   "lng": "-0.129811",
   "email": "pierre.coe@gmail.com",
   "phone": "",
   "web":null,"skip_address":null,"logo":null,"address": "GB, London, Storey's Gate, ",
   "description_text": "Write a description about your company or about you as a service provider. You can add other service providers inside the system and each can have his own description.",
   "timezone": "Europe London",
   "show_in_client_timezone":false,"timeframe": "60",
   "timeline_type": "modern_week",
   "allow_event_day_break": "0",
   "allow_event_breaktime_break": "0"
 }
Retrieved from "https://help.simplybook.me/index.php?title=Company_public_service_methods&oldid=1055"