Skip to content

Overview

Welcome to the Reserva API - a comprehensive multi-tenant booking platform designed for beauty salons, spas, and wellness businesses.

Quick Start

Get started with the API in minutes:

  1. Explore the API - Interactive Swagger UI documentation
  2. Read API Reference - Detailed ReDoc documentation
  3. Learn Tenant Management - Understand multi-tenant architecture
  4. Register Your Business - Use POST /api/v1/public/register to create your account

Architecture

Multi-Tenant Structure

The platform uses a two-level hierarchy designed for businesses with multiple locations:

graph TB
    Tenant[Tenant - Business Brand]
    Outlet1[Outlet 1]
    Outlet2[Outlet 2]
    Outlet3[Outlet 3]

    Tenant --> Outlet1
    Tenant --> Outlet2
    Tenant --> Outlet3

Key Principles:

  • Tenant Isolation - Complete data separation between tenants at database level
  • Outlet Distribution - Multiple physical locations per tenant
  • Role-Based Access - Granular permissions with 5 user roles
  • Subscription Tiers - Flexible plans from FREE to ENTERPRISE

Technology Stack

Component Technology
Framework FastAPI (Python 3.9+)
Database MongoDB with PyMongo Async
Authentication JWT + RBAC
Validation Pydantic v2
Payments Paper.id Integration
Documentation OpenAPI 3.0 (Swagger/ReDoc)

Core Features

Three Access Levels

The API is organized into three portals with different access requirements:

graph TB
    subgraph Staff[Staff Portal - JWT Required]
        S1[Tenant Management]
        S2[Appointment Management]
        S3[Reports & Analytics]
        S4[Merchant Withdrawals]
    end

    subgraph Customer[Customer Portal - Customer JWT]
        C1[Profile & Preferences]
        C2[Online Booking]
        C3[Payment Processing]
        C4[GDPR Controls]
    end

    subgraph Public[Public API - No Auth]
        P1[Browse Businesses]
        P2[View Services]
        P3[Check Availability]
        P4[Tenant Registration]
    end

🟧 Staff Portal

For business owners and staff

  • Tenant & outlet management
  • Staff scheduling and availability
  • Service catalog configuration
  • Appointment management
  • Reports & analytics
  • Merchant withdrawals
  • Platform fee configuration

Authentication: JWT token required

🟦 Customer Portal

For end customers

  • Self-registration (email/phone + OTP)
  • Profile & preference management
  • Consent & privacy controls (GDPR)
  • Online booking & rescheduling
  • Payment processing
  • Loyalty points & membership tiers
  • Appointment notifications

Authentication: Customer JWT token required

🟩 Public API

No authentication required

  • Browse businesses & outlets
  • View service catalogs
  • Check real-time availability
  • Read customer reviews
  • Get business hours
  • Tenant self-registration

Authentication: None (rate-limited)

API Organization

Endpoint Categories

🟧 Admin Portal

