Download the PHP package teamtools/php-sdk without Composer

Teamtools PHP SDK

• List of all SDK methods

Installation

TeamTools PHP SDK is on Packagist: https://packagist.org/packages/teamtools/php-sdk

TeamTools PHP SDK can be installed using composer (https://getcomposer.org) by issuing following command:

All dependencies will be imported into working directory and you can start using SDK by including appropriate file. Example: if you create your application directory in same level as vendor directory, and your directory structure looks like this:

than you can start using teamtools SDK by including autoload.php in your app/index.php file like this:

You should not modify contents of vendor directory since its contents will be overwritten by composer updates.

Registering client

Before calling any method, client must be authenticated to work with API. This is achieved by supplying client credentials to static method initialize:

If the authentication is successful, from now on we can make calls to SDK methods.

Retrieving access token

If access token is needed for making additional requests to TeamTools API, it can be retrieved after registering client, like this:

Customer entity

Customer namespace

To work with customers, include the following namespace:

Create customer

Update customer

Updating entity flow is: instantiate object from database, set its attributes to desired value and save back to database. Entity can be retrieved by id, or tag and search in which case a collection of objects will be returned. Ways of retrieving entities are described in next section (Get customers).

Get customer

Single customer object can be retrived by its id.

It's also possible to retrieve entities by tag, in which case a collection of entities will be returned.

Finally, entities can be searched by keyword using static method getAll which is provided in all entities. Also returns collection of entities.

Delete customer

Deleting customer is done by instantiating it from database and calling its delete method. Data is being soft-deleted.

Migrate endusers to another customer

Get customer's endusers

Get customer's events

Restore deleted customer

Restore deleted end user

Attributes

Attributes are properties that can be defined and attached to entity. There is a set of predefined attributes for each entity and arbitrary number of additional user-defined attributes may be created.

Get customer attributes

Retrieve a list of attributes for an entity. Contains default and custom attributes, as well as description of relationships with other entities.

Create or update customer attribute

Custom attributes can be defined by instantiating Attribute object with corresponding properties and calling saveAttribute method on corresponding entity, as shown below. New custom attribute department will be created and attached to Customer. This attribute will be included in validations when working with Customer entity. For example: after creating this attribute, it won't be possible to create Customer entity if department is not provided, since department is required custom attribute ('required' => true).

Parameter descriptions

Delete customer attribute

Attribute can be deleted by supplying its id to static method deleteAttribute of corresponding entity. Attributes are soft-deleted, ie. record is marked as deleted and not physically removed from database.

Get enduser attributes

Retrieve a list of attributes for an entity. Contains default and custom attributes, as well as description of relationships with other entities.

Create or update enduser attribute

Custom attributes can be defined by instantiating Attribute object with corresponding properties and calling saveAttribute method on corresponding entity, as shown below. New custom attribute testAttribute will be created and attached to EndUser. This attribute will be included in validations when working with EndUser entity. For example: after creating this attribute, it won't be possible to create EndUser entity if testAttribute is not provided, since testAttribute is required custom attribute ('required' => true).

Delete enduser attribute

Attribute can be deleted by supplying its id to static method deleteAttribute of corresponding entity. Attributes are soft-deleted, ie. record is marked as deleted and not physically removed from database.

TeamTools SDK response formats

Every interaction with TeamTools SDK will return response, even delete operation returns deleted resource. There are two types of responses: PHP object and raw JSON response as API returns it. Default format is PHP object (Entity or ArrayIterator when collections are returned) and raw response can be received by:

• supplying true to instance methods

  • Update customer and return raw response

  • Update customer and return teamtools\Entities\Customer object
• calling methods with suffix Raw when working with static methods
  • $customer = Customer::getByID('565719f3095747906a9215f5'); - returns teamtools\Entities\Customer object
  • $customer = Customer::getByIDRaw('565719f3095747906a9215f5'); - returns raw JSON response

Methods with corresponding "raw response" methods:

Embedding related objects in response

Normally, related objects will be represented with ID in response. For example, customer will contain subscription ID in response which can be used to fetch subscription object. It is possible to embed related object directly into response and save additional server request.

Example embedding subscription object into customer response:

Related data can be nested, and more than one relation can be included. Parameter format should be string with comma separated relations to embed.

Examples for include parameter are:

• embed single relation:
  • include=events
• embed multiple relations:
  • include=events,customer
• nesting data:
  • include=events,customer.invoices

Some example of related object manipulations (not wrapped in try - catch blocks for the sake of clarity):

Features

Feature namespace

To work with features, include the following namespace:

Get feature attributes

Create feature attribute

Update feature attributes

Delete feature attribute

Get feature by ID

Get feature by tag

Create feature

Update feature

Delete feature

Relation examples

Update feature dependencies

Remove feature dependencies

Groups, Packages and Plans

Groups, Packages and Plans namespaces:

To work with groups, packages or plans, include respective namespace:

Step 1: Create Group

Groups have following parameters:

• name - a user-friendly label for the Group that’ll be seen by you in your dashboard, and possibly by your customers.
• default - should be set as true or false, depending if you want to set Group as default
• defaultPackageId - each Group should contain at least one Package. If Group is having more than one Package, you should determine, which Package is getting defaultPackageId.

Code example:

Example with default package and assign as default group:

Retrieve packages by group ID:

Step 2: Create Packages

Packages have following parameters:

• name - a user-friendly label for the package that’ll be seen by you in your dashboard, and possibly by your customers.
• description - additional description of Package for providing more information.
• default - Indicates if Package is default for the group.
• groupId - represents Package group.
• featureIds - represents Feature(s) you want to assign to Package.

Code example:

Example creating package with features:

Upon creation of Package, you will get packageId from teamtools. Each Package requires a unique ID. You’ll provide this value in API requests to subscribe a customer to one of your Packages.

Default Package

In case there is only one Package created in the Group, this Package will get defaultPackageId. If there are two or more Packages created in the Group, you'll need to decide which Package gets to be default.

Retrieve all packages

Step 3: Create Plan

Plan includes following parameters:

• name - a user-friendly label for the Plan which will be inherited from Package name
• description - additional description of Plan for providing more information, which will be inherited from Package name
• trial - number of days available for trial, used in case Trial is offered by your service.
• initialFee - amount, used in case you want to charge specific fee for service setup.
• pricing - described below

Example creating unit plan:

Example creating flat plan:

Example creating tier plan:

Get plan by ID:

Start subscribing Customer to a Package

There are two ways to create customer subscription: via customer create / update request and through dedicated endpoint.

Create subscription using customer update request (returns customer in response):

Create subscription using dedicated endpoint (default group). Returns subscription in response:

Create subscription using dedicated endpoint:

Retrieve customer's subscription

Unsubscribe customer from package

By calling following SDK function customer will be unsubscribed from current package. If subscription exists on payment gateway, it will also be cancelled. Return value: subscription object.

Add invoice item

Invoice item can be added and picked up by next invoice generation. If subscription exist on payment gateway, invoice item will be created on gateway. Otherwise it's created in TeamTools database.

Invoices

Get invoice by ID

Create invoice

Settle invoice

Used to manually mark invoice as settled.

Apply payment on invoice

Manually apply payment to invoice total. If applied amount is equal to invoice total, invoice will be marked as paid. If amount is larger than open invoice amount, invoice will be closed and remaining amount added to balance on subscription object.

Get payments / refunds

Retrieve refunds or payments for invoice:

Bulk insert and update

Customers and Endusers support bulk operations like inserting and updating multiple records in single request. For this operation a structure named "data" should be provided, which contains array of entities to be persisted. If array element contains element "id", entity with that specific ID will be updated. Otherwise, entity will be inserted. All validations are still valid, like when working with single entity.

Customers example:

Endusers example:

Retrieve webhook event

Webhook event format examples

Customer name updated:

Group created:

Package deleted: