diff --git a/docs/API_VALIDATION_STAGE_PLAN.md b/docs/API_VALIDATION_STAGE_PLAN.md
new file mode 100644
index 0000000..782cc33
--- /dev/null
+++ b/docs/API_VALIDATION_STAGE_PLAN.md
@@ -0,0 +1,395 @@
+# API Availability Validation Stage - Implementation Plan
+
+## Overview
+
+This document outlines the planned implementation of a final validation stage that will verify service availability against real-time BusProNet API data before booking confirmation. This enhancement will complement the existing dynamic availability system by providing authoritative validation against live data.
+
+## Business Context
+
+### Current State
+- **Dynamic Availability System**: Prevents overbooking within single booking sessions using XML data
+- **XML Data Limitations**: Availability data may become outdated during booking creation process
+- **Session-Scoped Protection**: Current system only tracks availability within individual booking workflows
+
+### Business Need
+- **Real-Time Validation**: Ensure final service selections are valid against current API state
+- **Cross-Session Integrity**: Prevent conflicts between multiple concurrent booking sessions
+- **Authoritative Source**: Use BusProNet API as single source of truth for final validation
+- **User Experience**: Provide clear feedback when services become unavailable
+
+## Technical Architecture
+
+### Validation Flow
+
+```
+Current Flow:
+XML Data → Dynamic Availability → Form Validation → Booking Submission
+
+Planned Flow:
+XML Data → Dynamic Availability → Form Validation → API Validation → Booking Submission
+```
+
+### Integration Points
+
+#### 1. Pre-Submission Validation Hook
+```php
+// Planned integration in booking workflow
+class BookingController
+{
+ public function confirmBooking(BookingCreateDto $bookingDto): Response
+ {
+ // Step 1: Standard form validation
+ $formErrors = $this->validateForm($bookingDto);
+ if (!empty($formErrors)) {
+ return $this->handleFormErrors($formErrors);
+ }
+
+ // Step 2: API availability validation (NEW)
+ $apiValidation = $this->bookingValidationService->validateServiceAvailability($bookingDto);
+ if (!$apiValidation->isValid()) {
+ return $this->handleAvailabilityConflicts($apiValidation);
+ }
+
+ // Step 3: Submit to BPN API
+ return $this->submitBooking($bookingDto);
+ }
+}
+```
+
+#### 2. Validation Service Architecture
+```php
+interface BookingValidationServiceInterface
+{
+ public function validateServiceAvailability(BookingCreateDto $bookingDto): ValidationResult;
+ public function resolveAvailabilityConflicts(BookingCreateDto $bookingDto): ConflictResolution;
+ public function getAlternativeServices(Service $unavailableService): array;
+}
+
+class BookingValidationService implements BookingValidationServiceInterface
+{
+ public function __construct(
+ private readonly BusProNetApiClient $apiClient,
+ private readonly ServiceAvailabilityCalculator $availabilityCalculator,
+ private readonly ConflictResolver $conflictResolver
+ ) {}
+}
+```
+
+#### 3. Validation Result Handling
+```php
+class ValidationResult
+{
+ public function __construct(
+ private readonly bool $isValid,
+ private readonly array $conflicts = [],
+ private readonly array $warnings = []
+ ) {}
+
+ public function isValid(): bool;
+ public function getConflicts(): array;
+ public function hasWarnings(): bool;
+ public function getWarnings(): array;
+}
+
+class AvailabilityConflict
+{
+ public function __construct(
+ private readonly Service $service,
+ private readonly int $requestedQuantity,
+ private readonly int $actualAvailability,
+ private readonly array $affectedParticipants
+ ) {}
+}
+```
+
+## Implementation Strategy
+
+### Phase 1: Foundation (Week 1)
+- **API Integration**: Enhance BusProNet API client with availability checking endpoints
+- **Validation Models**: Create validation result and conflict data structures
+- **Service Architecture**: Implement core BookingValidationService
+
+### Phase 2: Conflict Resolution (Week 2)
+- **Conflict Detection**: Identify which services have availability issues
+- **Resolution Strategies**: Implement automatic and manual conflict resolution
+- **Alternative Suggestions**: Provide similar service recommendations
+
+### Phase 3: User Experience (Week 3)
+- **Error Handling**: Graceful handling of availability conflicts
+- **User Interface**: Clear messaging and resolution options
+- **Progressive Enhancement**: Maintain functionality if API is unavailable
+
+### Phase 4: Integration & Testing (Week 4)
+- **Booking Flow Integration**: Wire validation into existing booking controllers
+- **Comprehensive Testing**: Test various conflict scenarios
+- **Performance Optimization**: Ensure validation doesn't impact user experience
+
+## User Experience Design
+
+### Conflict Resolution Scenarios
+
+#### Scenario 1: Service No Longer Available
+```
+User Action: Submits booking with "Advanced Ski Course" selected
+API Response: Advanced Ski Course is fully booked
+System Response:
+ - Show clear error message
+ - Suggest alternative courses
+ - Allow user to modify selection or cancel
+```
+
+#### Scenario 2: Reduced Availability
+```
+User Action: Books 3 participants for "Equipment Rental"
+API Response: Only 2 rental sets available
+System Response:
+ - Inform user of reduced availability
+ - Offer options: reduce participants or find alternatives
+ - Update pricing accordingly
+```
+
+#### Scenario 3: Multiple Conflicts
+```
+User Action: Complex booking with several service conflicts
+API Response: Multiple services have availability issues
+System Response:
+ - Prioritize conflicts by impact
+ - Provide batch resolution options
+ - Guide user through step-by-step resolution
+```
+
+### Error Messages & UI
+
+#### Clear Communication
+```html
+
+
Availability Update Required
+
Some services in your booking are no longer available:
+
+
+
+ Advanced Ski Course
+ Fully booked
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+## API Integration Details
+
+### BusProNet API Enhancements
+
+#### New Endpoint Requirements
+```php
+// Required API capabilities
+interface BusProNetAvailabilityApi
+{
+ /**
+ * Check real-time availability for multiple services
+ */
+ public function checkServiceAvailability(array $serviceIds, \DateTimeImmutable $travelDate): array;
+
+ /**
+ * Reserve services temporarily during booking process
+ */
+ public function reserveServices(array $selections, int $reservationMinutes = 15): ReservationResult;
+
+ /**
+ * Get alternative services for unavailable selections
+ */
+ public function findAlternativeServices(Service $unavailableService): array;
+}
+```
+
+#### API Call Optimization
+- **Batch Requests**: Check multiple services in single API call
+- **Caching Strategy**: Cache availability data for short periods (1-2 minutes)
+- **Timeout Handling**: Graceful degradation if API is slow/unavailable
+- **Rate Limiting**: Respect API rate limits to avoid service disruption
+
+## Data Flow & Processing
+
+### Validation Pipeline
+
+```
+1. Booking Submission
+ ↓
+2. Extract Service Selections
+ ↓
+3. Group by Service Type
+ ↓
+4. API Availability Check (Batched)
+ ↓
+5. Compare Requested vs Available
+ ↓
+6. Generate Conflict Report
+ ↓
+7. Resolve or Present to User
+ ↓
+8. Continue with Booking Submission
+```
+
+### Performance Considerations
+
+#### Optimization Strategies
+- **Parallel Processing**: Check different service types concurrently
+- **Smart Caching**: Cache recent availability checks
+- **Incremental Validation**: Only validate changed services
+- **Background Refresh**: Update availability data in background
+
+#### Fallback Mechanisms
+- **API Timeout**: Continue with booking if API unavailable (with warning)
+- **Partial Validation**: Validate what's possible, warn about unvalidated services
+- **Manual Override**: Allow staff to override validation in exceptional cases
+
+## Error Handling & Edge Cases
+
+### API Failure Scenarios
+- **Connection Timeout**: Use cached data with warning message
+- **Authentication Issues**: Log error, allow booking with notification
+- **Rate Limiting**: Queue validation or use exponential backoff
+- **Invalid Response**: Parse what's possible, warn about remainder
+
+### Data Consistency Issues
+- **Service ID Mismatch**: Handle cases where XML and API have different service IDs
+- **Availability Calculation Errors**: Provide conservative estimates
+- **Concurrent Bookings**: Handle race conditions gracefully
+
+### User Experience Fallbacks
+- **Progressive Enhancement**: Core booking works even if validation fails
+- **Clear Status Indicators**: Show validation status to users
+- **Manual Verification**: Provide staff tools for manual validation
+
+## Testing Strategy
+
+### Unit Testing
+- **Validation Logic**: Test conflict detection and resolution algorithms
+- **API Integration**: Mock API responses for various scenarios
+- **Edge Cases**: Test timeout, error, and edge case handling
+
+### Integration Testing
+- **End-to-End Flow**: Test complete booking workflow with validation
+- **API Mocking**: Simulate various API response scenarios
+- **Performance Testing**: Ensure validation doesn't slow booking process
+
+### Manual Testing Scenarios
+1. **Happy Path**: All services available, validation passes
+2. **Single Conflict**: One service unavailable, resolution works
+3. **Multiple Conflicts**: Complex conflicts resolved appropriately
+4. **API Failure**: Graceful degradation when API unavailable
+5. **Performance**: Validation completes within acceptable timeframe
+
+## Security & Compliance
+
+### Data Protection
+- **Sensitive Data**: Ensure booking data is properly encrypted during API calls
+- **Logging**: Log validation events without exposing personal information
+- **Audit Trail**: Maintain records of validation decisions for compliance
+
+### API Security
+- **Authentication**: Secure API communication with proper credentials
+- **Rate Limiting**: Respect API limits to maintain service availability
+- **Error Handling**: Don't expose sensitive API details in user-facing errors
+
+## Monitoring & Observability
+
+### Key Metrics
+- **Validation Success Rate**: Percentage of bookings passing validation
+- **Conflict Rate**: How often availability conflicts occur
+- **Resolution Rate**: How often conflicts are successfully resolved
+- **API Performance**: Response times and error rates
+
+### Logging Strategy
+```php
+// Planned logging approach
+$this->logger->info('Booking validation started', [
+ 'booking_id' => $bookingDto->id,
+ 'service_count' => count($selectedServices),
+ 'participant_count' => count($bookingDto->participants)
+]);
+
+$this->logger->warning('Availability conflict detected', [
+ 'service_id' => $service->id,
+ 'service_name' => $service->label,
+ 'requested' => $requestedQuantity,
+ 'available' => $actualAvailability
+]);
+```
+
+## Future Enhancements
+
+### Advanced Features
+- **Predictive Availability**: Use historical data to predict availability issues
+- **Smart Alternatives**: Machine learning-based service recommendations
+- **Real-time Updates**: WebSocket integration for live availability updates
+- **Mobile Optimization**: Optimized validation flow for mobile devices
+
+### Business Intelligence
+- **Demand Analytics**: Track which services have highest conflict rates
+- **Optimization Insights**: Identify opportunities to improve availability management
+- **Customer Behavior**: Analyze how users respond to availability conflicts
+
+## Implementation Timeline
+
+### Sprint 1: Foundation (2 weeks)
+- API client enhancements
+- Core validation service
+- Basic conflict detection
+
+### Sprint 2: User Experience (2 weeks)
+- Conflict resolution UI
+- Error handling and messaging
+- Alternative service suggestions
+
+### Sprint 3: Integration (1 week)
+- Booking flow integration
+- Performance optimization
+- Comprehensive testing
+
+### Sprint 4: Monitoring & Refinement (1 week)
+- Logging and monitoring setup
+- Performance tuning
+- Documentation and training
+
+## Success Criteria
+
+### Technical Success
+- ✅ API validation integrated without performance degradation
+- ✅ Conflict resolution success rate > 90%
+- ✅ Validation response time < 2 seconds
+- ✅ Graceful handling of API failures
+
+### Business Success
+- ✅ Reduced booking conflicts and customer complaints
+- ✅ Improved booking completion rates
+- ✅ Better inventory management and utilization
+- ✅ Enhanced customer experience and satisfaction
+
+### User Experience Success
+- ✅ Clear, actionable error messages
+- ✅ Intuitive conflict resolution workflow
+- ✅ Minimal additional steps for successful bookings
+- ✅ Accessible design for all user types
+
+---
+
+**Planning Status**: 📋 **Documented and Ready for Implementation**
+**Priority**: 🔥 **High - Critical for Production Reliability**
+**Estimated Effort**: 6 weeks (Foundation + UX + Integration + Testing)
+**Dependencies**: Enhanced BusProNet API, existing availability system
+**Risk Level**: Medium (API integration complexity)
+
+**Next Steps**:
+1. Stakeholder review and approval
+2. API specification with BusProNet team
+3. Technical spike for proof of concept
+4. Implementation sprint planning
\ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
index 5d46d04..4187f58 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -228,6 +228,7 @@ bin/console debug:container ServiceAvailabilityCalculator
- **Mobile Optimization**: Responsive design improvements
- **Analytics Integration**: User behavior tracking
- **Cross-Session Availability**: Extend availability tracking beyond single sessions
+- **API Availability Validation**: Implement final validation stage against BusProNet API before booking confirmation
### Technical Debt
- **Code Coverage**: Increase test coverage to 90%+
@@ -235,6 +236,7 @@ bin/console debug:container ServiceAvailabilityCalculator
- **Documentation**: API endpoint documentation
- **Monitoring**: Enhanced logging and metrics
- **Availability Testing**: Comprehensive test coverage for availability system
+- **API Validation Integration**: Implement real-time availability validation via BusProNet API
---
diff --git a/docs/SERVICE_AVAILABILITY_SYSTEM.md b/docs/SERVICE_AVAILABILITY_SYSTEM.md
index 26846f2..9fe1510 100644
--- a/docs/SERVICE_AVAILABILITY_SYSTEM.md
+++ b/docs/SERVICE_AVAILABILITY_SYSTEM.md
@@ -330,6 +330,35 @@ dump($filtered);
- **HTMX Updates**: Availability changes trigger form refreshes
- **Form Handlers**: Service selections processed by specialized field handlers
+## Future Enhancements
+
+### Planned: API Validation Stage
+
+**Important Note**: The current availability system uses XML data that may become outdated during the booking creation process. A future enhancement will implement a **validation stage** that checks final service selections against real-time availability via the BusProNet API before final booking confirmation.
+
+#### Planned Implementation
+- **Pre-Submission Validation**: Before final booking submission, validate all selected services against current API availability
+- **Real-Time Check**: Call BusProNet API to get current availability status
+- **Conflict Resolution**: Handle cases where selected services are no longer available
+- **User Feedback**: Provide clear messaging when services become unavailable during booking process
+
+#### Technical Integration Points
+```php
+// Future validation service (planned)
+class BookingValidationService
+{
+ public function validateServiceAvailability(BookingCreateDto $bookingDto): ValidationResult;
+ public function resolveAvailabilityConflicts(BookingCreateDto $bookingDto): ConflictResolution;
+}
+```
+
+#### Business Logic
+- **Session Availability**: Current system prevents overbooking within single booking session
+- **API Validation**: Future system will prevent overbooking across all booking sessions system-wide
+- **Two-Stage Protection**: Provides both immediate feedback and final validation
+
+This planned enhancement will complement the existing dynamic availability system by adding a final validation layer that ensures booking integrity against the authoritative BusProNet API data.
+
---
**Implementation Status**: ✅ **Completed and Tested**
@@ -337,4 +366,5 @@ dump($filtered);
**Integration**: Seamless with existing form system
**Performance**: Optimized for real-time updates
**Testing**: Verified working in development environment
+**Future Enhancement**: API validation stage planned for booking finalization
**Documentation**: Comprehensive with examples and troubleshooting
\ No newline at end of file