Category Endpoints Documentation Description
Authentication /api/v1/auth/* Guide Login, token refresh, password reset, multi-tenant auth
Tenants /api/v1/tenants/* Guide Tenant CRUD, statistics, settings, category templates
Subscriptions /api/v1/subscriptions/* Guide Plans (FREE/PRO/ENTERPRISE), upgrades, renewals, usage limits
Users /api/v1/users/* Guide Staff user accounts, roles, permissions
Outlets /api/v1/outlets/* Guide Location management, business hours, settings
Staff /api/v1/staff/* Guide Service providers, skills, availability, scheduling
Services /api/v1/services/* Guide Service catalog, pricing, categories, outlet pricing
Availability /api/v1/availability/* Guide Staff schedules, breaks, recurring patterns, conflict detection
Customers /api/v1/customers/* Guide Customer profiles, preferences, history, analytics
Appointments /api/v1/appointments/* Guide Booking management, status tracking, calendar, package credit redemption
Packages /api/v1/packages/* Guide Service bundles, credit system, discount calculation
Staff Customer Packages /api/v1/staff/customer-packages/* Guide Walk-in purchases, credit management, manual redemption

🟦 Customer Portal

Category Endpoints Documentation Description
Customer Auth /api/v1/customer/auth/* Guide Registration, login, OTP verification, password reset
Customer Profile /api/v1/customers/profile/* Guide Profile updates, preferences, consent, GDPR account deletion
Customer Booking /api/v1/customer/booking/* Guide Browse services, check availability, book appointments
Customer Payments /api/v1/customer/payments/* Guide Process payments, payment history, refunds
Token Usage /api/v1/token-usage/* Guide AI chat quota management, usage tracking, history
Customer Packages /api/v1/customer/packages/* Guide Browse packages, purchase, view credits
Package Payments /api/v1/customer/package-payments/* Guide Payment processing, payment links, status tracking

🟩 Public API

Category Endpoints Documentation Description
Public Business /api/v1/public/* Guide Browse businesses, services, tenant registration
Public Availability /api/v1/public/availability/* Guide Real-time availability grid for public booking

🔷 Shared Resources

Category Endpoints Documentation Description
Invoices /api/v1/invoices/* Guide Billing, receipts, payment tracking via Paper.id
Payment History /api/v1/payments/history/* Guide Payment history with dual authentication (staff/customer)

🔌 Integration

Category Endpoints Documentation Description
Webhooks /api/v1/webhooks/* Guide Payment callbacks, intelligent routing, subscription/appointment webhooks
Invoice Download /api/v1/invoices/*/download Guide PDF invoice generation and download

Authentication Flow

Staff Portal Authentication

sequenceDiagram
    User->>API: POST /api/v1/auth/login
    API->>User: Organizations list (if multiple)
    User->>API: POST /api/v1/auth/complete-login
    API->>User: JWT token with tenant context
    User->>API: Protected endpoints with Bearer token

Token Contains:

  • User ID and role
  • Tenant ID (for data isolation)
  • Outlet IDs (for access control)
  • 30-minute expiration

Customer Portal Authentication

sequenceDiagram
    Customer->>API: POST /api/v1/customer/auth/register
    API->>Customer: OTP sent (email/SMS)
    Customer->>API: POST /api/v1/customer/auth/verify-email
    API->>Customer: JWT token
    Customer->>API: Protected endpoints with Bearer token

Getting Started as a Business

graph LR
    A[Register] --> B[Login]
    B --> C[Create Outlets]
    C --> D[Add Services]
    D --> E[Create Staff]
    E --> F[Set Availability]
    F --> G[Start Booking]

1. Register Your Tenant

Endpoint: POST /api/v1/public/register

{
  "business_name": "Bella Vista Spa",
  "business_email": "contact@bellavista.com",
  "business_phone": "+1-555-987-6543",
  "admin_email": "admin@bellavista.com",
  "admin_password": "SecurePass123!",
  "terms_accepted": true
}

Response: Instant activation with tenant_id, slug, and client_partner_id (Paper.id)

2. Log In

Endpoint: POST /api/v1/auth/login

Use admin credentials from registration.

3. Set Up Your Business

  1. Create Outlets - POST /api/v1/outlets (add locations)
  2. Add Services - POST /api/v1/services (define service catalog)
  3. Create Staff - POST /api/v1/staff (add service providers)
  4. Set Availability - POST /api/v1/availability (configure schedules)
  5. Start Booking - Ready to accept appointments!

Getting Started as a Customer

graph LR
    A[Find Business] --> B[Register]
    B --> C[Setup Profile]
    C --> D[Browse Services]
    D --> E[Check Availability]
    E --> F[Create Booking]
    F --> G[Make Payment]
    G --> H[Confirmed]

1. Find a Business

Endpoint: GET /api/v1/public/outlets?city=New York

Browse businesses near you (no auth required).

2. Register & Setup Profile

Registration: POST /api/v1/customer/auth/register

Sign up with email or phone number.

Profile Setup (Optional): PUT /api/v1/customers/profile

Complete your profile with personal information, preferences, and privacy settings.

3. Book Appointment

  1. Browse Services - GET /api/v1/customer/booking/services
  2. Check Availability - GET /api/v1/customer/booking/available-slots
  3. Create Booking - POST /api/v1/customer/booking/appointments
  4. Make Payment - POST /api/v1/customer/payments/process-appointment

