Qssly Developer Hub

// Response shape:
{
  "items": [
    {
      "id": "2f7157ca-3edf-4ef4-90c6-bb0a5ed87848",
      "name": "Deluxe Suite 101",
      "location_id": "a1b2c3d4-...",
      "capacity": 2,
      "metadata_schema": null,
      "tenant_id": "...",
      "created_at": "2026-06-20T10:00:00Z",
      "updated_at": "2026-06-20T10:00:00Z"
    }
  ],
  "total": 12,
  "page": 1,
  "page_size": 20,
  "pages": 1
}

// Response shape:
{
  "items": [
    {
      "id": "8b9e67d2-38ef-4171-aa31-50e5671192e8",
      "name": "Standard Night Stay",
      "duration_minutes": 1440,       // 24 hours = 1 night
      "buffer_minutes": 180,          // 3-hour gap between stays (cleaning)
      "price": 2500.00,
      "currency": "INR",
      "payment_type": "FULL_ADVANCE", // FULL_ADVANCE | PARTIAL_ADVANCE | PAY_LATER
      "advance_payment_amount": null, // Only set when PARTIAL_ADVANCE
      "cancellation_cutoff_hours": 24  // Can cancel up to 24h before
    }
  ]
}

GET /api/v1/availability?resource_id={room_id}&service_id={stay_service_id}&start_date=2026-07-01&end_date=2026-07-04

Response:
{
  "resource_id": "2f7157ca-...",
  "service_id": "8b9e67d2-...",
  "timezone": "Asia/Kolkata",
  "slots": [
    { "date": "2026-07-01", "times": ["14:00"] },  ← Available (check-in at 2 PM)
    { "date": "2026-07-02", "times": ["14:00"] },  ← Available
    { "date": "2026-07-03", "times": ["14:00"] }   ← Available
  ]
}

✅ Jul 1–3 each show a 14:00 slot → the room is free for a Jul 1–4 stay.
Note: slot times are LOCAL. In Asia/Kolkata (UTC+5:30), 14:00 local = 08:30Z — convert before booking.

POST /api/v1/bookings
X-API-Key: qs_live_xxxx
Content-Type: application/json

{
  "resource_id": "2f7157ca-3edf-4ef4-90c6-bb0a5ed87848",
  "service_id": "8b9e67d2-38ef-4171-aa31-50e5671192e8",
  "start_time": "2026-07-01T08:30:00Z",   // Check-in: Jul 1, 14:00 IST (08:30 UTC)
  "end_time": "2026-07-02T08:30:00Z",     // Check-out: Jul 2, 14:00 IST (08:30 UTC) — exactly 1440 min
  "customer_email": "[email protected]",
  "customer_phone": "+919876543210",
  "booking_metadata": {
    "guests": 2,
    "special_requests": "High floor room, extra pillows"
  }
}

Response:
{
  "id": "abc123-...",
  "status": "PENDING_PAYMENT",
  "payment_status": "PENDING",
  "total_amount": 2500.00,
  "checkout_url": "https://razorpay.com/pay/order_xxxxx"
}

→ Redirect guest to checkout_url to complete payment.
→ After payment, booking status auto-updates to CONFIRMED.
→ For a 3-night stay: make one booking per night, or use a 4320-min (3×1440) service booked Jul 1 14:00 → Jul 4 14:00.

GET /api/v1/availability?resource_id={doctor_id}&service_id={consult_service_id}&date=2026-06-29

Response:
{
  "resource_id": "8a7c293c-...",
  "service_id": "5b12a9e3-...",
  "timezone": "Asia/Kolkata",
  "slots": [{
    "date": "2026-06-29",
    "times": [
      "09:00",   // 9:00 AM – 9:30 AM (appointment)
      "09:40",   // 9:40 AM – 10:10 AM
      "10:20",   // 10:20 AM – 10:50 AM
      "11:00",   // 11:00 AM – 11:30 AM
      "14:00",   // 2:00 PM – 2:30 PM (afternoon session)
      "14:40",   // 2:40 PM – 3:10 PM
      "15:20"    // 3:20 PM – 3:50 PM
    ]
  }]
}

Note: The gap from 11:40 to 14:00 is the doctor's lunch break
(no availability rule defined for 12:00–14:00).

POST /api/v1/bookings
X-API-Key: qs_live_xxxx
Content-Type: application/json

{
  "resource_id": "8a7c293c-21a4-44b2-8c29-de98e11a2fcd",
  "service_id": "5b12a9e3-2e3b-47e1-88fc-8f7a8109d9f2",
  "start_time": "2026-06-29T03:30:00Z",   // 9:00 AM IST (03:30 UTC)
  "end_time": "2026-06-29T04:00:00Z",     // 9:30 AM IST (04:00 UTC)
  "customer_email": "[email protected]",
  "customer_phone": "+919876543210",
  "booking_metadata": {
    "symptoms": "Recurring headaches and mild fever for 3 days",
    "allergies": "Penicillin",
    "blood_group": "B+"
  }
}

