SuperSaaS Ruby API Client

Manage appointments, users, and other objects on the SuperSaaS appointment scheduling platform in Ruby.

The SuperSaaS API provides endpoints that can be used to read or update information from your SuperSaaS account. This can be useful to build an integration with a back-end system or to extract information to generate reports.

1. Register for a (free) SuperSaaS account, and
2. Get your account name and API key on the Account Info page.

No external dependencies. Only the json and net/http libraries from the Ruby standard library are used. Requires Ruby 2.5 or later.

Install with:

$ gem install supersaas-api-client

Alternatively, you can use bundler to install it by adding this line to your Gemfile. The supersaas-api-client may update major versions with breaking changes, so it's recommended to use a major version when expressing the gem dependency. e.g.

gem 'supersaas-api-client', '~> 2'

The Client can be used either (1) through the singleton helper method instance, e.g.

Supersaas::Client.instance #=> <Supersaas::Client>

Or else by (2) simply creating a new client instance manually, e.g.

Supersaas::Client.new #=> <Supersaas::Client>

Initialize the SuperSaaS Client with authorization credentials:

Supersaas::Client.configure do |config|
  config.account_name = 'accnt'
  config.api_key = 'xxxxxxxxxxxxxxxxxxxxxx'
end

Note, ensure that configure is called before instance or new, otherwise the client will be initialized with configuration defaults.

If the client isn't configured explicitly, it will use default ENV variables for the account name and api key.

ENV['SSS_API_ACCOUNT_NAME'] = 'your-env-supersaas-account-name'
ENV['SSS_API_KEY'] = 'your-env-supersaas-api-key'
Supersaas::Client.instance.account_name #=> 'your-env-supersaas-account-name'
Supersaas::Client.instance.api_key #=> 'your-env-supersaas-api-key'

All configuration options can be individually set on the client.

Supersaas::Client.instance.api_key = 'xxxxxxxxxxxxxxxxxxxxxx'
Supersaas::Client.instance.verbose = true
...

Details of the data structures, parameters, and values can be found on the developer documentation site:

https://www.supersaas.com/info/dev

Create a user with user attributes params create(attributes, user_id = nil, webhook = nil, duplicate = nil). If webhook=true is present it will trigger any webhooks connected to the account. To avoid a ‘create’ action from being automatically interpreted as an ‘update’, you can add the parameter duplicate=raise, then error 422 Unprocessable Entity will be raised. If in your database your user has id 1234 then you can supply a foreign key in format 1234fk in user_id (optional) which you can use to identify user: If validation fails for any field then error 422 Unprocessable Entity will be raised. The server's explanation is in the exception's errors, see Error Handling. Data fields that you can supply can be found here.

Supersaas::Client.instance.users.create({name: 'name@name.com', full_name: 'Example Name', email: 'example@example.com'}, '1234fk', true, 'raise') #=> http://www.supersaas.com/api/users/1234.json

Update a user by user_id with user attributes params update(user_id, attributes, webhook = nil, notfound = nil). If webhook=true is present it will trigger any webhooks connected to the account. To avoid automatically creating a new record, you can add the parameter notfound=error or notfound=ignore to return a 404 Not Found or 200 OK respectively. If the user_id does not exist 404 error will be raised. You only need to specify the attributes you wish to update:

Supersaas::Client.instance.users.update(12345, {full_name: 'New Name'}, true, "ignore") #=> nil

Delete a single user by user_id, and if the user does not exist 404 error will be raised. If webhook=true is present it will trigger any webhooks connected to the account.

Supersaas::Client.instance.users.delete(12345) #=> nil

Get a single user by user_id, and if the user does not exist 404 error will be raised, you may use optional form:

Supersaas::Client.instance.users.get(12345) #=> <Supersaas::User>

Get all users with optional form and limit/offset pagination params, list(form = nil, limit = nil, offset = nil). User can have a form attached, and setting form=true shows the data:

Supersaas::Client.instance.users.list(false, 25, 0) #=> [<Supersaas::User>, ...]

Get all the fields available to user object:

Supersaas::Client.instance.users.field_list #=> [<Supersaas::FieldList>, ...]

Get the fields that can be set when creating a user, each with a required flag:

Supersaas::Client.instance.users.input_field_list #=> [<Supersaas::FieldList>, ...]

Create an appointment with schedule_id, and user_id(optional) (see API documentation on create new) appointment attributes and optional form and webhook params, create(schedule_id, user_id, attributes, form = nil, webhook = nil):

Supersaas::Client.instance.appointments.create(12345, 67890, {full_name: 'Example Name', email: 'example@example.com', slot_id: 12345}, true, true) #=> http://www.supersaas.com/api/bookings/12345.json

Input attributes are sent on create and update: start, finish, name, full_name, email, address, mobile, phone, country, field_1, field_2, field_1_r, field_2_r, super_field, description and form_id, plus what is booked: resource_id on a resource schedule, or slot_id and quantity (number of places) on a capacity schedule. Any other attribute is not sent. The API does not support creating bookings on service schedules.

