Pipedrive Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require benhawker/pipedrive
   

   Add the package to your composer.json and run composer update.

2. Authentication:

   • Obtain your Pipedrive API key from Pipedrive Settings > API.
   • Initialize the client in a service provider or config file:

     $pipedrive = new \Benhawker\Pipedrive\Pipedrive('your_api_key_here');
     

3. First Use Case: Fetch a list of persons (contacts) to verify connectivity:

   $persons = $pipedrive->persons()->get();
   dd($persons['data']); // Inspect the response structure
   

Key Entry Points

• Resource Methods: Each CRM entity (e.g., persons, deals, notes) has CRUD methods (get(), add(), update(), delete()).
• Pagination: Use get() with start and limit params for large datasets:

  $pipedrive->persons()->get(['start' => 0, 'limit' => 50]);
  

• Error Handling: Wrap API calls in try-catch blocks to handle HTTP errors (e.g., 404 for missing records):

  try {
      $deal = $pipedrive->deals()->get(['id' => 123]);
  } catch (\Benhawker\Pipedrive\Exceptions\ApiException $e) {
      Log::error($e->getMessage());
  }
  

Implementation Patterns

Common Workflows

1. Data Synchronization:

   • Use get() to fetch records, then loop/update locally:

     $remotePersons = $pipedrive->persons()->get();
     foreach ($remotePersons['data'] as $person) {
         Person::updateOrCreate(
             ['local_id' => $person['id']],
             ['name' => $person['name']]
         );
     }
     

2. Deal Pipeline Automation:

   • Fetch deals by stage, then trigger actions (e.g., send emails):

     $openDeals = $pipedrive->deals()->get(['status' => 'won']);
     foreach ($openDeals['data'] as $deal) {
         Mail::to($deal['person_id'])->send(new DealWonEmail($deal));
     }
     

3. Activity Tracking:

   • Schedule recurring activities (e.g., follow-ups) using due_date:

     $activity = [
         'subject' => 'Follow-up Call',
         'type' => 'call',
         'person_id' => $personId,
         'due_date' => now()->addDays(7)->format('Y-m-d'),
     ];
     $pipedrive->activities()->add($activity);
     

Integration Tips

• Laravel Service Container: Bind the client in AppServiceProvider for dependency injection:

  $this->app->singleton(\Benhawker\Pipedrive\Pipedrive::class, function ($app) {
      return new \Benhawker\Pipedrive\Pipedrive(config('services.pipedrive.key'));
  });
  

  Then inject via constructor:

  public function __construct(private Pipedrive $pipedrive) {}
  

• Queued Jobs: Offload API calls to queues to avoid timeouts:

  SyncPipedriveData::dispatch($pipedrive)->onQueue('pipedrive');
  

• Webhooks: Use Pipedrive’s webhook system to push updates to your app (e.g., via Laravel’s HandleIncomingWebhook middleware).

Gotchas and Tips

Pitfalls

1. Rate Limiting:

   • Pipedrive enforces rate limits (e.g., 60 requests/minute).
   • Fix: Implement exponential backoff or use Laravel’s throttle middleware:

     Route::middleware(['throttle:60,1'])->group(...);
     

2. ID Mismatches:

   • Local IDs (e.g., person_id in your DB) ≠ Pipedrive IDs. Always validate:

     $pipedrivePerson = $pipedrive->persons()->get(['id' => $localPerson->pipedrive_id]);
     if (empty($pipedrivePerson['data'])) {
         throw new \Exception("Pipedrive ID {$localPerson->pipedrive_id} not found");
     }
     

3. File Uploads:

   • The library supports file uploads, but requires base64-encoded strings:

     $file = [
         'file' => base64_encode(file_get_contents('path/to/file.pdf')),
         'name' => 'contract.pdf',
         'deal_id' => 123,
     ];
     $pipedrive->files()->add($file);
     

   • Tip: Use Laravel’s Storage facade to handle encoding:

     $file['file'] = base64_encode(Storage::disk('local')->get('file.pdf'));
     

4. Soft Deletes:

   • Pipedrive uses deleted flag (not Laravel’s deleted_at). Filter queries:

     $activePersons = $pipedrive->persons()->get(['deleted' => 'false']);
     

Debugging

• Enable Debugging: Set the debug flag in the constructor to log raw API responses:

  $pipedrive = new \Benhawker\Pipedrive\Pipedrive('api_key', true);
  

  Check Laravel logs for client/server response details.

• Common Errors:

  • 401 Unauthorized: Verify API key permissions in Pipedrive.
  • 400 Bad Request: Validate required fields (e.g., person_id for notes).
  • 500 Server Error: Check Pipedrive’s status page.

Extension Points

1. Custom Endpoints:

   • Extend the library by creating a proxy class:

     class CustomPipedrive extends \Benhawker\Pipedrive\Pipedrive {
         public function customDeals() {
             return $this->request('GET', '/deals', ['custom_field' => 'value']);
         }
     }
     

2. Middleware:

   • Add request/response filters via Laravel middleware:

     $pipedrive->getMiddleware()->push(function ($request) {
         $request->query->set('expand', ['person', 'user']);
     });
     

3. Testing:

   • Mock the client in PHPUnit:

     $mock = Mockery::mock(\Benhawker\Pipedrive\Pipedrive::class);
     $mock->shouldReceive('persons->get')->andReturn(['data' => []]);
     $this->app->instance(\Benhawker\Pipedrive\Pipedrive::class, $mock);