Bitrix24 Library Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require debishev/bitrix24-library
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Debishev\Bitrix24\Bitrix24ServiceProvider"
   

2. Configuration Edit config/bitrix24.php with your Bitrix24 credentials (webhook URL, API token, etc.):

   'webhook_url' => env('BITRIX24_WEBHOOK_URL'),
   'api_token' => env('BITRIX24_API_TOKEN'),
   

3. First Use Case: Fetching CRM Leads

   use Debishev\Bitrix24\Bitrix24;
   
   $bitrix = new Bitrix24(config('bitrix24.api_token'));
   $leads = $bitrix->crm()->leads()->get();
   

Implementation Patterns

Common Workflows

1. CRUD Operations Use the fluent API for common actions:

   // Create a lead
   $lead = $bitrix->crm()->leads()->add([
       'TITLE' => 'New Lead',
       'NAME' => 'John Doe',
   ]);
   
   // Update a lead
   $bitrix->crm()->leads()->update($lead['ID'], ['TITLE' => 'Updated Lead']);
   
   // Delete a lead
   $bitrix->crm()->leads()->delete($lead['ID']);
   

2. Webhook Handling Register a Laravel route to handle Bitrix24 webhook events:

   Route::post('/bitrix24/webhook', [Bitrix24WebhookController::class, 'handle']);
   

   Process events in the controller:

   public function handle(Request $request)
   {
       $bitrix = new Bitrix24(config('bitrix24.api_token'));
       $event = $bitrix->webhook()->parse($request->all());
   
       // Handle event (e.g., new lead)
       if ($event->type === 'lead.add') {
           // Logic here
       }
   }
   

3. Batch Operations Use the batch() method for bulk actions:

   $bitrix->crm()->leads()->batch([
       ['ID' => 1, 'TITLE' => 'Lead 1'],
       ['ID' => 2, 'TITLE' => 'Lead 2'],
   ])->update();
   

4. Integration with Laravel Models Extend a Laravel model to sync with Bitrix24:

   class Lead extends Model
   {
       public function syncToBitrix24()
       {
           $bitrix = new Bitrix24(config('bitrix24.api_token'));
           return $bitrix->crm()->leads()->add($this->toArray());
       }
   }
   

Gotchas and Tips

Pitfalls

1. API Rate Limits Bitrix24 enforces API call limits. Cache responses aggressively:

   $leads = Cache::remember('bitrix24_leads', now()->addHours(1), function () {
       return $bitrix->crm()->leads()->get();
   });
   

2. Webhook Verification Always verify webhook signatures to avoid spoofing:

   public function handle(Request $request)
   {
       if (!$bitrix->webhook()->verify($request->all())) {
           abort(403, 'Invalid webhook signature');
       }
   }
   

3. Field Mapping Bitrix24 uses custom field names (e.g., UF_CRM_123456). Ensure your config maps these correctly:

   'field_mappings' => [
       'custom_field' => 'UF_CRM_123456',
   ],
   

4. Error Handling Wrap API calls in try-catch blocks:

   try {
       $bitrix->crm()->leads()->add($data);
   } catch (\Debishev\Bitrix24\Exceptions\Bitrix24Exception $e) {
       Log::error('Bitrix24 error: ' . $e->getMessage());
   }
   

Tips

1. Logging Enable debug logging for API responses:

   $bitrix = new Bitrix24(config('bitrix24.api_token'), [
       'debug' => true,
   ]);
   

2. Testing Use the Bitrix24Mock class for unit tests:

   $mock = new Bitrix24Mock();
   $mock->shouldReceive('add')->andReturn(['ID' => 1]);
   

3. Extensions Override the Bitrix24 class to add custom methods:

   class CustomBitrix24 extends Bitrix24
   {
       public function customMethod()
       {
           return $this->call('custom.endpoint', []);
       }
   }
   

4. Documentation Refer to the Bitrix24 API docs for field names and endpoints. The package mirrors these closely.