Important: end_time = start_time + duration_minutes (30 min).
Do NOT add buffer_minutes to end_time — buffer only affects slot generation.

POST https://your-server.com/webhooks/Qssly
Content-Type: application/json
X-Qssly-Signature: sha256=a1b2c3d4e5f6...
X-Qssly-Idempotency-Key: booking-id:booking.confirmed:2026-07-01T14:00:00Z

{
  "event": "booking.confirmed",
  "timestamp": "2026-07-01T14:05:23Z",
  "data": {
    "id": "2f7157ca-3edf-4ef4-90c6-bb0a5ed87848",
    "resource_id": "room-uuid",
    "service_id": "service-uuid",
    "start_time": "2026-07-01T08:30:00Z",
    "end_time": "2026-07-04T05:30:00Z",
    "status": "CONFIRMED",
    "payment_status": "PAID",
    "total_amount": 7500.0,
    "amount_paid": 7500.0,
    "balance_due": 0.0,
    "location_timezone": "Asia/Kolkata",
    "customer_email": "[email protected]",
    "customer_phone": "+919876543210",
    "metadata": { "guests": 2 },
    "checkout_url": null,
    "provider_transaction_id": "pay_xyz12345"
  }
}

Events: booking.confirmed, booking.cancelled, booking.rescheduled, booking.no_show, booking.completed, booking.created

const crypto = require('crypto');
// Tip: Use a library like 'fast-json-stable-stringify' to properly sort keys recursively
const stringify = require('fast-json-stable-stringify'); 

function verifyWebhook(req, webhookSecret) {
  const signature = req.headers['x-Qssly-signature'];
  if (!signature) return false;

  const canonical = stringify(req.body);
  const expected = 'sha256=' + crypto
    .createHmac('sha256', webhookSecret)
    .update(canonical)
    .digest('hex');

  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch (e) {
    return false;
  }
}

import hmac, hashlib, json

def verify_Qssly_webhook(request_body: bytes, signature: str, secret: str) -> bool:
    """Verify the X-Qssly-Signature header."""
    payload = json.loads(request_body)
    canonical = json.dumps(payload, separators=(',', ':'), sort_keys=True).encode()
    expected = 'sha256=' + hmac.new(
        secret.encode(), canonical, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# Usage in Python Web Framework:
@app.post("/webhooks/Qssly")
async def handle_webhook(request: Request):
    body = await request.body()
    sig = request.headers.get("X-Qssly-Signature", "")
    if not verify_Qssly_webhook(body, sig, WEBHOOK_SECRET):
        raise HTTPException(status_code=400, detail="Invalid signature")
    
    payload = json.loads(body)
    event = payload["event"]  # "booking.confirmed", etc.
    booking = payload["data"]
    # Process the event...

GET /api/v1/payments/checkout-config/{booking_id}
X-API-Key: qs_live_xxxx

Response (200 OK):
{
  "key_id": "rzp_live_XXXXX",
  "amount": 50000,               // Amount in the smallest currency unit (paise)
  "currency": "INR",
  "order_id": "order_XXXXXX",
  "business_name": "Your Business Name",
  "customer_email": "[email protected]",
  "customer_phone": "+919876543210"
}

Note: the booking must be in PENDING_PAYMENT state with a Razorpay order
already initialized, otherwise this returns 400.

// 1. Include Razorpay SDK: <script src="https://checkout.razorpay.com/v1/checkout.js"></script>

// 2. Fetch config from Qssly
const configResponse = await fetch(`/api/v1/payments/checkout-config/${bookingId}`, {
  headers: { 'X-API-Key': 'qs_live_your_key' }
});
const config = await configResponse.json();

// 3. Setup Razorpay options
const options = {
  key: config.key_id,
  amount: config.amount,
  currency: config.currency,
  name: config.business_name,
  order_id: config.order_id,
  prefill: {
    email: config.customer_email,
    contact: config.customer_phone,
  },
  handler: async function (response) {
    // 4. Send verification payload to Qssly
    const verifyRes = await fetch('/api/v1/payments/verify-razorpay', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'qs_live_your_key'
      },
      body: JSON.stringify({
        razorpay_order_id: response.razorpay_order_id,
        razorpay_payment_id: response.razorpay_payment_id,
        razorpay_signature: response.razorpay_signature
      })
    });

    if (verifyRes.ok) {
      alert('Payment successful and booking confirmed!');
    } else {
      alert('Payment verification failed.');
    }
  }
};

// 5. Open checkout
const rzp = new window.Razorpay(options);
rzp.open();