goboomtown/cloud-sdk-php

PHP SDK for the Boomtown Cloud API

Boomtown Cloud SDK for PHP (v1)

Overview

This repository contains the open source PHP SDK that allows you to access the Cloud API from your PHP app. Authentication uses a pre-shared key and secret, which is generated in our Admin Portal.

Getting Started

To get started, clone this repository and add it to your PHP project

API Key Generation

• Log onto the Admin Portal (https://admin.goboomtown.com)
• Click Providers in the left menu
• Find your provider in the list
• Double click your provider
• Click API Settings, near the button of the configuration panel
• Select Sandbox or Live, depending on the state of development
• Click Re-Generate
• Copy the access token and private-key, as provided in the pop-up dialog

Documentation For Authorization

The Cloud API uses a keyed-HMAC (Hash Message Authentication Code) for authentication. To authenticate a request, your public (your token) & private (your secret) key are used to calculate the HMAC from a "canonicalized resource" based on specific elements of your request URL. Informally, we call this process "signing the request," and we call the output of the HMAC algorithm the signature.

Note:

• HMAC is based on SHA256 hashing.
• Each request will be valid for 10 seconds from when the request is signed.

The Canonicalized Resource Parts:

The "canonicalized resource" is comprised of the PATH, QUERY and a TIMESTAMP in ISO-8601 form and will be constructed as follows in the order listed.

1. PATH: The URL without the hostname and QUERY - "/api/v2/issues"
2. QUERY: Anything after the PATH - "?id=SOME_ID#FOO"
3. TIMESTAMP Date & Time in ISO8601 format - "2016-03-01T23:22:57+00:00"

Concatenating the Canonicalized Resource Parts:

• Resource Template = PATH + QUERY + : + TIMESTAMP
• Resource (With Query) = "/api/v2/issues?id=SOME_ID#FOO:2016-03-01T23:22:57+00:00"
• Resource (Without Query) = "/api/v2/issues:2016-03-01T23:22:57+00:00"

X-Boomtown-Date

• Type: API key
• API key parameter name: X-Boomtown-Date
• Location: HTTP header
• Description: Will contain the current date+time in ISO8601 format

X-Boomtown-Token

• Type: API key
• API key parameter name: X-Boomtown-Token
• Location: HTTP header
• Description: Will contain your token/public key

X-Boomtown-Signature

• Type: API key
• API key parameter name: X-Boomtown-Signature
• Location: HTTP header
• Description: Will contain the signature generated from the Canonicalized Resource

Usage

Note: This version of the Boomtown Cloud SDK for PHP requires PHP 5.3 or greater.

Getting started, accessing basic data.

# Initialize the ApiClient
$apiClient = new ApiClient();

# Set your API credentials
$apiClient
    ->setApiToken("YOUR_BOOMTOWN_TOKEN")
    ->setApiSecret("YOUR_BOOMTOWN_SECRET");

# Instantiate the ProvidersApi
# **Note:** we need to provide the API ApiClient we configured above.
$providerApi = new ProvidersApi($apiClient);
try {
    # Request your Provider profile
    # Note: Results are always an array of 0 or more models
    # If you just want to get ritght at the data call the getResults method.
    $provider = $providerApi->getProvider()->getResults()[0];

    # Request your default team
    $defaultTeam = $providerApi->getProviderTeam(
        $provider->getDefaultPartnersTeamsId())->getResults()[0];

    # Get the raw response for the provider teams request
    $teamCollection = $providerApi->getProviderTeams();

    # Print only the array of ProviderTeam models
    print_r($teams->getResults()); echo "\n\n";
    
    # Get all of the your Merchants 
    $memberCollection = $providerApi->getProviderMembers();
    print_r($memberCollection->getResults()); echo "\n\n";

} catch (ApiException $e) {
    print_r($e->getResponseObject());
}

Working with Merchant Issues

# Instantiate the IssuesApi
# **Note:** we can reuse the ApiClient object created previously/above.
$issuesApi = new IssuesApi($apiClient);
try {
    $limit = 10;
    $start = 0;
    # Get a collection of all of the Issues you are managing
    $globalIssueCollection = $issuesApi
        ->getIssues($limit, $start)
        ->getResults();
    
    # Get a collection of Issues for a Merchant
    $merchantIssueCollection = $issuesApi
        ->getIssues($limit, $start, $merchantId)
        ->getResults();
    
    # Get a collection of all of the Issues for a Merchants User
    $userIssueCollection = $issuesApi
        ->getIssues($limit, $start, null, $merchantUserId)
        ->getResults();
    
    # Get a collection of all of the Issues for a Merchants Location
    # Result pagination defaults to a limit of 10 and starts from 0
    $locationIssueCollection = $issuesApi
        ->getIssues(null, null, null, null, $merchantLocationId)
        ->getResults();
    
    # Lets grab the first issue and do a few things with it
    $issue = $globalIssueCollection[0];
    
    # Lets log a note against this Issue
    $issuesApi->createIssueLog($issue->getId(), "Hi, this is a note");
    
    # Lets advance the Issues status to "Resolved"
    $issuesApi->resolveIssue($issue->getId());
    
    # Finally lets cancel the Issue
    $issuesApi->cancelIssue($issue->getId());

} catch (ApiException $e) {
    print_r($e->getResponseObject());
}

Creating a new Merchant and creating a new Issue for them

$merchantApi = new MerchantsApi($apiClient);
$issuesApi   = new IssuesApi($apiClient);
try {

    # First Lets create a new Merchant, 
    # we will simultaneously create a user and a location
    $merchantCreate = new MemberCreateRequest();

    # Instantiate the models
    $memberCreate
        ->setMembers(new Member())
        ->setMembersUsers(new MemberUser())
        ->setMembersLocations(new MemberLocation());

    $merchantCreate->getMembers()
        ->setName("A Merchant")
        ->setCity("San Francisco")
        ->setState("CA")
        ->setZipcode("94101")
        ->setEmail("[email protected]")
        ->setPhone("555 555 5555")
        ->setStreet1("123 Skylane");

    $merchantCreate->getMembersUsers()
        ->setFirstName("Bob")
        ->setLastName("Mango")
        ->setSmsNumber("999 999 9999")
        ->setEmail("[email protected]");

    $merchantCreate->getMembersLocations()
        ->setSiteName("A Merchant Mango")
        ->setCity("San Francisco")
        ->setState("CA")
        ->setZipcode("94101")
        ->setStreet1("Soma Lofts")
        ->setStreet2("#1337");

    # Ok, lets save it
    $merchantData = $merchantApi->createMember($merchantCreate)->getResults();

    # Use the new Merchant data to create a Issue
    $issue = new Issue();
    $issue->setMembersId($merchantData->getMember()->getId())
        ->setMembersLocationsId($merchantData->getMemberLocation()->getId())
        ->setMembersUsersId($merchantData->getMemberUser()->getId())
        ->setDetails("We would like to get WiFi installed here.")
        ->setType("Support");

    $issue = $issuesApi->createIssue($issue);

} catch (ApiException $e) {
    print_r($e->getResponseObject());
}

Cloud API documentation available at: http://developers.goboomtown.com/

License

Please see the license file for more information.