Read-only attributes are returned when reading appointments but never sent: id, created_on, updated_on, created_by, updated_by, user_id, deleted, res_name, service_id, service_name, waitlisted, and form when reading with form set.

Update an appointment by schedule_id and appointment_id with appointment attributes, see the above link, update(schedule_id, appointment_id, attributes, form = nil, webhook = nil):

Supersaas::Client.instance.appointments.update(12345, 67890, {full_name: 'New Name'}) #=> nil

Delete a single appointment by schedule_id and appointment_id with optional webhook:

Supersaas::Client.instance.appointments.delete(12345, 67890) #=> nil

Get a single appointment by schedule_id and appointment_id:

Supersaas::Client.instance.appointments.get(12345, 67890) #=> <Supersaas::Appointment>

List appointments by schedule_id, with form, start_time, limit, finish and offset view params, list(schedule_id, form = nil, start_time = nil, limit = nil, finish = nil, offset = nil):

Supersaas::Client.instance.appointments.list(12345, true, '2018-01-31 00:00:00', 25) #=> [<Supersaas::Appointment>, ...]

Get agenda (upcoming) appointments by schedule_id and user_id, with from_time view param (see), agenda(schedule_id, user_id, from_time = nil, slot = false):

Supersaas::Client.instance.appointments.agenda(12345, 67890, '2018-01-31 00:00:00') #=> [<Supersaas::Appointment>, ...]

This method is deprecated and will be removed in the future. Get agenda (upcoming) slots by schedule_id and user_id, with from_time view param, agenda_slots(schedule_id, user_id, from_time = nil):

Supersaas::Client.instance.appointments.agenda_slots(12345, 67890, '2018-01-31 00:00:00') #=> [<Supersaas::Slot>, ...]

Note: only works for capacity type schedules.

Get available appointments by schedule_id, with from time and length_minutes and resource params (see), available(schedule_id, from_time, length_minutes = nil, resource = nil, full = nil, limit = nil):

Supersaas::Client.instance.appointments.available(12345, '2018-01-31 00:00:00', 15, 'My Class') #=> [<Supersaas::Appointment>, ...]

Get recently changed appointments by schedule_id, with from time, to time, user user, slot view params (see docs), changes(schedule_id, from_time = nil, to = nil, slot = false, user = nil, limit = nil, offset = nil):

Supersaas::Client.instance.appointments.changes(12345, '2018-01-31 00:00:00', '2019-01-31 00:00:00', true) #=> [<Supersaas::Appointment>, ...]

Get range of appointments by schedule_id, with today, from time, to time and slot view params (see docs), range(schedule_id, today = false, from_time = nil, to = nil, slot = false, user = nil, resource_id = nil, service_id = nil, limit = nil, offset = nil):

Supersaas::Client.instance.appointments.range(12345, false, '2018-01-31 00:00:00', '2019-01-31 00:00:00', true) #=> [<Supersaas::Appointment>, ...]/[<Supersaas::Slot>, ...]

List the slots of a capacity type schedule by schedule_id, with optional start_time, finish, limit (default 100, max 2500) and offset view params, list(schedule_id, start_time = nil, finish = nil, limit = nil, offset = nil):

Supersaas::Client.instance.slots.list(12345, '2018-01-31 00:00:00', '2019-01-31 00:00:00', 50) #=> [<Supersaas::Slot>, ...]

Note: slots only work for capacity type schedules. On other schedule types the API returns 405, which raises Supersaas::Exception with "Not available for this schedule type".

Get a single slot by schedule_id and slot_id:

Supersaas::Client.instance.slots.get(12345, 67890) #=> <Supersaas::Slot>

Create a slot with schedule_id and slot attributes (start, finish, title, description, location, capacity, price, color), create(schedule_id, attributes). A capacity of '-' means unlimited, 0 means no places:

Supersaas::Client.instance.slots.create(12345, {start: '2018-01-31 14:00:00', finish: '2018-01-31 15:00:00', title: 'Yoga', capacity: 10}) #=> http://www.supersaas.com/api/slots/67890.json

Update a slot by schedule_id and slot_id with slot attributes, see the above link, update(schedule_id, slot_id, attributes):

Supersaas::Client.instance.slots.update(12345, 67890, {title: 'Advanced Yoga', capacity: '-'}) #=> {}

Delete a single slot by schedule_id and slot_id. Bookings on the slot are deleted as well:

Supersaas::Client.instance.slots.delete(12345, 67890) #=> {}

Get all forms by template superform_id, with from_time, and user params (see) and limit/offset pagination params:

Supersaas::Client.instance.forms.list(12345, '2018-01-31 00:00:00') #=> [<Supersaas::Form>, ...]

Get a single form by form_id, will raise 404 error if not found:

Supersaas::Client.instance.forms.get(12345) #=> <Supersaas::Form>

Get a list of Form templates (SuperForms):

Supersaas::Client.instance.forms.forms #=> [<Supersaas::SuperForm>, ...]

Get a list of promotional coupon codes with pagination parameters limit and offset (see docs), list(limit = nil, offset = nil):

Supersaas::Client.instance.promotions.list #=> [<Supersaas::Promotion>, ...]

Retrieve information about a single coupon code by its alphanumeric promotion_code:

Supersaas::Client.instance.promotions.promotion('SPRING10') #=> [<Supersaas::Promotion>]

Duplicate a template promotion by giving (new) promotion_code and template_code in that order, duplicate_promotion_code(promotion_code, template_code):

Supersaas::Client.instance.promotions.duplicate_promotion_code('SPRING11', 'SPRING10') #=> nil

List Groups in an account (see):

Supersaas::Client.instance.groups.list #=> [<Supersaas::Group>, ...]

Get all account schedules:

Supersaas::Client.instance.schedules.list #=> [<Supersaas::Schedule>, ...]

Get all services/resources by schedule_id:

Supersaas::Client.instance.schedules.resources(12345) #=> [<Supersaas::Resource>, ...]

Note: does not work for capacity type schedules.

Get all the available fields of a schedule by schedule_id:

Supersaas::Client.instance.schedules.field_list(12345) #=> [<Supersaas::FieldList>, ...]

Get the fields that can be set when creating a booking on a schedule by schedule_id, each with a required flag:

Supersaas::Client.instance.schedules.input_field_list(12345) #=> [<Supersaas::FieldList>, ...]

Check that the account name and API key are valid. Returns true, or raises Supersaas::Exception with status 401:

Supersaas::Client.instance.ping #=> true

Create a webhook with target_url, event and parent_id (see). The event is the trigger letter, e.g. 'U' new user, 'M' changed user, 'N' new appointment, 'C' changed appointment. The parent_id is the schedule id for appointment events, the super form id for form events, and the account id otherwise:

Supersaas::Client.instance.hooks.create('https://example.com/hook', 'N', 12345) #=> {"id"=>67, "parent_id"=>12345}

Delete a webhook by hook_id and parent_id:

Supersaas::Client.instance.hooks.delete(67, 12345) #=> {}

The ./examples folder contains several executable Ruby scripts demonstrating how to use the API Client for common requests.

The examples require your account name and API key. The appointments example also needs a schedule id, and optionally takes a user id (otherwise it creates and deletes a user) and a slot id for capacity type schedules. These can be set as environment variables, e.g.

$ gem install supersaas-api-client
$ SSS_API_USER=myuserid SSS_API_SCHEDULE=myscheduleid SSS_API_ACCOUNT_NAME=myaccountname SSS_API_KEY=xxxxxxxxxxxxxxxxxxxxxx ./examples/appointments.rb
$ SSS_API_ACCOUNT_NAME=myaccountname SSS_API_KEY=xxxxxxxxxxxxxxxxxxxxxx ./examples/forms.rb
$ SSS_API_ACCOUNT_NAME=myaccountname SSS_API_KEY=xxxxxxxxxxxxxxxxxxxxxx ./examples/users.rb

The HTTP requests can be stubbed by configuring the client with the dry_run option, e.g.

Supersaas::Client.instance.dry_run = true

Note, stubbed requests always return an empty Hash.

The Client also provides a last_request attribute containing the Net::HTTP object from the last performed request, e.g.

Supersaas::Client.instance.last_request #=> <Net::HTTP::Get>

The headers, body, path, etc. of the last request can be inspected for assertion in tests, or for troubleshooting failed API requests.

For additional troubleshooting, the client can be configured with the verbose option, which will puts any JSON contents in the request and response. Password values in the request are shown as [FILTERED]; the request itself is sent unchanged. E.g.

Supersaas::Client.instance.verbose = true

The API Client raises a custom exception for HTTP errors and invalid input. Rescue from Supersaas::Exception when making API requests. e.g.

begin
  Supersaas::Client.instance.users.get
rescue Supersaas::Exception => e
  # Handle error
end

For HTTP errors the exception also carries the status code and the errors the server returned:

begin
  Supersaas::Client.instance.slots.get(12345, 999)
rescue Supersaas::Exception => e
  e.message #=> "HTTP Request Error: Not Found"
  e.status  #=> 404
  e.errors  #=> [{"status"=>"404", "title"=>"Not found"}]
end

errors is an empty array when the response has no JSON error body. status is nil for errors raised before a request is sent, such as invalid input.

• SuperSaaS Registration
• Product Documentation
• Developer Documentation

Contact: support@supersaas.com

The bin/ scripts are for working on the client itself and are not included in the gem:

$ bin/setup            # install the development dependencies
$ bin/console          # IRB session with the client loaded
$ bundle exec rake test
$ bundle exec rake lint

The package follows semantic versioning, i.e. MAJOR.MINOR.PATCH.

The SuperSaaS Ruby API Client is available under the MIT license. See the LICENSE file for more info.