Step by Step Guide to Building an Acuity Scheduling API Integration in PHP

Introduction

Hey there, fellow developer! Ready to supercharge your scheduling game? Let's dive into integrating the Acuity Scheduling API with PHP. This powerhouse combo will let you manage appointments like a pro, right from your own app. Buckle up!

Prerequisites

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

• A PHP environment (you're a pro, so I'm sure you've got this covered)
• An Acuity Scheduling account (if not, go grab one!)
• API credentials (we'll need these to make the magic happen)

Setting up the project

First things first, let's get our project structure in order:

1. Install Guzzle for handling HTTP requests:

   composer require guzzlehttp/guzzle
   

2. Create a basic PHP file structure. Nothing fancy, just something like:

   project/
   ├── src/
   │   └── AcuityClient.php
   └── composer.json
   

Authentication

Alright, time to get cozy with Acuity:

1. Grab your API key and User ID from your Acuity account.
2. In your AcuityClient.php, let's set up basic authentication:

use GuzzleHttp\Client;

class AcuityClient {
    private $client;
    private $userId;
    private $apiKey;

    public function __construct($userId, $apiKey) {
        $this->userId = $userId;
        $this->apiKey = $apiKey;
        $this->client = new Client([
            'base_uri' => 'https://acuityscheduling.com/api/v1/',
            'auth' => [$this->userId, $this->apiKey]
        ]);
    }
}

Making API requests

Now we're cooking! Let's add some methods to make API calls:

public function get($endpoint) {
    $response = $this->client->get($endpoint);
    return json_decode($response->getBody(), true);
}

public function post($endpoint, $data) {
    $response = $this->client->post($endpoint, ['json' => $data]);
    return json_decode($response->getBody(), true);
}

Core functionalities

Let's implement some key features:

Retrieving available appointment types

public function getAppointmentTypes() {
    return $this->get('appointment-types');
}

Fetching calendar availability

public function getAvailability($appointmentTypeId, $date) {
    return $this->get("availability/times?appointmentTypeID={$appointmentTypeId}&date={$date}");
}

Booking an appointment

public function bookAppointment($appointmentTypeId, $datetime, $firstName, $lastName, $email) {
    $data = [
        'appointmentTypeID' => $appointmentTypeId,
        'datetime' => $datetime,
        'firstName' => $firstName,
        'lastName' => $lastName,
        'email' => $email
    ];
    return $this->post('appointments', $data);
}

Canceling an appointment

public function cancelAppointment($appointmentId) {
    return $this->put("appointments/{$appointmentId}/cancel");
}

Error handling and response parsing

Let's add some error handling to our methods:

private function handleResponse($response) {
    $data = json_decode($response->getBody(), true);
    if ($response->getStatusCode() >= 400) {
        throw new Exception($data['message'] ?? 'An error occurred');
    }
    return $data;
}

Now update our get and post methods to use this:

public function get($endpoint) {
    $response = $this->client->get($endpoint);
    return $this->handleResponse($response);
}

public function post($endpoint, $data) {
    $response = $this->client->post($endpoint, ['json' => $data]);
    return $this->handleResponse($response);
}

Implementing webhooks (optional)

If you're feeling adventurous, set up a webhook endpoint in your app:

public function handleWebhook($payload) {
    $event = $payload['action'];
    switch ($event) {
        case 'scheduled':
            // Handle new appointment
            break;
        case 'canceled':
            // Handle cancellation
            break;
        // Add more cases as needed
    }
}

Testing the integration

Time to put our code through its paces:

$client = new AcuityClient('your-user-id', 'your-api-key');

// Get appointment types
$types = $client->getAppointmentTypes();
print_r($types);

// Book an appointment
$appointment = $client->bookAppointment(1, '2023-06-01 10:00:00', 'John', 'Doe', '[email protected]');
print_r($appointment);

Best practices and optimization

• Respect rate limits: Acuity has a limit of 100 requests per minute.
• Cache frequently accessed data like appointment types to reduce API calls.
• Use asynchronous requests for better performance when making multiple calls.

Conclusion

And there you have it! You've just built a solid Acuity Scheduling API integration in PHP. Pretty cool, right? Remember, this is just the beginning. There's a whole world of possibilities with this API, so don't be afraid to explore and expand on what we've done here.

For more in-depth info, check out the Acuity Scheduling API docs. Now go forth and schedule like a boss! 🚀