Manage appointments, users, and other object 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 back-end system or to extract information to generate reports.
- Register for a (free) SuperSaaS account, and
- Get your account name and API key on the Account Info page.
No external dependencies. Only the json and net/http gems from the ruby standard library are used.
Install with:
$ gem install supersaas-api-client
Alternatively, you can use bundler to install it by adding this line to you 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
configureis called beforeinstanceornew, 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-account-name'
Supersaas::Client.instance.account_name #=> 'your-env-supersaas-account-name'
Supersaas::Client.instance.api_key #=> 'your-env-supersaas-account-name'
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 and any additional information will be printed to your log.
Data fields that you can supply can be found here.
Supersaas::Client.instance.users.create({name: '[email protected]', full_name: 'Example Name', email: '[email protected]'}, '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>, ...]
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: '[email protected]', slot_id: 12345}, true, true) #=> http://www.supersaas.com/api/bookings/12345.json
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 and start_time and limit view params,
list(schedule_id, form = nil, start_time = nil, limit = nil):
Supersaas::Client.instance.appointments.list(12345, 67890, true, true) #=> [<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>, ...]
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 use with promotion_code:
Supersaas::Client.instance.promotions.promotion(12345) #=> <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(12345, 94832838) #=> 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>, ...]
The ./examples folder contains several executable Ruby scripts demonstrating how to use the API Client for common requests.
The examples will require your account name, api key, and some of the examples a schedule id and/or user id and/or form id. These can be set as environment variables. e.g.
$ gem install supersaas-api-client
$ SSS_API_UID=myuserid SSS_API_SCHEDULE=myscheduleid SSS_API_ACCOUNT_NAME=myaccountname SSS_API_KEY=xxxxxxxxxxxxxxxxxxxxxx ./examples/appointments.rb
$ SSS_API_FORM=myuserid 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, 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
Some errors have more information and are printed to the log before raising the error e.g.
appointment = Supersaas::Client.instance.appointments.create(12345, {bad_field_name: ''})
"Error 400, Bad request: unknown attribute 'bad_field_name' for Booking."
Contact: [email protected]
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.