AI-Enabled Booking System: Requirements & Flow

Mandatory Technical Requirements

1. REST API with JSON

• Standard HTTP methods (GET, POST, PUT, DELETE)
• JSON request/response format
• Predictable URL structure

2. OpenAPI 3.0+ Specification

• Machine-readable API documentation
• Detailed descriptions for endpoints, parameters, responses
• Example requests/responses included
• Error codes documented

3. Authentication System

• API keys for guest bookings (public key for AI agents)
• OAuth 2.0 for authenticated user bookings (future phase)
• Rate limiting per IP/key

4. Core API Endpoints

Public Discovery (No Auth):

• GET /api/ai/v1/search - Search salons by location, service, price, date
• GET /api/ai/v1/salons/{id} - Get salon details
• GET /api/ai/v1/availability - Check available time slots

Guest Booking (Public API Key):

• POST /api/ai/v1/bookings - Create provisional booking
• GET /api/ai/v1/bookings/{id} - Check booking status

5. Payment Integration

• Stripe Checkout for PCI/PSD2 compliance
• Configurable deposit amounts (per salon)
• 15-30 minute payment window for provisional bookings
• Automatic slot release on payment timeout

6. Error Handling

• Standard HTTP status codes
• Structured error messages with actionable guidance
• Validation errors explaining issues clearly

7. Public Documentation Site

• Human and AI-readable API documentation
• Getting started guide
• SEO-optimized for AI crawler discovery
• Code examples in multiple languages

8. Idempotency

• Idempotency keys for POST requests
• Prevent duplicate bookings from retries

---

User Booking Flow

Scenario: User asks AI for haircut in Brighton under £100

Step 1: Discovery

User → AI: "Find me a haircut in Brighton tomorrow under £100"
AI → Calls GET /api/ai/v1/search?location=brighton&service=haircut&max_price=100&date=tomorrow
API → Returns 3-5 matching salons with prices, ratings, availability
AI → Presents options to user

Step 2: Selection

User → AI: "Book the 2pm slot at Trendy Cuts"
AI → Calls POST /api/ai/v1/bookings with:
  - salon_id, service_id, datetime
  - customer email, name, phone
  - source: "chatgpt" or "claude"
  - idempotency_key

Step 3: Provisional Booking Created

API → Returns:
{
  "booking_id": "bkg_789",
  "status": "pending_payment",
  "expires_at": "2025-10-15T14:15:00Z",  // 15 min hold
  "deposit_amount": 10.00,
  "total_amount": 45.00,
  "payment_url": "https://marketplace.com/pay/bkg_789"
}

AI → User: "I've reserved your 2pm slot. Complete the £10 deposit to confirm: [payment link]"

Step 4: Payment

User → Clicks payment link
Browser → Opens Stripe Checkout (mobile-optimized)
User → Completes payment with Apple Pay/Google Pay/Card (includes 3D Secure)
Stripe → Webhook confirms payment to system
System → Updates booking status to "confirmed"

Step 5: Confirmation

System → Sends email to customer with:
  - Booking details (salon, time, service, price)
  - Confirmation code
  - Calendar invite (.ics file)
  - Manage booking link
  - Salon contact info

AI → Receives webhook/status check
AI → User: "Confirmed! Your haircut at Trendy Cuts is booked for tomorrow at 2pm. Confirmation code: ABC123. Check your email for details."

Step 6: Reminder & Management

System → Sends reminder email 24h before
User → Can modify/cancel via link in email (cancellation policy applies)

---

Payment Model Options

Option A: Deposit Required (Recommended)

• £10 deposit via Stripe at booking time
• Remaining £35 paid at salon
• Deposit forfeited if no-show/late cancellation
• Lower barrier to booking

Option B: Full Payment

• £45 charged upfront
• Refund policy for cancellations
• Higher security for salons
• May reduce conversion

Configuration

• Let salons configure their deposit policy per service
• High-demand slots can require deposits
• Off-peak slots may have zero deposit

---

AI Marketplace Presence

Phase 1: Platform Publishing

• ChatGPT GPT Store: Publish custom GPT "UK Salon Booking"
• Claude MCP Marketplace: Publish MCP server (when available)
• AI Tool Directories: List on AI agent discovery sites

Phase 2: Discoverability

• SEO-optimized API documentation
• Submit sitemap to search engines and AI crawlers
• Public OpenAPI spec for autonomous discovery

---

Data Tracked

Per Booking:

• Source (ChatGPT, Claude, Gemini, Perplexity, other)
• Customer details (email, name, phone)
• Salon and service selected
• Payment status and amount
• Timestamps (created, paid, confirmed)

Analytics:

• Bookings from AI vs web vs app
• Conversion rates by AI platform
• Most popular AI-requested services
• Revenue from AI channel

---

Security & Compliance

Rate Limiting:

• Search API: 100 requests/min per IP
• Booking API: 10 bookings/hour per IP

PCI Compliance:

• All payment handling via Stripe
• No card data stored on our servers

PSD2/SCA Compliance:

• 3D Secure authentication via Stripe Checkout
• Strong customer authentication for all payments

Data Protection:

• Customer email required for booking confirmation
• GDPR-compliant data handling
• Opt-in for marketing communications

---

Technical Stack Considerations

• API Framework: RESTful, versioned (/api/ai/v1)
• Documentation: Swagger/OpenAPI 3.0+, hosted publicly
• Payment: Stripe Checkout with webhooks
• Auth: API keys (guest), OAuth 2.0 (authenticated users - future)
• Rate Limiting: IP-based with configurable thresholds
• Monitoring: Track API usage, errors, conversion rates by source

---

Success Metrics

• Number of AI-initiated bookings per month
• Conversion rate (search → provisional booking → paid booking)
• Revenue from AI channel
• User satisfaction (post-booking survey)
• Salon adoption of AI booking features