Package & Credit System

The platform includes a comprehensive package management system for selling service bundles:

graph LR
    A[Create Package] --> B[Customer Purchases]
    B --> C[Credits Activated]
    C --> D[Book with Credits]
    D --> E[Credits Redeemed]

Key Features:

  • Service Bundles - Create packages with multiple services at discounted prices
  • Credit System - Customers receive redeemable credits upon purchase
  • FIFO Redemption - Oldest credits used first to prevent expiration waste
  • Appointment Integration - Use credits directly when booking appointments
  • Subscription Limits - Package creation limits based on plan tier

Package Documentation:

Guide Description
Package Management Admin package creation and configuration
Staff Customer Package Management Staff-side operations and walk-in sales
Customer Package Management Customer self-service purchasing
Customer Package Payments Payment processing and status tracking
Appointment Credit Redemption Using credits for appointments

Payment Integration

The platform integrates with Paper.id payment gateway:

  • Automatic Setup - Partner account created on tenant registration
  • Invoice Generation - Automatic invoicing for appointments
  • Webhook Support - Real-time payment status updates
  • Merchant Payouts - Withdraw earnings with OTP verification
  • Platform Fees - Configurable fee structures

Webhook Events:

  • Payment success/failure
  • Invoice paid
  • Withdrawal processed

Subscription Plans

Plan Outlets Staff Appointments/Month Packages Items/Package
FREE 1 5 100 1 3
PRO 10 50 2,000 10 10
ENTERPRISE Unlimited Unlimited Unlimited 100 20

Upgrade anytime: POST /api/v1/subscriptions/upgrade

Note: Package payments are fee-exempt across all subscription tiers.

Security Features

  • JWT Authentication - Secure, stateless tokens for both staff and customers
  • RBAC - 5 user roles with granular permissions
  • Tenant Isolation - Complete data separation at database level
  • GDPR Compliance - Right to be forgotten, consent management, data portability
  • OWASP Headers - Security best practices implementation
  • Rate Limiting - API abuse prevention across all portals
  • Audit Logging - Comprehensive activity tracking for compliance
  • Webhook Signatures - HMAC-SHA256 verification (where supported)
  • Data Anonymization - Privacy-preserving deletion with business record retention

Documentation Resources

Interactive API Documentation

  • Swagger UI - Try endpoints with built-in request builder
  • ReDoc - Clean, searchable API reference

Admin Portal Guides

Customer Portal Guides

Public API Guides

Shared Resources Guides

Integration Guides

Code Examples

All endpoints include:

  • Request/response schemas
  • Example payloads
  • Error responses
  • Business rules documentation

Key Concepts

Tenant Isolation

Every API call operates within a tenant context. JWT tokens contain tenant_id to ensure:

  • Users only see their own tenant's data
  • Database queries automatically filter by tenant
  • Cross-tenant access is prevented

Outlet Assignment

Staff, services, and appointments are tied to specific outlets:

  • Staff can work at multiple outlets
  • Services can be available at specific outlets
  • Appointments are booked at a single outlet

Appointment Lifecycle

stateDiagram-v2
    [*] --> PENDING
    PENDING --> CONFIRMED: Payment received
    PENDING --> CANCELLED: User cancels
    CONFIRMED --> COMPLETED: Service done
    CONFIRMED --> NO_SHOW: Customer absent
    CONFIRMED --> CANCELLED: User cancels
    COMPLETED --> [*]
    CANCELLED --> [*]
    NO_SHOW --> [*]

Payment Flow

graph LR
    A[Appointment Created] --> B[Invoice Generated]
    B --> C[Payment Processed]
    C --> D[Merchant Balance Updated]

Rate Limiting

Portal Requests/Minute Requests/Hour
Staff Portal 100 1000
Customer Portal 60 600
Public API 30 300

Rate limit headers returned:

  • X-RateLimit-Limit-Minute
  • X-RateLimit-Remaining-Minute
  • X-RateLimit-Limit-Hour
  • X-RateLimit-Remaining-Hour

Support

Ready to build? Start with Tenant Registration or explore the API Reference.