# Qssly Booking Engine — Full System Specifications and API Reference

This document compiles the complete developer reference, system architecture guidelines, database models, payment processes, and API contracts for Qssly Booking Engine. It is intended to serve as a comprehensive grounding source for AI coding systems.

---

## 1. Core Architecture Overview
Qssly is a headless scheduling and booking SaaS.

### Multi-Tenancy
Your tenant context is resolved automatically from your `X-API-Key`; API responses can never contain another organization's locations, resources, services, customers, or bookings. As an API consumer you do not manage this isolation; it is enforced by the engine on every query.

### Double Booking Prevention
Only `CONFIRMED` bookings consume a resource's capacity slots. Setting a booking's status to `CANCELLED` or `NO_SHOW` releases the slot immediately.
---

## 2. API Integrations

### Client API Authentication
All tenant endpoints require the `X-API-Key: qs_live_<key>` header. Admin / Customer rescheduling and cancellation endpoints require `Authorization: Bearer <JWT_TOKEN>`.

### Timezone Conversion Rule
Slots returned by `GET /availability` are in the location timezone (e.g. `Asia/Kolkata`). Clients **must** parse these and submit all bookings in UTC format.
- E.g. 09:00:00 local time in Kolkata (IST, UTC+5:30) must be converted and booked as 03:30:00 UTC (e.g., `2026-07-15T03:30:00Z`).

### Razorpay Payments Integration
1. Client POSTs a booking -> Returns booking details with `checkout_url` if payment is required.
2. If `checkout_url` exists, redirect client or open Razorpay Checkout SDK.
3. Backend exposes config via `GET /api/v1/payments/checkout-config/{booking_id}`.
4. Razorpay completes payment and sends a POST to our server or verified webhook handler.
5. Verification endpoint: `POST /api/v1/payments/verify-razorpay` verifies HMAC signature before confirming the booking.

### Webhook Signatures
Every event notification sends a POST request containing signature verification headers:
- `X-Qssly-Signature`: `sha256=<HMAC_HEX>`
- `X-Qssly-Idempotency-Key`: `<booking_id>:<event>:<timestamp>`

Signature is computed as:
```
HMAC-SHA256(webhook_secret, JSON.stringify(body, separators=(',',':'), sort_keys=True))
```

Webhook retry queue policies:
- If target endpoint returns non-2xx, system executes up to 5 retries with exponential backoff: `delay = 10 * 3^retry + random(0, 5)` seconds.
- Failed notifications will be dropped after the maximum number of retries.