Open Belasting Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer in your Laravel/Symfony project:

   composer require common-gateway/open-belasting-bundle
   

   Register the bundle in config/bundles.php (Symfony) or config/app.php (Laravel via Symfony bridge):

   CommonGateway\OpenBelastingBundle\OpenBelastingBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="CommonGateway\OpenBelastingBundle\OpenBelastingBundle" --tag="config"
   

   Update .env with your API credentials:

   OPEN_BELASTING_API_KEY=your_api_key
   OPEN_BELASTING_BASE_URL=https://api.openbelastingen.nl
   

3. First Use Case: Fetching an Assessment Use the AssessmentClient service to retrieve an assessment:

   use CommonGateway\OpenBelastingBundle\Client\AssessmentClient;
   
   $assessmentClient = app(AssessmentClient::class);
   $assessment = $assessmentClient->getAssessment('123456789'); // BSN or tax ID
   

Implementation Patterns

Core Workflows

1. Fetching Assessments

   • Use AssessmentClient for single assessments or AssessmentCollectionClient for bulk operations.
   • Example: Fetch all assessments for a given year:

     $assessments = $assessmentClient->getAssessmentsByYear('123456789', 2023);
     

2. Submitting Objections

   • Use ObjectionClient to create or update objections:

     $objection = new Objection();
     $objection->setAssessmentId('ASS_123');
     $objection->setReason('Disagreement with tax calculation');
     $objectionClient = app(ObjectionClient::class);
     $objectionClient->submitObjection($objection);
     

3. Event-Driven Integrations

   • Listen to AssessmentFetchedEvent or ObjectionSubmittedEvent for real-time processing:

     // In a Symfony event subscriber (Laravel: use Laravel's event system)
     public function onAssessmentFetched(AssessmentFetchedEvent $event) {
         $assessment = $event->getAssessment();
         // Process or log the assessment
     }
     

Integration Tips

• Laravel-Specific: Use the Symfony bridge (symfony/flex) to integrate with Laravel’s service container.

  // In AppServiceProvider@boot()
  $this->app->register(new \CommonGateway\OpenBelastingBundle\OpenBelastingBundle());
  

• API Rate Limiting: Implement a queue (e.g., Laravel Queues) for bulk operations to avoid hitting API limits.
• Caching: Cache responses for frequently accessed assessments:

  $assessment = Cache::remember("assessment_{$bsn}", now()->addHours(1), function() use ($assessmentClient, $bsn) {
      return $assessmentClient->getAssessment($bsn);
  });
  

Gotchas and Tips

Pitfalls

1. API Key Management

   • Never hardcode API keys. Use Laravel’s .env or Symfony’s %env(resolve:...)% in config.
   • Rotate keys periodically and revoke old ones in the Open Belastingen dashboard.

2. Schema Mismatches

   • The bundle uses strict DTOs (Data Transfer Objects) for requests/responses. Validate input data before submission:

     if (!$objection->isValid()) {
         throw new \InvalidArgumentException('Invalid objection data: ' . $objection->getErrors());
     }
     

3. Idempotency

   • The API may not guarantee idempotency for all endpoints. Use unique identifiers (e.g., UUIDs) for critical operations.

4. Error Handling

   • Wrap API calls in try-catch blocks to handle OpenBelastingApiException:

     try {
         $assessment = $assessmentClient->getAssessment($bsn);
     } catch (OpenBelastingApiException $e) {
         Log::error('Failed to fetch assessment: ' . $e->getMessage());
         // Retry or notify admin
     }
     

Debugging

• Enable API Logging: Set debug: true in config to log all API requests/responses.
• Postman Collection: The bundle includes a Postman collection in /resources/postman. Import it for manual testing.

Extension Points

1. Custom Mappings

   • Extend AssessmentMapper or ObjectionMapper to transform data before/after API calls:

     class CustomAssessmentMapper extends AssessmentMapper {
         public function mapToDto(array $data): AssessmentDto {
             $dto = parent::mapToDto($data);
             $dto->setCustomField($data['custom_field']);
             return $dto;
         }
     }
     

   • Register your mapper in the bundle’s config:

     services:
         CommonGateway\OpenBelastingBundle\Mapper\AssessmentMapper:
             class: App\CustomAssessmentMapper
     

2. Webhooks

   • Implement a webhook endpoint to receive real-time updates from Open Belastingen (if supported):

     Route::post('/open-belasting/webhook', [OpenBelastingWebhookController::class, 'handle']);
     

3. Testing

   • Use the OpenBelastingBundleTestCase base class for unit/integration tests:

     use CommonGateway\OpenBelastingBundle\Tests\OpenBelastingBundleTestCase;
     
     class MyTest extends OpenBelastingBundleTestCase {
         public function testAssessmentFetch() {
             // Mock API responses here
         }
     }