Step by Step Guide to Building a ConnectWise Manage API Integration in PHP

Aug 16, 2024 • 8 minute read

Introduction

Hey there, fellow developer! Ready to dive into the world of ConnectWise Manage API integration? You're in for a treat. This guide will walk you through the process of building a robust integration using PHP. ConnectWise Manage's API is a powerful tool that'll let you automate tasks, sync data, and extend functionality. Let's get started!

Prerequisites

Before we jump in, make sure you've got:

A PHP environment up and running (PHP 7.4+ recommended)
A ConnectWise Manage account with API credentials

Got those? Great! Let's move on.

Setting Up the Development Environment

First things first, let's get our environment ready:

Install Guzzle (trust me, it'll make HTTP requests a breeze):
```
composer require guzzlehttp/guzzle
```

Set up your API authentication. Create a config.php file:

<?php
define('CW_COMPANY_ID', 'your_company_id');
define('CW_PUBLIC_KEY', 'your_public_key');
define('CW_PRIVATE_KEY', 'your_private_key');
define('CW_API_URL', 'https://api-na.myconnectwise.net/v4_6_release/apis/3.0/');

Making Your First API Request

Let's start with a simple GET request to fetch companies:

<?php
require 'vendor/autoload.php';
require 'config.php';

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => CW_API_URL,
    'headers' => [
        'Authorization' => 'Basic ' . base64_encode(CW_COMPANY_ID . '+' . CW_PUBLIC_KEY . ':' . CW_PRIVATE_KEY),
        'Content-Type' => 'application/json',
    ],
]);

$response = $client->get('company/companies');
$companies = json_decode($response->getBody(), true);

print_r($companies);

Run this, and you should see a list of companies. Exciting, right?

CRUD Operations

Now that we've got our feet wet, let's dive into CRUD operations:

Create (POST)

$newCompany = [
    'name' => 'Acme Corp',
    'identifier' => 'AcmeCorp',
];

$response = $client->post('company/companies', ['json' => $newCompany]);
$createdCompany = json_decode($response->getBody(), true);

Read (GET)

We've already done this, but here's a more specific example:

$response = $client->get('company/companies/123'); // Replace 123 with an actual ID
$company = json_decode($response->getBody(), true);

Update (PUT/PATCH)

$updatedData = ['name' => 'Acme Corporation'];
$response = $client->patch('company/companies/123', ['json' => $updatedData]);

Delete (DELETE)

$response = $client->delete('company/companies/123');

Working with Specific Modules

ConnectWise Manage has various modules. Here's how to work with a few:

Tickets

// Create a ticket
$newTicket = [
    'summary' => 'New feature request',
    'board' => ['id' => 1],
    'company' => ['id' => 123],
];
$response = $client->post('service/tickets', ['json' => $newTicket]);

// Get all tickets
$response = $client->get('service/tickets');
$tickets = json_decode($response->getBody(), true);

Time Entries

// Create a time entry
$newTimeEntry = [
    'chargeToId' => 123, // Ticket ID
    'chargeToType' => 'ServiceTicket',
    'timeStart' => '2023-05-01T09:00:00Z',
    'timeEnd' => '2023-05-01T10:00:00Z',
    'notes' => 'Worked on feature implementation',
];
$response = $client->post('time/entries', ['json' => $newTimeEntry]);

Error Handling and Best Practices

Always wrap your API calls in try-catch blocks:

try {
    $response = $client->get('company/companies');
} catch (\GuzzleHttp\Exception\RequestException $e) {
    if ($e->hasResponse()) {
        $errorBody = json_decode($e->getResponse()->getBody(), true);
        echo "API Error: " . $errorBody['message'];
    } else {
        echo "Network Error: " . $e->getMessage();
    }
}

For rate limits, implement exponential backoff:

function makeRequestWithRetry($client, $method, $endpoint, $options = [], $maxRetries = 3) {
    for ($i = 0; $i < $maxRetries; $i++) {
        try {
            return $client->$method($endpoint, $options);
        } catch (\GuzzleHttp\Exception\ClientException $e) {
            if ($e->getResponse()->getStatusCode() == 429) {
                $waitTime = pow(2, $i);
                sleep($waitTime);
            } else {
                throw $e;
            }
        }
    }
    throw new \Exception("Max retries reached");
}

Advanced Topics

ConnectWise uses page and pageSize parameters:

$response = $client->get('company/companies', [
    'query' => ['page' => 1, 'pageSize' => 50]
]);

Filtering

Use the conditions parameter:

$response = $client->get('company/companies', [
    'query' => ['conditions' => 'name like "Acme%"']
]);

Webhooks

To receive updates, set up a webhook endpoint in your application and configure it in ConnectWise Manage.

Testing and Debugging

Always write unit tests for your integration. Here's a simple example using PHPUnit:

use PHPUnit\Framework\TestCase;

class ConnectWiseIntegrationTest extends TestCase
{
    public function testGetCompanies()
    {
        // Your test code here
    }
}

Conclusion

Congratulations! You've just built a ConnectWise Manage API integration in PHP. Remember, this is just the beginning. There's so much more you can do with this powerful API. Keep exploring, keep coding, and most importantly, have fun!

Additional Resources

Now go forth and integrate! You've got this! 🚀